「環境構築って、なんでこんなに難しいの？」
「エラーが出て先に進めない。自分だけできないのでは？」
そう不安に感じている方も多いのではないでしょうか。
先日、新しいプロジェクトに途中から参画し、
実際の手順書を見ながら環境構築をしました。
結論から言うと、環境構築は難しいです。
研修では1時間ほどで終わっていた準備が、実務では手順書が3ファイル・25シートあり、
画面が表示されるまでに約5日かかりました。
ただ、新人がつまずくのは普通のことです。
この記事では、実際のプロジェクトの手順書をもとに、環境構築の流れを実体験をもとに紹介します。
結論｜環境構築は難しい。新人がつまずくのは普通のこと
環境構築が難しいのは、
設定する項目やツールがとにかく多く、
しかも手順書どおりにいかないことがあるからです。
私の場合、Gradleのビルドエラーは、
情報系出身の上司に画面共有で見てもらっても、
その場では解決できませんでした。
経験のある人でも、すぐに原因が分からないことがあるのが環境構築です。
なので、エラーが出ても「自分だけができない」と思う必要はありません。
エラー文を読む、AIに聞く、早めに相談する。
これを繰り返していけば、最後には画面が表示されます。
環境構築とは？実務で最初にやる「開発の準備」
環境構築とは、自分のPCでプログラムを動かしたり、
開発・テストしたりできるように準備することです。
必要なツールを入れて、設定をして、ソースコードを取ってきて、
実際に動くところまで持っていきます。
研修は1時間、実務は手順書24シート・約5日間
研修でも環境構築はしましたが、最低限の設定でよかったので、
1時間ぐらいで終わっていました。
一方、実務では設定がめちゃくちゃ多いです。
今回のプロジェクトでは、手順書が次の3つに分かれていました。
| 手順書 | シート数 |
|---|---|
| フロント環境構築手順書 | 15 |
| バックエンド環境構築手順書 | 9 |
| BFF設定手順 | 1 |
| 合計 | 25 |
バックエンドの手順書は、私の直属の上司が作ったものです。
情報系卒の3年目くらいの方で、ある程度経験豊富です。
かかる時間はプロジェクトによって違います。
社内システムの案件だと半日～1日で終わりますが、
お客様から請け負う案件だと2～3日かかることもあります。
今回はお客様の案件で、画面内結合テストの準備までを含めて約5日かかりました。
※研修の様子は、
Java研修についていけない？文系・未経験で受けた新卒エンジニアが実体験を解説、
SQLは初心者には難しい？文系・未経験で研修を受けた実体験を解説
で紹介しています。
今回のプロジェクトで使ったツール一覧
今回の環境構築で使ったツールは、次のとおりです。
| ツール | 役割 |
|---|---|
| Git・GitLab | ソースコードの取得や管理 |
| WSL2 | Windows上でLinux環境を使う |
| Rancher Desktop | Dockerコンテナを動かす環境 |
| Docker | アプリやDBなどをコンテナで起動する |
| JDK（Amazon Corretto） | Javaの開発・実行環境 |
| Gradle | Javaプログラムのビルド |
| NVM・Node.js | Node.jsのバージョン管理や実行 |
| Cursor | ソースコードの編集・ターミナル操作 |
| A5:SQL Mk-2 | データベースの中身を確認・操作する |
| curl | APIの動作確認 |
これだけのツールを、一つずつ入れて設定していきます。
名前を聞いたことがないツールもあり、
最初は「これは何をするものなんだろう」という状態でした。
フロント・BFF・バックエンドの関係
今回のシステムは、大きく次の4つでできています。
- フロントエンド：Next.js（Reactベース）。ユーザーが見る画面
- BFF：フロント側のNode.js環境で動くAPI処理。
画面とバックエンドの間に入って、やり取りを仲介する
- バックエンド：Java、Spring Boot、Gradle。データの処理を担当する
- データベース：PostgreSQL。データを保存する
データの流れは、次のようなイメージです。
画面（Next.js） → BFF → バックエンド（Spring Boot） → データベース（PostgreSQL）
環境構築のゴールは、この4つを自分のPC上ですべて動かし、つなげることです。
どこか1つでも設定がずれていると、画面にデータが表示されません。
実際の環境構築の流れ｜手順書8ステップ
まず、今回のプロジェクトで実際にどう進んだかを、日ごとにまとめます。
| 日付 | やったこと |
|---|---|
| 10月12日 | 新しいプロジェクトに参画。プロジェクト説明書の読み込み |
| 10月13日 | WSL2、JDK、Git、SSH鍵などの初期設定（コンテナ実行のための環境準備） |
| 10月14日 | Gitのクローンに成功（Cursor上にプロジェクトのコードが表示された！）。Gradleビルドでエラー |
| 10月15日 | ビルドが通る。フロント環境の準備（NVM、プラグイン）。BFFの設定（画面を表示させるためのポート番号など） |
| 10月16日 | 画面内の動きに限定した結合テストの準備 |
ここからは、手順書の流れを8つのステップに分けて紹介します。
①WSL2・Rancher Desktop｜コンテナを動かす準備
最初に、Dockerコンテナを動かすための環境を準備します。
WSL2は、PowerShellで次のコマンドを実行してインストールします。
手順書にも「かなり時間がかかる」と書かれていました。
wsl --install
次に、Dockerを動かすためのRancher Desktopをインストールします。
②JDK・Node.js・Cursor｜開発ツールの導入
次に、開発に必要なツールを入れていきます。
**JDK（Amazon Corretto）**は、インストールしたあとに環境変数の設定が必要です。
「JAVA_HOME」にインストール先のフォルダを設定し、
「PATH」に %JAVA_HOME%\bin を追加します。
PCを再起動したあと、PowerShellで次のコマンドを打って
バージョンが表示されればOKです。
java -version
Node.jsは、NVMというツールを使って入れます。
NVMを使うと、Node.jsのバージョンを切り替えられるので、
チーム全員で同じバージョンにそろえられます。
nvm install 〇〇（バージョン）
nvm use 〇〇（バージョン）
node --version
手順書には、
「すでにNode.jsが入っている場合は、先にアンインストールしてから実施すること」
という注意書きもありました。
Cursorは、AIが使えるコードエディタです。
VS Codeがベースになっていて、Javaやコードチェック（ESLint）、
フォーマット（Prettier）などのプラグインも入れていきます。
③Git・SSH・ソースコード取得
ツールがそろったら、GitLabからソースコードを取ってきます。
そのためには、まずSSH鍵の設定をして、GitLabに認証を通す必要があります。
認証が通ったら、次のようなコマンドでリポジトリをクローン（コピー）します。
git clone ssh://git@（GitLabのURL）/（リポジトリ名）.git
クローンに成功し、Cursorのエディタ上にプロジェクトのコードが表示されたときは、
「やっとスタートラインに立てた」という気持ちでした。
ただ、このSSHの設定は、今回一番苦戦したポイントの一つです。
詳しくは後ほど紹介します。
④環境変数の設定｜.env.localで「どこにつなぐか」を教える
次に、環境変数の設定をします。
今回は、フロント側に「.env.local」というファイルを作って、各サービスの接続先を書き込みました。
例えば、BFFに対して「バックエンドは8080番ポートにあるよ」と教えるには、
次のように書きます。
BACKEND_API_URL=http://localhost:8080
ほかにも、次のような項目を設定しました。
| 設定項目 | 何を設定する？ |
|---|---|
| NEXTAUTH_URL | ログイン認証で使用するURL |
| COGNITO_ENDPOINT | 認証サービスの接続先 |
| NEXT_PUBLIC_BFF_BASE_URL | フロントからBFFへの接続先 |
| BACKEND_API_URL | BFFからバックエンドへの接続先 |
| REDIS_URL | Redisへの接続先 |
ここで1文字でも間違えると、画面とバックエンドがつながりません。
⑤Gradleビルド
次に、Java側のプログラムをビルドします。
ビルドとは、書かれたソースコードを、実際に動かせる形にまとめる作業です。
今回のプロジェクトでは、
共通部品（common）、バックエンド（backend）、バッチ（batch）の3つに分かれていて、
それぞれ次のようなコマンドでビルドします。
./gradlew :〇〇-common:build -x test
./gradlew :〇〇-backend:build -x test
./gradlew :〇〇-batch:build -x test
すべて「BUILD SUCCESSFUL」と表示されれば完了です。
……なのですが、私はここで丸1日止まりました。
⑥⑦Dockerコンテナ起動とAPI・DBの接続確認
ビルドが通ったら、Dockerでバックエンドや関連サービスを起動します。
プロジェクトのフォルダで、次のようなコマンドを実行します。
docker compose up -d --build backend
起動したら、ちゃんと動いているかを確認します。
APIの確認は、curlを使います。次のコマンドを打って、正常な応答が返ってくればOKです。
curl http://localhost:8080/actuator/health
データベースの確認は、A5:SQL Mk-2を使います。
PostgreSQLを選んで、サーバー名やポート番号などの接続情報を入力し、
テスト接続が成功すれば完了です。
⑧フロント・BFF・バックエンドをつなぐ
最後に、画面内結合テストをするために、フロント・BFF・バックエンドをすべてつなげます。
すべて起動したら、ブラウザでローカルのURL（http://127.0.0.1:3000/）を開きます。
ログイン画面が表示され、ログインして画面が動けばゴールです。
画面が表示されたときは、めちゃくちゃ嬉しかったです。
自分では何も作っていないのに、何かアプリを作り上げた感がありました。
新人エンジニアが苦戦したポイント
ここからは、今回の環境構築で実際に苦戦したポイントを紹介します。
Gradleビルドが通らない
一番時間がかかったのは、Gradleビルドです。
ビルドを実行するとエラーが出て、先に進めなくなりました。
上司に画面共有で見てもらいながら原因を探しましたが、
その日は結局解決できませんでした。
ところが、次の日にもう一度確認したら、なぜかビルドが通りました。
原因として考えているのは、次の2つです。
- 別のプロジェクトのコンテナを起動させたままだった：
それと競合してしまったのではないかと考えています
- 開発中のコードがおかしかった：
プロジェクトはまだ製造の途中で、プログラムが日々修正されています。
どこかのファイルのコードに問題があった可能性もあります
経験のある上司でもすぐには分からなかったので、
「環境構築のエラーは、誰でもつまずくものなんだ」と少し安心した部分もあります。
GitLabへのSSH接続の手順が、別の場所にあった
GitLabへのSSH接続の設定も、時間がかかりました。
原因は、SSHの設定手順が今回の手順書に載っていなかったことです。
Gitの設定手順は、別のSharePointの中にありました。
それを見つけるのに苦労しました。
実務の手順書は、すべてが完全に整っているわけではありません。
足りない部分は、自分で探して進める力が求められます。本当に。
コードが変わっていて、スクショどおりにできない
手順書どおりにやったのに、うまくいかない場面もありました。
プロジェクトのコードが手順書を作った時点から変わっていて、コードを修正する作業が、
手順書のスクリーンショットどおりにならなかったのです。
そのときは、Cursorに入っているAIに聞きながら、
「たぶんこうだろう」と推測して進めるしかありませんでした。
作業するブランチ・コミットしていいかが分からない
私はコードをいじる担当ではないので、Gitで大きく困ったことは基本的にありません。
ただ、最初は「どのブランチで作業していいのか」が分かりませんでした。
また、テストコードを作ったあとに、
「これはコミットしていいのか」と不安になることもありました。
途中から参画したので、聞ける人が少ない
一番不安だったのは、気持ちの面です。
私はプロジェクトに途中から配属されたので、止まったときに聞ける人が少なかったです。
他のメンバーはすでに環境構築を終えていて、自分と同じ状況になっている人がいません。
それが本当に不安でした。
環境構築でエラーが出たときの対処法
ここでは、私が実際にやっていた対処法と、手順書に書かれていた対処法を紹介します。
エラー文の一番下と「error」の文字を探す
エラーが出たら、まずエラー文を読みます。
エラー文は長いことが多いですが、一番下の行や「error」という文字を探すのが重要だと思います。
そこに原因のヒントが書かれていることが多いです。
エラー文をAI（Cursorのエージェント）に貼って聞く
エラー文を読んでも分からないときは、AIに聞きます。
今回はCursorを使っていたので、
エディタに入っているAIエージェントにそのまま聞いていました。
リモートなら早めに相談して、画面共有で見てもらう
それでも解決しないときは、上司に相談します。
私の会社はリモートワークなので、周りから自分の状況が見えません。
なので、状況が分かるように、早めに聞くようにしていました。
言葉だけで説明するのは難しいので、画面共有で一緒に見てもらうのがおすすめです。
※リモートワークの様子は、
エンジニアのリモートワークはどんな感じ？新卒1年目の実体験を紹介
で紹介しています。
再起動とポートの確認を試す
手順書の「開発中に困ったときのメモ」というシートには、
よくあるトラブルの対処法がまとめられていました。
例えば、次のようなものです。
- Dockerがおかしいとき：Rancher Desktopを一度終了して、再起動する
- 古いプロセスが残っていて、修正が反映されないとき：
netstat -ano | findstr :3000で、ポートを使っているプロセスを確認して終了する
- CursorのターミナルでNode.jsのコマンドが効かないとき：CursorやPCを再起動する
私のビルドエラーも、別プロジェクトのコンテナとの競合が原因だったとしたら、
起動中のコンテナやポートを先に確認していれば、もっと早く気づけたかもしれません。
環境構築を通して学んだこと
画面が表示されたときは「アプリを作った感」があって嬉しい
すべて起動して画面が表示されたときは、めちゃくちゃ嬉しかったです。
自分では何もしていないのに、何かアプリを作り上げた感がありました。
エラーで止まっていた時間が長かった分、達成感も大きかったです。
ツールごとにできることが分かった
今回の環境構築で、「こんなツールがあって、こんなことができるんだ」と勉強になりました。
WSL2やRancher Desktop、NVMなど、
研修では触らなかったツールも多かったです。
実際に手を動かしたことで、名前と役割が少しずつ結びつくようになりました。
システムの全体像は、3、4回やると分かってくる
正直、システムの全体像まではまだ分かっていません。
ただ、同じような環境構築を3、4回やれば、全体像が分かってくると思います。
1回目は、手順書どおりに進めるだけで精一杯でいいのだと感じています。
上司はAIなしで原因を推測していた。自分もそうなりたい
一緒にエラーを見てもらったとき、上司はAIに聞かなくても、
エラーの原因を推測していました。
私はまだAIに頼りっぱなしなので、自分も早くそうなりたいと思っています。
環境構築に関するQ&A
環境構築にはどのくらい時間がかかる？
プロジェクトによって違います。
私の会社の場合、社内システムの案件なら半日～1日で終わります。
一方、お客様から請け負う案件だと、2～3日かかることもあります。
テストをするためだけなら、1日以内で終わることが多いです。
今回の私は、プロジェクトの説明書を読む日や、ビルドエラーで止まった日も含めて、
約5日かかりました。
Javaの環境構築は難しい？
最初は難しいと思います。
JDKを入れるだけでなく、JAVA_HOMEやPATHといった環境変数の設定が必要だからです。
さらに、Gradleでのビルドでもエラーが出ることがあります。
ただ、手順書どおりに一つずつ進め、
確認しながら進めれば、ちゃんと動かせます。
ReactやDockerの環境構築も難しい？
React（今回はNext.js）は、Node.jsのバージョンをチームでそろえる必要があり、
NVMの設定や npm install などの作業があります。
Dockerも、Rancher Desktopが起動しない、
ほかのコンテナと競合するなど、つまずくポイントがあります。
どちらも最初は難しいですが、ツールを1つずつ入れること自体は、
手順書どおりに進めれば大きく詰まることはありませんでした。
私の場合は、ビルドやポート番号の設定など、
ツール同士が関わる部分でつまずくことが多かったです。
環境構築が苦手でも、エンジニアを続けられる？
続けられると思います。
経験のある上司でも、すぐに原因が分からないエラーはあります。
環境構築でつまずくのは、新人なら普通のことです。
大事なのは、エラーが出たときに一つずつ原因を確認すること、
そして早めに相談することです。
回数を重ねれば、少しずつ慣れていくと思います。
※新卒1年目の仕事内容は、新卒エンジニア1年目は何をする？文系・未経験で入社して半年間の実体験を紹介で紹介しています。
まとめ｜環境構築は、原因を一つずつ確かめれば必ず進む
環境構築は、ツールや設定項目が多く、
手順書どおりにいかないこともあるので、難しいです。
私も、研修では1時間で終わっていた準備に、実務では約5日かかりました。
ただ、エラーが出ても、エラー文を読む、AIに聞く、早めに相談するを繰り返していけば、
最後には画面が表示されます。
そのときの達成感は、本当に大きいです。
これから環境構築をする方へのアドバイスは、「とにかくやってみるしかない」です。
どんな操作をしたらこうなったのかを説明できるように、
慎重に進めてみてください。
この記事が、環境構築に不安を感じている方の参考になれば幸いです。
コメント