環境構築で一日が溶けるのが怖かった僕が Docker Compose で 5 分起動の土台を固めた話

開発テンプレと再現性の設計

月曜の朝、新しいプロジェクトを始めようとして——気づいたら夕方だった。

コードは一行も書いていない。

Node.js のバージョンを確認して、PostgreSQL をインストールして、接続文字列を調べて、node_modules の依存関係でエラーが出て、また調べて。

そんな月曜が何度もありました。

フリーランスの仕事は、案件の隙間に個人開発を差し込むことが多い。

隙間は短い。

短い隙間が、環境構築だけで終わることがある。

珈琲が冷めた頃に気づく
——今日、コードを一行も書いていない（汗）

その感覚は、怠けとは違います。

意欲はあった。
時間もあった。
でも入口で詰まった。

これは、設計の問題です。

フリーランスとして案件をこなしながら、隙間時間で個人開発や note を書いている僕にとって、環境構築に一日が溶けるのは本当に怖いのです。

時間だけじゃない。

「また同じことをやっている」という自己嫌悪がくっついてくる。

——この記事は、その消耗から抜け出すために整えた、Docker Compose 開発テンプレの実験記録です。

「docker-compose up で動いた」という感動は、以前の記事に書きました。

今回はその先——コピーするだけで新プロジェクトが 5 分で始動する状態を作るまでの試行錯誤の記録です。

被験者は僕ひとり。
実験室は、いつもの仕事部屋と、いつもの Obsidian です。

動いたの先にある、 もう一段の問題

以前の記事で、Docker との最初の出会いと挫折を書きました。

あのチームプロジェクトで docker-compose.yml の魔法を体験してから、僕の開発スタイルは確かに変わりました。

環境を揃える苦労が、一つのファイルに閉じ込められる
——その体感は本物でした。

しかし、時間が経つにつれて、別の問題が顔を出してきたのです。

Docker の感動から、数週間が経った頃のことです。

チームの誰かが書いた docker-compose.yml を見ながら、自分のプロジェクト用に書き直す。
ネットで「Next.js Docker Compose」と検索して、コードをコピペして、動かなくてデバッグして、また調べる。

これは環境構築地獄の別バージョンでした。

Docker を使っているのに、依然として最初の 1 日が重い。

もし、自分がいつも使うスタックに最適化されたテンプレが手元にあったら——その考えが浮かんだのが、このテンプレ整備の出発点でした。

なんとなく動く設定を毎回書いていた

正直に言います。

最初に自力で書いた docker-compose.yml は、理解が甘いまま動いていました。

「とにかく動けばいい」で書いたファイルは、後で問題の温床になることがある——これを知ったのは、痛い目を見てからでした。

【ハマり ①】 node_modules が消えた

ホスト側のコードとコンテナを同期するために、ボリュームマウントを書きました。

volumes:
  - .:/app

これでコードが反映されてうれしかった。

でも、docker compose up したあと、なぜかローカルの node_modules が空になっている。

コンテナ内でインストールした node_modules が、ホスト側のディレクトリに上書きされてしまっていたのです。

node_modules だけを匿名ボリュームで分離する書き方を知らなかった。

volumes:
  - .:/app
  - /app/node_modules  # これが足りなかった

この一行の意味を理解するのに、丸一日かかりました。

【ハマり ②】 DB が起動する前に App が死んだ

depends_on を使えば DB より先に App が起動しない
——そう思っていました。

でも実際には、depends_on はコンテナの起動順序を制御するだけで、DB の中身が準備できるまで待ってくれるわけじゃないのです。

App が接続しに行ったとき、PostgreSQL がまだリクエストを受け付けられる状態になっていないと、接続エラーで App が落ちる。

depends_on に condition: service_healthy を追加して、ヘルスチェックを設定する必要がある
——そこまで理解するのに、何度か本番環境で泣きました。

【ハマり ③】 ホットリロードが効かない

ボリュームマウントでファイルを同期しているのに、コードを変更しても Dev サーバーが再起動しない。

macOS の Docker Desktop は、デフォルトでは inotify によるファイル変更検知が機能しないことがあります。

