本記事では、AWS EC2 インスタンスに SSM Session Manager で接続し、Node.js v20 をセットアップした上で、Git Sparse Checkout を利用して Next.js (frontend) アプリケーションをデプロイ・PM2で常時起動するまでの手順を解説します。

🛠️ 事前準備（セットアップ編）

デプロイ作業を始める前に、必要なアクセス権限・トークン・実行環境を整えます。

Step 1: GitHub の Personal Access Token (PAT) を発行

リポジトリからコードを取得（git clone）するためのアクセスキーを発行します。

GitHub にログインし、右上のプロフィールアイコン ➔ 「Settings」 を開きます。
左サイドバー最下部の 「Developer settings」 をクリックします。
「Personal access tokens」 ➔ 「Tokens (classic)」 を選択します。
「Generate new token」 ➔ 「Generate new token (classic)」 をクリックします。
以下の項目を設定します：
- Note: トークンの用途名（例: ec2-deploy-token）
- Expiration: 有効期限（推奨: 30日〜90日）
- Select scopes: repo にチェックを入れる（リポジトリへのアクセス権限）
ページ下部の 「Generate token」 をクリックします。
表示されたトークン（ghp_...）をコピーして大切に保管します。
※画面を閉じると二度と表示されません。

SSH 鍵や 22 番ポートを開放せずに、AWS CLI を使ってローカルターミナルから安全に EC2 へ接続します。

1. ローカル PC の事前準備（初回のみ）

ローカル端末に AWS CLI と Session Manager プラグイン がインストールされ、認証情報が設定されていることを確認します。

AWS CLI 認証設定: aws configure で Credentials が設定されていること
Session Manager プラグイン: 未インストールの場合はインストールしてください。
- Mac (Homebrew): brew install --cask session-manager-plugin
- Windows (Chocolatey): choco install awscli-sessionmanagerplugin

2. セッションの開始

ターミナルから以下のコマンドを実行して EC2 に接続します。（<INSTANCE_ID> を対象の EC2 インスタンス ID に置き換えてください）

aws ssm start-session --target <INSTANCE_ID>

3. 接続ユーザーの確認

接続後、シェル上の初期ユーザーが ssm-user であることを確認します。

whoami
# 出力結果が ssm-user であることを確認

Step 3: Node.js v20 のインストール

EC2 上に Node.js バージョン 20（LTS）をインストールします。

# NodeSource から Node.js 20.x のリポジトリをセットアップ
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -

# Node.js と npm をインストール
sudo dnf install -y nodejs

# バージョン確認（v20.x.x と表示されることを確認）
node -v
npm -v

🚀 アプリケーションデプロイ（実践編）

環境が整ったら、Next.js アプリケーションのデプロイを進めます。

1. デプロイ用ディレクトリの作成と権限設定

SSM のシェル環境では $USER 変数が正しく展開されないことがあるため、ユーザー名（ssm-user）を明示的に指定します。

# ディレクトリ作成
sudo mkdir -p /var/www/sample

# 所有者を ssm-user に変更
sudo chown -R ssm-user:ssm-user /var/www/sample

# 移動
cd /var/www/sample

2. Git Sparse Checkout で `frontend` だけを取得

リポジトリ全体ではなく、必要な frontend フォルダのみを取得します。

# 一時ディレクトリにクローン（<YOUR_GITHUB_TOKEN> やユーザー名等を置き換えて実行）
git clone --no-checkout --depth=1 https://<YOUR_GITHUB_TOKEN>@github.com/<YOUR_GITHUB_USER_NAME>/<YOUR_REPOSITORY_NAME>.git temp

# 一時ディレクトリに移動
cd temp

# Sparse Checkout を有効化
git sparse-checkout init --cone
git sparse-checkout set frontend

# ファイルをチェックアウト
git checkout

# frontend の中身を親ディレクトリ（/var/www/sample）に移動
mv frontend/* ../

# 一時ディレクトリを削除してクリーンアップ
cd ..
rm -rf temp

3. ファイル権限の再設定（重要）

Git 操作時にファイル所有権が変わる場合があるため、再度 ssm-user に権限を付与します。これを忘れると後の npm install やビルド時にエラーとなります。

sudo chown -R ssm-user:ssm-user /var/www/sample

4. 環境変数の設定（`.env.local`）

Next.js が読み込む環境変数ファイルを作成します。

nano .env.local

エディタが開いたら、必要な環境変数を記述します。

# 記述例
NEXT_PUBLIC_API_URL=https://your-backend-api.com
DATABASE_URL=your_database_url

エディタの操作方法:
Ctrl + O ➔ Enter（保存） ➔ Ctrl + X（終了）

5. 依存関係のインストールとビルド

環境変数を反映させて、Next.js をプロダクション用にビルドします。

# 依存パッケージのインストール
npm install

# プロダクションビルド
npm run build

6. アプリケーションの常時起動（PM2 導入）

ターミナルを閉じてもアプリが停止しないよう、プロセス管理ツールの PM2 で常時起動させます。

# PM2 をグローバルインストール
sudo npm install -g pm2

# Next.js を PM2 で起動
pm2 start npm --name "sample" -- start

# OS 再起動時に自動起動するよう設定を保存
pm2 startup
pm2 save

7. 動作確認

アプリが正常に起動しているか確認します。

# プロセスの状態確認
pm2 status

# リアルタイムログの確認（ログの終了は Ctrl + C）
pm2 logs sample

ブラウザから http://<EC2のパブリックIP>:3000 にアクセスし、画面が表示されればデプロイ完了です！

💡 トラブルシューティング

Permission denied エラーが出る場合:
必ず sudo chown -R ssm-user:ssm-user /var/www/sample を実行して所有権を修正してください。
node コマンドが見つからない・バージョンが古い場合:
「Step 3: Node.js v20 のインストール」の手順を再実行し、node -v で v20.x.x になっているか確認してください。
ポート 3000 にアクセスできない場合:
EC2 のセキュリティグループで「インバウンドルール」に カスタム TCP / ポート 3000（ソース: 0.0.0.0/0 等） が許可されているか確認してください。