Communityコーディング&開発github.com

laravel-coolify-docker

Laravelアプリケーションをコンテナ化し、Coolifyにデプロイするためのスキル。開発者のマシンでイメージをビルド(Apple Silicon → amd64クロスビルド対応)し、GitHub Container Registryにプッシュし、Docker Composeスタック(Web + キュー・ワーカー + スケジューラー + データベース)として実行します。Dockerfile、docker-compose.prod.yml、ビルド&プッシュスクリプト、プロキシ対策、ローカルテスト環境、デプロイドキュメントを生成します。

laravel-coolify-docker とは?

このスキルは、LaravelまたはFilamentプロジェクトをDockerコンテナ化し、Coolify(Dokploy、EasyPanel、CapRover、通常のVPS+Dockerなど)にデプロイするための完全なワークフローを提供します。開発者のローカルマシンでdocker buildxを使用してlinux/amd64イメージをビルドし、GitHub Container Registry(ghcr.io)にプッシュ、サーバー(Coolify)はそのイメージをプルしてdocker-compose.prod.ymlで実行します。Dockerfile(serversideup/phpベース)、docker-compose.prod.yml(Web、キュー・ワーカー、スケジューラー、データベース)、.dockerignore、環境変数テンプレート、ビルド&プッシュスクリプトを生成します。また、プロジェクトのスキャン(PHPバージョン、拡張機能、キュー、スケジューラー、データベース、フロントエンド、プロキシ設定などを自動検出)、npm lockfileの修復(macOSで作成されたlockfileのLinuxネイティブバイナリ不足を修正)、プロキシ対策(CoolifyのTraefik下でHTTPアセットURLが生成される問題を解決)、ローカル検証、デプロイドキュメントの作成をサポートします。このスキルは、Laravelアプリを共有ホスティングやForgeからコンテナに移行する場合、SQLiteにフォールバックする、MySQLに接続できない、キュー・ジョブが処理されない、プロキシ配下でHTTPアセットが壊れる、npm ciが@rollup/rollup-linuxバイナリ不足で失敗する、といったトラブルシューティングにも対応します。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/uluumbch/laravel-coolify-docker/tree/HEAD/skills/laravel-coolify-docker

Installed? Explore more コーディング&開発 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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/Dockerfileserversideup/php:<ver>-fpm-nginxベースのマルチステージイメージ。
assets/dockerignore.dockerignoreとして保存。
assets/docker-compose.prod.ymlapp + worker + (scheduler) + mysql。Coolifyが参照するファイル。
assets/docker-compose.prod.local.ymlワークステーション用オーバーライド::8080を公開、セキュアクッキー無効。
assets/env.docker.example.env.docker.exampleとして保存。ローカルおよびCoolify環境変数のテンプレート。
assets/docker-build-push.shscripts/docker-build-push.shとして保存。amd64をビルドし、latest + git SHAをプッシュ。
references/variants.mdPostgres/MariaDB、Redis、Horizon、Reverb、Octane、SSR、Wayfinder、pnpm/yarn/bun、Chromium、SQLite-only。
references/coolify.mdサーバー上のGHCR認証、リソース作成、ドメイン:8080、デプロイ/更新/ロールバック。
references/other-platforms.mdDokploy、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 内で
    ->withMiddleware(function (Middleware $middleware): void {
        $middleware->trustProxies(at: '*');
    })
    
    Laravel ≤10:app/Http/Middleware/TrustProxies.php に protected $proxies = '*'; を設定します。'*' は、ポート8080がインターネットに公開されることがないため安全です — ドキュメントでその旨を説明してください。
  • npm lockfileを修復する スキャンでフラグが立った場合:
    python3 <skill-dir>/scripts/repair_npm_lock.py <project-dir>
    
    これはネイティブバイナリパッケージ(rollup、esbuild、lightningcss、Tailwind oxide、swc、sass-embedded)のみを再解決します;出力されたバージョンアップをユーザーに報告します。
  • .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のバナー/自動化をスキップし、ワンオフコマンドがクリーンな出力を表示できるようにします。)

確認し、各結果を報告します:

  1. すべてのサービスがhealthy;appログがstorage:link、マイグレーション、optimizeを❌なしで表示。
  2. curl -s -o /dev/null -w '%{http_code}' localhost:8080/up → 200;ログイン/ホームページ → 200、そのCSS/JS URLが200を返す。
  3. プロキシ:curl -s -H 'X-Forwarded-Proto: https' -H 'X-Forwarded-Host: x.example.com' localhost:8080/<page> → アセットURLがhttps://x.example.comで始まる。
  4. php artisan db:seed --force(アプリに初回インストール時にユーザーが期待するシーダーがある場合)。
  5. キュー:アプリからの実際のキュー化クラス(通知/ジョブ)を各名前付きキューにディスパッチし、ワーカーがDONEをログに記録し、副作用が発生したことを確認します。tinker --executeからディスパッチされたクロージャはワーカーで失敗します(evalされたコードはアンシリアライズできない) — これはテストアーティファクトであり、バグではありません。また、テスト受信者を選ぶ際にアプリ自身のshouldSend/認可を尊重します。
  6. ストレージ:ワーカーからpublicディスクにファイルを書き込み、localhost:8080/storage/...でappから取得、その後down + upしてファイルとDB行が永続化されることを確認。
  7. サーバー用のクロスビルド: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へのプッシュはイメージを公開し、デプロイは本番を変更するため、停止してユーザーに決定させます。以下のものを提供します:

  1. echo <write:packages権限のPAT> | docker login ghcr.io -u <user> --password-stdin
  2. コミット、その後 scripts/docker-build-push.sh(ダーティツリーは拒否;ローカルのみのビルドには--load)。
  3. references/coolify.mdからのCoolify手順 — 特にサーバーがプライベートパッケージに対して読み取り専用のGHCRログインを必要とすること。これはsudo docker loginで行います(Coolifyはrootとしてプル;非rootログインは見えません)、そしてドメインはhttps://domain:8080として入力します(:8080 = コンテナポート)。
  4. リマインダー:移行時に古いAPP_KEY(およびVAPIDや他の長期キー)を再利用;新しいデプロイが稼働したら、古いSSH/FTPデプロイワークフローを無効化する。

ログインしたらプッシュを実行するオファーをします。

よくあるユーザーの混乱を先取りする

ユーザーはしばしばdocker run <image>やDocker Desktopの▶ボタンをイメージ単体で試します。それではWebコンテナだけが起動します:DBサービスは存在せず、自動実行はオフで、Laravelはsqliteにフォールバックする(Database file at path [...] does not exist)か、mysqlの解決に失敗します。答えは常にコンポーズスタックです。ドキュメントのローカルテストセクションでこれを述べてください。

関連スキル