issue109: 必須の環境変数が全 docker compose コマンドで必要な点を明記し .env による指定を案内する

[tichi73]

Fixes #109

背景

外部DBシングル構成 (single/extdb) で docker compose pull が以下のエラーで停止する、という問い合わせがあった。

error while interpolating x-required-db-env.DATABASE_URL: required variable DATABASE_URL is missing a value: ...

2026/07/10 リリースで導入した :? による必須化 (#98) が原因。docker compose は変数展開を compose ファイル読み込み時に一括で実施するため、up だけでなく pull / config / down / ps / logs などすべてのサブコマンドで発火する (pull が接続先に接続しているわけではなく、ファイルのパース段階で停止している)。ドキュメントはいずれも up の文脈でしか説明しておらず、README 自身の手順どおりに進めても必ずエラーになっていた。

変更内容

1. .env による指定を主手順にした (c5a614c / 2b288ff)

コマンドごとの前置き指定は実運用で現実的でないため、セットアップ手順の先頭で .env を用意する流れに改めた。以降の pull / up -d / down は素のコマンドのままでよい。

• Environment.md に「環境変数の指定方法」節を新設 (必須の環境変数の一覧 / 全コマンドで必要になる理由 / .env の書式と注意点)
• extdb・jobmngrd の README を .env 主手順に再構成し、前置き指定は「参考: .env を使わない場合」に集約
• .env / .env.bak.* を .gitignore に追加 (パスワードを平文で含むため。資格情報セットアップ支援スクリプト (init.sh) の導入 — 初期/再デプロイの簡便化と堅牢化 #104 からの先行取り込み)

.env の書式説明は Docker Compose v2.29.2 での実挙動を確認して記述している。シェルではなく compose が解釈するため、コマンド前置きでの指定とは扱いが異なる。

.env の記述	展開結果
DATABASE_URL=pgsql://u:pa$ss@h:5432/db	pgsql://u:pa@h:5432/db ($ss が変数参照として展開される)
DATABASE_URL=pgsql://u:pa$$ss@h:5432/db	$ はエスケープされて維持
DATABASE_URL='pgsql://u:pa$ss@h:5432/db'	クオートは除去され $ は維持
DATABASE_URL=pgsql://u:p@h:5432/db # comment	空白 + # 以降はコメントとして無視

2. cluster/swarm の DATABASE_URL 必須化を取り止めた (e9ae9f3)

本構成では setup_stack.sh が要否判定 (未指定なら DATABASE_HOST から既定値を組み立て、いずれも無ければエラー停止) を行なった上で docker-swarm.yml を生成する。compose ファイル側の :? はこれと重複しており、README の環境変数表の記述 (「未指定時は DATABASE_HOST からデフォルト値を構築します」) とも矛盾していた。また docker stack deploy には用いない docker compose pull まで停止させていた。

x-required-db-env と 3 サービスの <<: マージを削除し、#98 以前の状態に戻した。

extdb / jobmngrd で必須を維持したのは、未指定時のフォールバック先が内部コンテナ (postgres / rabbitmq) で、これらの構成には存在しないため。黙って起動すると名前解決エラーで kengine が再起動ループに入り、原因の分かりにくい失敗になる。

3. :? のエラーメッセージを改善した (26ac0f3)

README を読まずにコマンドを実行した場合、このメッセージが唯一の導線になるため、値の例だけでなく (1) up 以外でも必要であること (2) .env に書けば以後不要になること (3) Environment.md への誘導を含めた。

$ docker compose pull
error while interpolating x-required-db-env.DATABASE_URL: required variable DATABASE_URL is missing a value:
DATABASE_URL must be set. It is required by every docker compose command (pull, config, up, down, ...),
not only up. Recommended - write it in the .env file in this directory
(e.g. DATABASE_URL=pgsql://user:password@host:5432/dbname). See Environment.md for details

動作確認

環境変数・.env なしの状態で docker compose config -q / docker compose pull を実行:

構成	結果
ke2/single/extdb	改善後のメッセージでエラー停止
ke2/extra/jobmngrd	同上 (AMQP_URL)
ke2/cluster/swarm	通過 (緩和後。従来はエラー停止)
ke2/single/basic	通過

あわせて確認した項目:

• .env 作成後、extdb / jobmngrd で追加指定なしに config -q が通ること
• SHARED_DIR=... ./setup_stack.sh が docker-swarm.yml を生成でき、既定で DATABASE_URL=pgsql://kompira:kompira@host.docker.internal:9999/kompira、DATABASE_HOST=10.20.0.100 指定時に ...@10.20.0.100:9999/kompira になること (README の記述どおり)
• .env が git check-ignore で除外されること

補足

• RELEASE-NOTES.md は変更していない。 2026/07/17 節は当該リリース時点の事実を記述したものであり、2. の緩和で「swarm も必須」が成り立たなくなるため。既存の RELEASE-NOTES は全節がリリース単位で確定しており「未リリース」節の前例もないことから、本リリース分はリリース作業時に ChangeLog から起こす。
• 管理者マニュアル側にも対応する修正を用意している。 swarm ページの記述は本 PR のリリース後でないと正しくならないため、公開順序に注意が必要 (マニュアル側の issue に記載済み)。
• 資格情報セットアップ支援スクリプト (init.sh) の導入 — 初期/再デプロイの簡便化と堅牢化 #104 (init.sh 導入) との競合は 資格情報セットアップ支援スクリプト (init.sh) の導入 — 初期/再デプロイの簡便化と堅牢化 #104 側で解決する方針。 本 PR を先にリリースし、docker compose pull → ./init.sh の順序修正は既に 資格情報セットアップ支援スクリプト (init.sh) の導入 — 初期/再デプロイの簡便化と堅牢化 #104 ブランチへ入れてある。

[Copilot]

Pull request overview

This PR addresses issue #109 by clarifying that required environment variables in certain Docker Compose configurations are evaluated at compose-file load time, so they are needed for all docker compose subcommands (e.g., pull, config, down), and by recommending .env files as the primary way to provide them.

Changes:

• Add a new “環境変数の指定方法” section to Environment.md, documenting required variables and .env behavior/pitfalls.
• Update single/extdb and extra/jobmngrd READMEs to introduce .env setup before docker compose pull, and move per-command env examples into a “参考” section.
• Relax cluster/swarm by removing compose-level DATABASE_URL required checks and relying on setup_stack.sh validation; also ignore .env files via .gitignore.

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
ke2/single/extdb/README.md	Reorders setup to create .env first; explains “all subcommands need env” and adds a non-.env reference section.
ke2/single/extdb/docker-compose.override.yml	Improves required-var message for DATABASE_URL and documents why it affects all compose commands.
ke2/extra/jobmngrd/README.md	Reorders setup to create .env first; adds guidance and a non-.env reference section for AMQP_URL.
ke2/extra/jobmngrd/docker-compose.override.yml	Improves required-var message for AMQP_URL and documents load-time interpolation behavior.
ke2/cluster/swarm/docker-compose.override.yml	Removes compose-level DATABASE_URL requirement and adds rationale comments.
Environment.md	Adds consolidated documentation for required env vars and recommended .env usage, including parsing/escaping caveats.
ChangeLog	Records the documentation change and the swarm requirement relaxation for #109.
.gitignore	Ignores .env and .env.bak.* repository-wide to prevent accidental secret commits.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 7 out of 8 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

ke2/single/extdb/README.md:128

• カスタマイズ例のコマンドが DATABASE_URL の指定を含まないため、このセクションだけを参照して実行すると必須変数未指定でエラーになります（.env に設定済みである前提が明示されていません）。

この構成では、外部データベースへの接続情報として `DATABASE_URL` の指定が **必須** です（未指定の場合は `pull` を含むすべての docker compose コマンドがエラー停止します）。その他の環境変数は各構成で共通のため、[Environment.md](../../../Environment.md) を参照してください。カスタマイズした環境変数も `.env` に記述しておくことができます。

カスタマイズ例:

    $ AMQP_PASSWORD='strong-pw' KOMPIRA_LOG_DIR=/var/log/kompira docker compose up -d