【注意】こちら備忘録です
「誰かの力になれたら」とかではなく備忘録として書いています。
そのため見辛かったり情報の新旧・過不足などがあります。きっと。
🚀 AWS EC2に「Spring Boot + MySQL (Docker) + Next.js」をフルデプロイするまでに直面したエラーと解決策の全記録
所有者エラー・Dockerの仕様・Next.jsの本番ビルド制限・無料枠EC2のメモリ不足（ハングアップ）といった「定番の壁」の乗り越え方とロードマップを、トラブルシューティングの記録としてまとめた。
1. 登場した重要キーワード（単語帳）
- SCP (Secure Copy Protocol)：ローカルPCからリモートサーバー（EC2）へ、SSHを利用して安全にファイルやフォルダを転送する仕組み。
- chown (Change Owner)：Linuxにおいて、ファイルやディレクトリの「所有ユーザー」や「所有グループ」を変更するコマンド。
-
Docker Entrypoint Initdb：MySQL公式コンテナの仕様。
/docker-entrypoint-initdb.dに置かれたSQLファイルは、コンテナの初回起動時のみアルファベット（名前）順で自動実行される。 -
Docker Compose：複数のコンテナ（今回ならMySQLなど）の設定を
docker-compose.ymlにまとめ、コマンド一発で一括管理・起動するツール。 -
Suspense (React/Next.js)：コンポーネントの読み込みが完了するまで、代わりにローディング画面（
fallback）を表示して処理を待機させる仕組み。 -
CSR Bailout (Client-side Rendering Bailout)：Next.jsの仕様。本番ビルド（サーバー側）時に、ブラウザ専用の機能（
useSearchParamsなど）をそのまま使うと、ビルドエラー（Bailout）を起こす現象。 - 仮想メモリ（スワップ領域）：本物のメモリ（RAM）が不足した際、ハードディスク（SSD）の一部をメモリの代用として借用し、システムのフリーズ（ハングアップ）を防ぐ仕組み。
2. 多用したLinux・ネットワークコマンド一覧
📂 ファイル転送・確認
# ファイルをEC2のホームに送信（ローカルのPowershellで入力）
scp -i <鍵> <送りたいファイル> ec2-user@<IP>:~
# フォルダを中身ごと丸ごと（再帰的：-r）送信（ローカルのPowershellで入力）
scp -i <鍵> -r <送りたいフォルダ> ec2-user@<IP>:~
# ファイルの一覧を、権限、所有者、更新日時（タイムスタンプ）付きで詳細表示（SSH連携をしているターミナル上で入力）
ls -l
# ファイルの中身をターミナル画面上に展開して確認（SSH連携をしているターミナル上で入力）
cat <ファイル名>
👑 権限・所有者変更（王様コマンド）
# フォルダの所有者を root から一般ユーザー ec2-user に変更
sudo chown ec2-user:ec2-user <フォルダ名>
🐳 Docker・Docker Compose操作
# 設定ファイルを元に、バックグラウンド（裏側：-d）でコンテナを起動
docker compose up -d
# コンテナを停止し、同時にボリューム（データ：-v）も完全消去して初回状態にリセット
docker compose down -v
# 現在稼働しているコンテナの生存・起動ステータス（STATUS）を確認
docker compose ps
# コンテナの内部ログを表示し、エラーの原因を特定
docker logs <コンテナ名>
⚡ 仮想メモリ（スワップ）追加（EC2フリーズ強制突破）
# ① 2GB分の空っぽのファイルを生成
sudo dd if=/dev/zero of=/swapfile bs=1M count=2048
# ② 管理者以外触れないようにロック
sudo chmod 600 /swapfile
# ③ スワップ領域として初期化
sudo mkswap /swapfile
# ④ 仮想メモリを有効化し、メモリを 1GB ➔ 実質3GB へ増強
sudo swapon /swapfile
# 現在の本物メモリとスワップメモリの残量を人間が見やすい形式（-h）で表示
free -h
3. トラブルと解決の手順
データベース構築
① ディレクトリの権限エラー (Permission denied)
-
現象：
mkdirで作ったmysql-initフォルダにSQLが送信できない。 -
原因：フォルダの所有者が
rootになっていたため、一般ユーザーec2-userでの書き込みが拒否された。 -
解決：
sudo chownを行い、個人(ユーザー)もチーム(グループ)もec2-userの所有に変更して解決。
② SQL自動実行順序の罠 (Table doesn't exist)
-
現象：
docker logsを見ると、テーブル作成前にデータ挿入が走りエラーに。 -
原因：Docker内のSQLはアルファベット順に動くため、
data.sqlがschema.sqlより先に動いていた。 -
解決：
mvコマンドで01_schema.sql、02_data.sqlへ改名。一度作成されたコンテナは初期化が走らないため、docker compose down -vでボリュームを完全リセットして再起動し、解決。
フロントエンドビルド・送信
① Next.js本番ビルドのエラー (Missing Suspense with CSR Bailout)
-
現象：ローカルでの
npm run buildが/formationや/support-cardsで落ちる。 -
原因：URLパラメータを扱う
useSearchParams()が使われているパーツが<Suspense>で囲まれていなかった。 -
解決：
-
/formationページ：親ファイル側で、該当コンポーネントを<Suspense>タグでサンドイッチした。 -
/support-cardsページ：ページ直下で使われていたため、メイン処理を丸ごと別関数（子コンポーネント）へ切り出し、最下部に作った新しい入り口から<Suspense>で包み込んで呼び出す構造へ変更し、ビルド成功。
-
② 無料枠EC2のハングアップ（恐怖のフリーズ）
-
現象：EC2上で
npm installを実行中、プロンプトが完全に無反応に。 - 原因：無料枠EC2のメモリ（1GB）をNext.jsが使い切り、OSごとパンクした。料金的な課金ではなくハードウェアの限界。
- 解決：一度Tera Termを強制終了してログインし直し、ハードディスク領域を借用する「スワップ領域（仮想メモリ）」を2GB追加して実質3GB環境を構築。リトライして無事突破。
4. まとめ
ここまで見てくれた方へ。
MySQLの文字化けはとても厄介。