CHOKIDAR_USEPOLLING=true の環境変数を設定することで解決しましたが、この問題を知らなければ「なぜ反映されないんだ」と永遠にデバッグし続けることになります。

【ハマり ④】 .env の本番キーを git push した

.env ファイルに直接キーを書いていたとき、.gitignore の設定を誤って commit してしまったことがあります。

実害はなかったものの、冷汗が出ました。

それ以来、「.env.example を必ずリポジトリに入れて、.env は絶対に追跡しない」がテンプレのルールになりました。

.gitignore に .env を追加するのは当然として、git add のあとに git status で .env が含まれていないことを確認する習慣も一緒に身についています。

これは技術的な問題ではなく、人間的なミスの話ですが、テンプレに最初から防御策が組み込まれていれば、そのミスも減ります。

テンプレという発想に気づいた日

あるとき、案件の合間に個人プロジェクトを始めようとしたときのことです。

Obsidian のノートを開いて、過去に書いた docker-compose.yml を探しました。

ひとつは Node.js だけのやつ。
ひとつは MySQL を使ったやつ。
ひとつはポートフォリオサイトのやつ。

どれも、一度しか使っていない。
どれも、そのプロジェクト固有の設定が混ざっていて、そのまま使いまわせない。

「これ、毎回最初から書き直してるじゃないか」

気づいた瞬間に、少し笑いました。

Docker を使ってきた意味は何だったのか——。

でも、これは自分だけじゃないと思っています。

Docker の使い方は覚えた。
再利用しやすい形で整理するところまで、まだ届いていなかっただけなのです。

エンジニアとして 15 年のキャリアがあっても、テンプレを作るという習慣はある時期まで持っていませんでした。

毎回ゼロから組み立てる職人気質は、ときに誇りにもなる。

でもフリーランスの個人開発では、その職人気質が時間泥棒になることがある。

テンプレを作るのは、手を抜くことじゃない。

——そう考えを変えたのが転機でした。

そこから、自分の典型スタック専用テンプレを Obsidian に整備するという作業が始まりました。

テンプレさえあれば、新しいプロジェクトでやることはシンプルになります。

——それだけで開発が始まる状態を作る。

それが、今回の実験の核心でした。

【5 分起動を支える考え方】 再現性は優しさである

テンプレを作る前に、一つだけ考え方を整理しておきたいことがあります。

再現性、という言葉です。

技術的には同じ環境を再現できることという意味で使いますが、僕はもう少し広い意味で捉えています。

半年後、プロジェクトを再開しようとしたとき、環境のせいで動かなかったら——その悔しさは経験したことがある人なら分かると思います。

フリーランスは、複数のプロジェクトを並行して走らせることがある。

案件が一段落して、三ヶ月ぶりに個人プロジェクトを開いたとき、すぐに動き出せるかどうかで続けられるかどうかが変わります。

Docker Compose のテンプレを整えることは、コードの効率化ではなくて自分の継続性を守る行為なのです。

そう考えると、テンプレに手間をかける意味が少し違って見えてきませんか？

フリーランスという働き方は、体力や意志力だけで動かしているとどこかで限界が来ます。

僕はそれを、案件が重なった時期に経験しました。

忙しい週が続いたあと、個人開発に戻ろうとした瞬間に環境が壊れていることに気づいた。

Node.js のバージョンが上がっていて、コンテナが起動しない。

設定の意味を覚えていないから、何を直せばいいか分からない。

そのとき、整備されたテンプレがあれば、修正箇所が明確だった。

テンプレは記憶の代替品でもあるのです。

エンジニアとして 15 年、さまざまなツールと設定ファイルを経験してきました。

——その実感がテンプレという習慣に変わりました。

記憶に頼るより、Obsidian のノートに頼る。

ノートは裏切らないし、疲れないし、寝坊もしません。

ここまでが無料エリアでお伝えできる「なぜテンプレが必要か」の話です。

次のエリアでは、実際のテンプレの中身——ハマりポイントを潰した設定、.env の設計パターン、ホットリロードの修正、複数サービスを安全に繋ぐ書き方まで具体的に公開します。

僕の最小テンプレ全体像

ここからは、実際に僕が使っているテンプレを段階的に公開します。