Laravel → Docker → GHCR → Coolify
ターゲット構成:イメージは開発者のマシンでビルドされ、ghcr.ioにプッシュされ、サーバー(Coolify)はコンポーズ・ファイルを介してそれをプルして実行するだけです。サーバー上でのビルドは行わず、イメージ内にシークレットは含まれず、すべての設定は環境変数から行われます。
workstation ── docker buildx (linux/amd64) ──push──▶ ghcr.io/<owner>/<repo>:latest,:<sha>
│ pull
server (Coolify) ── docker-compose.prod.yml ──▶ app (nginx+php-fpm :8080) · worker · [scheduler] · db
バンドルファイル(コピーして適応;プレースホルダーは__IMAGE__のような形式):
| パス | 用途 |
|---|---|
scripts/inspect_laravel.py <dir> | 読み取り専用のプロジェクトスキャン→JSONファクト。最初に実行します。 |
scripts/repair_npm_lock.py <dir> | Linuxネイティブバイナリ不足のpackage-lock.jsonを修正します(Dockerが必要)。 |
assets/Dockerfile | serversideup/php:<ver>-fpm-nginxベースのマルチステージイメージ。 |
assets/dockerignore | .dockerignoreとして保存。 |
assets/docker-compose.prod.yml | app + worker + (scheduler) + mysql。Coolifyが参照するファイル。 |
assets/docker-compose.prod.local.yml | ワークステーション用オーバーライド::8080を公開、セキュアクッキー無効。 |
assets/env.docker.example | .env.docker.exampleとして保存。ローカルおよびCoolify環境変数のテンプレート。 |
assets/docker-build-push.sh | scripts/docker-build-push.shとして保存。amd64をビルドし、latest + git SHAをプッシュ。 |
references/variants.md | Postgres/MariaDB、Redis、Horizon、Reverb、Octane、SSR、Wayfinder、pnpm/yarn/bun、Chromium、SQLite-only。 |
references/coolify.md | サーバー上のGHCR認証、リソース作成、ドメイン:8080、デプロイ/更新/ロールバック。 |
references/other-platforms.md | Dokploy、EasyPanel、CapRover、通常のDocker + Caddy、Kubernetesに関するメモ。 |
references/troubleshooting.md | 症状→原因→修正テーブル。何か失敗したときに参照。 |
references/docs-template.md | プロジェクト用に作成するdocs/DOCKER_DEPLOYMENT.mdのアウトライン。 |
ユーザーが質問や障害(完全なセットアップではない)のみを持っている場合は、全ワークフローを実行する代わりに、直接references/troubleshooting.mdまたは該当するリファレンスに進んでください。
ワークフロー
1. プロジェクトを調査する
python3 <skill-dir>/scripts/inspect_laravel.py <project-dir>
イメージとスタックを決定するファクトを報告します。注意深く読んでください — 各フィールドは決定に対応しています:
php.allowed— ロックされたパッケージがすべて受け入れるPHPマイナーバージョン。ベースイメージタグには許可された最高バージョンを選択します。空の場合、ロックは単一バージョンでは満たせません;どのパッケージがブロックしているかをユーザーに伝えます(php.blocked_by)。単にcomposer.jsonが^8.2と書いてあるからといってバージョンを選ばないでください:推移的パッケージ(例:openspout~8.2||~8.3||~8.4、Symfony 8>=8.4.1)がそれを狭め、推測が間違っているとビルドが後で失敗します。extensions.install_on_serversideup—install-php-extensionsに正確に入れるもの。gmp/bcmathはWebプッシュのために一緒に現れます;両方インストールしても問題ありません。extensions.system_binaries— OSバイナリが必要なパッケージ(Chromium、wkhtmltopdf、ffmpeg)。コードが実際にそれらを使用しているかをイメージを肥大化させる前に確認してください(クラスをgrep);使用されている場合はreferences/variants.mdを参照。queues—needs_workerとworker_queue_arg。ワーカーの--queue=はすべての名前付きキュー(onQueue、$queue、viaQueues()から)をリストアップする必要があります。そうしないと、それらのジョブはテーブルに永久に残り、デフォルトキュー・ワーカーは正常に見えます。scheduler.has_scheduled_tasks→schedulerサービスを追加。packages.key_packages→ Horizonはワーカーを置き換え;ReverbはWebSocketサービスを追加;Octaneはベースイメージを変更(バリアントを参照)。database— コンポーズDBサービスのドライバ。config_defaultはしばしばsqliteであることに注意:コンテナ内でDB_CONNECTIONが設定されていない場合、Laravelは静かにSQLiteを使用します。そのため、コンポーズファイルは明示的に設定します。frontend.npm_lock_missing_linux_binaries— 空でない場合、npm ciがLinuxで失敗することを意味します。repair_npm_lock.pyを実行します(ステップ3)。frontend.vite_needs_php_at_build— WayfinderなどはViteビルド中にPHPが必要です;バリアントを参照。proxy.bootstrap_trustProxies/legacy_TrustProxies_middleware— ステップ3のプロキシ修正が必要かどうか。git.ghcr_image— イメージ名(GHCRは小文字を要求)。existing_files— 既存のdocker-compose.yml(多くの場合Sail開発用)を上書きしない;本番ファイルはdocker-compose.prod.yml。
また、スキャンで判断できないコードもざっと確認してください:起動時にDBにアクセスするプロバイダ(ビルド中のcomposer dump-autoload / optimizeを壊す)、自身のURLをfile_get_contents(asset(...))するコード、ハードコードされたstorage_pathの仮定。
2. ユーザーだけが知っているいくつかのことを確認する
簡潔に(1ラウンド)尋ね、ユーザーが気にしない場合は妥当なデフォルトを設定します:
- サーバーCPUアーキテクチャ — 通常は
linux/amd64(ほとんどのVPS)。ARMサーバー(Hetzner CAX、Oracle Ampere、Graviton)→linux/arm64。不明→マルチアーキlinux/amd64,linux/arm64(ビルドが遅い)。これは重要です:Macでビルドされたarm64イメージはamd64サーバーで起動しません(exec format error)。 - データベース:コンポーズスタック内で実行するか(最も簡単、推奨)、既存の管理DBを使用する(
mysqlサービスを削除し、DB_HOSTを渡す)。 - 変更しないままにしておくべきもの(古いデプロイワークフロー、Sailコンポーズファイル)。
3. コードをコンテナ対応にする
- プロキシを信頼する。 CoolifyのTraefikはTLSを終端し、HTTPを転送します。
X-Forwarded-*を信頼しないと、Laravelはhttp://URLを生成します(混合コンテンツ、Livewire/Filamentアセットの破損、安全でないクッキー、Webプッシュの失敗)。Laravel 11+:bootstrap/app.php内でLaravel ≤10:->withMiddleware(function (Middleware $middleware): void { $middleware->trustProxies(at: '*'); })app/Http/Middleware/TrustProxies.phpにprotected $proxies = '*';を設定します。'*'は、ポート8080がインターネットに公開されることがないため安全です — ドキュメントでその旨を説明してください。 - npm lockfileを修復する スキャンでフラグが立った場合:
これはネイティブバイナリパッケージ(rollup、esbuild、lightningcss、Tailwind oxide、swc、sass-embedded)のみを再解決します;出力されたバージョンアップをユーザーに報告します。python3 <skill-dir>/scripts/repair_npm_lock.py <project-dir> .env.example:アプリが読み取るがexampleに欠けているキーを追加します(config/内のenv(呼び出しとファイルを比較)して、デプロイドキュメントが完全になるようにします。.gitignore:.env.dockerを追加します。
4. Dockerファイルを生成する
assets/からプロジェクトにコピーし、プレースホルダーを埋めます:__IMAGE__、__REPO_URL__(httpsのGitHub URL、GHCRパッケージをリポジトリにリンク)、__APP_NAME__、__PHP_VERSION__、__PHP_EXTENSIONS__、__QUEUES__。その後適応:
- 何もキューイングされていない場合は
workerサービスを削除;スケジュールタスクがある場合はschedulerのコメントを解除。 references/variants.mdに従って、DBサービス/環境変数をPostgres、MariaDB、またはRedisに交換。x-app-envアンカーにアプリ固有の環境変数キー(APIキー、VAPID、S3)を${VAR:-}として追加;本当に必要なものは${VAR:?msg}とマークして、値が欠けている場合は半分設定された状態で起動する代わりに大きく失敗するようにします。APP_TIMEZONEのデフォルトをアプリのconfig/app.phpのデフォルトに設定。- パッケージマネージャーがnpmでない、
package.jsonがない、SSR、Chromium →references/variants.md。
テンプレートに組み込まれた設計上の決定(理由がない限り維持):
- serversideup/php は、NGINX + FPMを非rootの
www-dataとして:8080で提供し、/upヘルスチェック、healthcheck-queue/healthcheck-schedule、そしてstorage:link、DB待機、migrate --force、php artisan optimize(filament:optimizeや他のパッケージの最適化フックを含む)を実行するAUTORUN_ENABLEDを提供します。AUTORUN_ENABLED=trueを設定するのはappサービスのみなので、マイグレーションは1回のみ実行されます;ワーカー/スケジューラーはappが正常になるのを待ちます。 $BUILDPLATFORM上のアセットステージ — Mac上でネイティブに実行され、PHPステージはamd64用にエミュレートされます;出力はアーキテクチャに依存しません。- ソースをコピーする前にComposerインストール — 依存関係レイヤーはキャッシュされたまま;コードのみのリビルドはエミュレーション下でも高速です。
- app + worker (+ scheduler) で共有される1つの
storage/appボリューム — ジョブが書き込んだファイルはWebコンテナから見える必要があります。 - ログはstderrに出力 — プラットフォームのログビューアで表示できるようにします。
5. プッシュ前にローカルで検証する
これを実際に行ってください — 「Dockerfileが正しく見える」で止まらないでください。開発コンテナと衝突しないようにコンポーズプロジェクト名を使用します。
docker buildx build --load -t <name>:test . # ネイティブアーキ、高速
docker run --rm --entrypoint php <name>:test -m # 拡張機能が存在するか?
docker run --rm --entrypoint php <name>:test artisan key:generate --show
cp .env.docker.example .env.docker # APP_IMAGE=<name>, IMAGE_TAG=test, PULL_POLICY=never, key, passwords
docker compose -p <name>test --env-file .env.docker -f docker-compose.prod.yml -f docker-compose.prod.local.yml up -d --wait
(--entrypoint phpはserversideupのバナー/自動化をスキップし、ワンオフコマンドがクリーンな出力を表示できるようにします。)
確認し、各結果を報告します:
- すべてのサービスが
healthy;appログがstorage:link、マイグレーション、optimizeを❌なしで表示。 curl -s -o /dev/null -w '%{http_code}' localhost:8080/up→ 200;ログイン/ホームページ → 200、そのCSS/JS URLが200を返す。- プロキシ:
curl -s -H 'X-Forwarded-Proto: https' -H 'X-Forwarded-Host: x.example.com' localhost:8080/<page>→ アセットURLがhttps://x.example.comで始まる。 php artisan db:seed --force(アプリに初回インストール時にユーザーが期待するシーダーがある場合)。- キュー:アプリからの実際のキュー化クラス(通知/ジョブ)を各名前付きキューにディスパッチし、ワーカーが
DONEをログに記録し、副作用が発生したことを確認します。tinker --executeからディスパッチされたクロージャはワーカーで失敗します(evalされたコードはアンシリアライズできない) — これはテストアーティファクトであり、バグではありません。また、テスト受信者を選ぶ際にアプリ自身のshouldSend/認可を尊重します。 - ストレージ:ワーカーから
publicディスクにファイルを書き込み、localhost:8080/storage/...でappから取得、その後down+upしてファイルとDB行が永続化されることを確認。 - サーバー用のクロスビルド:
docker buildx build --platform linux/amd64 -t <name>:amd64 --load .その後docker image inspect <name>:amd64 --format '{{.Architecture}}'。バックグラウンドで実行 — QEMUビルドには数分かかります。
完了したら docker compose -p <name>test down -v で破棄します。
6. デプロイドキュメントを作成する
references/docs-template.mdに従ってdocs/DOCKER_DEPLOYMENT.mdを作成します。プロジェクトの既存ドキュメントが使用している言語で書き、README.mdからリンクします。ドキュメントでは、各ファイルについて何が変わったか、なぜ変わったか(このスキル作成時にユーザーが求めたことであり、将来のメンテナーに必要)、アーキテクチャ、初回セットアップ、ビルド/プッシュ、ローカルテスト、Coolifyの手順、更新/ロールバック、運用、旧ホストからのデータ移行、およびステップ1で見つけたプロジェクト固有の注意点を説明する必要があります。
7. 引き継ぎ — 外向けのことを行う前に確認する
GHCRへのプッシュはイメージを公開し、デプロイは本番を変更するため、停止してユーザーに決定させます。以下のものを提供します:
echo <write:packages権限のPAT> | docker login ghcr.io -u <user> --password-stdin- コミット、その後
scripts/docker-build-push.sh(ダーティツリーは拒否;ローカルのみのビルドには--load)。 references/coolify.mdからのCoolify手順 — 特にサーバーがプライベートパッケージに対して読み取り専用のGHCRログインを必要とすること。これはsudo docker loginで行います(Coolifyはrootとしてプル;非rootログインは見えません)、そしてドメインはhttps://domain:8080として入力します(:8080= コンテナポート)。- リマインダー:移行時に古い
APP_KEY(およびVAPIDや他の長期キー)を再利用;新しいデプロイが稼働したら、古いSSH/FTPデプロイワークフローを無効化する。
ログインしたらプッシュを実行するオファーをします。
よくあるユーザーの混乱を先取りする
ユーザーはしばしばdocker run <image>やDocker Desktopの▶ボタンをイメージ単体で試します。それではWebコンテナだけが起動します:DBサービスは存在せず、自動実行はオフで、Laravelはsqliteにフォールバックする(Database file at path [...] does not exist)か、mysqlの解決に失敗します。答えは常にコンポーズスタックです。ドキュメントのローカルテストセクションでこれを述べてください。