本記事では、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にチェックを入れる（リポジトリへのアクセス権限）
-
Note: トークンの用途名（例:
- ページ下部の 「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
-
Mac (Homebrew):
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 等） が許可されているか確認してください。