Community코딩 & 개발github.com

Laravel → Docker → GHCR → Coolify

Laravel 애플리케이션을 프로덕션용으로 컨테이너화하고 Coolify에 배포합니다. 로컬(Apple Silicon → amd64 크로스 빌드 포함)에서 이미지를 빌드하고 GHCR에 푸시한 후 Docker Compose 스택(웹, 큐 워커, 스케줄러, 데이터베이스)으로 실행합니다.

Laravel → Docker → GHCR → Coolify란 무엇인가요?

이 스킬은 Laravel 프로젝트를 Docker 기반으로 완전히 이전하여 프로덕션 환경에 배포하는 전체 워크플로우를 제공합니다. 개발자 워크스테이션에서 이미지를 빌드하고 GitHub Container Registry(GHCR)에 푸시한 후, 서버(Coolify)는 compose 파일을 통해 이미지(웹 + 큐 워커 + 스케줄러 + DB)를 가져와 실행하기만 하면 됩니다. 지원하는 플랫폼은 Coolify, Dokploy, EasyPanel, CapRover, 일반 VPS + Docker입니다. 주요 기능으로는 프로젝트 검사 자동화, npm 잠금 파일 복구, 신뢰 프록시 설정, Dockerfile/docker-compose 생성, 로컬 테스트 및 배포 문서 생성이 포함됩니다. 사용자가 Laravel/Filament 프로젝트를 Docker로 마이그레이션하거나, SQLite 대신 MySQL을 사용하도록 구성하거나, 큐 작업이 처리되지 않는 문제를 해결할 때 특히 유용합니다.

지원 대상~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)는 compose 파일을 통해 가져와서 실행만 합니다. 서버에서 빌드하지 않고, 이미지에 시크릿이 포함되지 않으며, 모든 설정은 환경 변수에서 가져옵니다.

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 전용.
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는 웹 푸시를 위해 함께 나타납니다; 둘 다 설치해도 괜찮습니다.
  • extensions.system_binaries — OS 바이너리가 필요한 패키지(Chromium, wkhtmltopdf, ffmpeg). 이미지를 비대화시키기 전에 코드가 실제로 사용하는지 확인하세요(클래스명으로 grep); 사용 중이면 references/variants.md 참조.
  • queues — needs_worker 및 worker_queue_arg. 워커의 --queue=는 모든 명명된 큐(from onQueue, $queue, viaQueues())를 나열해야 합니다. 그렇지 않으면 해당 작업이 기본 큐 워커가 정상으로 보이는 동안 테이블에 영원히 남습니다.
  • scheduler.has_scheduled_tasks → scheduler 서비스 추가.
  • packages.key_packages → Horizon은 워커를 대체; Reverb는 웹소켓 서비스 추가; Octane은 베이스 이미지 변경(variants 참조).
  • database — compose DB 서비스의 드라이버. config_default는 종종 sqlite입니다: 컨테이너에서 DB_CONNECTION이 설정되지 않으면 Laravel은 조용히 SQLite를 사용합니다. 이러한 이유로 compose 파일에서 명시적으로 설정합니다.
  • frontend.npm_lock_missing_linux_binaries — 비어 있지 않으면 Linux에서 npm ci가 실패합니다. repair_npm_lock.py 실행(3단계).
  • frontend.vite_needs_php_at_build — Wayfinder 등은 Vite 빌드 중에 PHP가 필요; variants 참조.
  • 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. 사용자만 아는 몇 가지 사항 확인

간략하게 묻고(한 라운드), 사용자가 신경 쓰지 않으면 합리적으로 기본값을 설정하세요:

  • 서버 CPU 아키텍처 — 일반적으로 linux/amd64(대부분 VPS). ARM 서버(Hetzner CAX, Oracle Ampere, Graviton) → linux/arm64. 알 수 없음 → 멀티 아키텍처 linux/amd64,linux/arm64(빌드 느림). Mac에서 빌드된 arm64 이미지는 amd64 서버에서 시작되지 않기 때문에 중요합니다(exec format error).
  • 데이터베이스: compose 스택에서 실행(가장 간단하고 권장) 또는 기존/관리형 DB 사용(mysql 서비스 제거, DB_HOST 전달).
  • 그대로 두어야 하는 것(기존 배포 워크플로우, Sail compose 파일).

3. 코드를 컨테이너에 맞게 준비

  • 프록시 신뢰. Coolify의 Traefik은 TLS를 종료하고 HTTP를 전달합니다. X-Forwarded-*를 신뢰하지 않으면 Laravel은 http:// URL을 생성합니다(혼합 콘텐츠, 깨진 Livewire/Filament 자산, 안전하지 않은 쿠키, 웹 푸시 실패). 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: 앱이 읽지만 예제에 없는 키를 추가하세요(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로 교체.
  • 앱별 환경 키(API 키, VAPID, S3)를 x-app-env 앵커에 ${VAR:-}로 추가; 진정으로 필수인 것은 ${VAR:?msg}로 표시하여 누락된 값이 반쯤 구성된 상태로 부팅되지 않도록 오류를 발생시킵니다.
  • APP_TIMEZONE 기본값을 앱의 config/app.php 기본값으로 설정.
  • 패키지 매니저가 npm이 아닌 경우, package.json 없음, SSR, Chromium → references/variants.md.

템플릿에 포함된 설계 결정(이유가 없으면 유지):

  • serversideup/php는 NGINX+FPM을 비루트 www-data로 :8080에서 제공하고, /up 헬스 체크, healthcheck-queue/healthcheck-schedule, AUTORUN_ENABLED를 제공하며, 이는 storage:link 실행, DB 대기, migrate --force, php artisan optimize 실행을 포함합니다(여기에는 filament:optimize 및 기타 패키지의 최적화 훅이 포함됨). app 서비스만 AUTORUN_ENABLED=true를 설정하므로 마이그레이션이 한 번 실행됩니다; worker/scheduler는 app이 정상 상태가 될 때까지 기다립니다.
  • $BUILDPLATFORM에서 Assets 단계 — Mac에서 기본적으로 실행되는 동안 PHP 단계는 amd64용으로 에뮬레이션됩니다; 출력은 아키텍처에 독립적입니다.
  • 소스 복사 전 Composer 설치 — 종속성 레이어가 캐시됩니다; 코드 전용 재빌드는 에뮬레이션에서도 빠릅니다.
  • app + worker(+ scheduler)용 공유 storage/app 볼륨 — 작업이 기록한 파일이 웹 컨테이너에 표시되어야 합니다.
  • 로그를 stderr로 — 플랫폼의 로그 뷰어에서 표시됩니다.

5. 푸시하기 전에 로컬에서 확인

실제로 수행하세요 — "Dockerfile이 올바르게 보인다"에서 멈추지 마세요. 개발 컨테이너와 충돌하지 않도록 compose 프로젝트 이름을 사용하세요.

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에서 전달된 클로저는 워커에서 실패합니다(평가된 코드를 역직렬화할 수 없음) — 이는 테스트 아티팩트일 뿐 버그가 아닙니다. 또한 테스트 수신자를 선택할 때 앱 자체의 shouldSend/권한 부여를 존중하세요.
  6. 스토리지: 워커에서 public 디스크에 파일을 쓰고, 앱에서 localhost:8080/storage/...를 통해 가져온 다음 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 <PAT with write:packages> | 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로 풀링; 비루트 로그인은 보이지 않음), 도메인은 https://domain:8080으로 입력(:8080 = 컨테이너 포트).
  4. 알림: 마이그레이션 시 이전 APP_KEY(및 VAPID 또는 기타 장기 키) 재사용; 새 배포가 라이브가 되면 기존 SSH/FTP 배포 워크플로우를 비활성화.

사용자가 로그인하면 푸시를 대신 실행하겠다고 제안하세요.

일반적인 사용자 혼란 예방

사용자는 종종 docker run <image> 또는 Docker Desktop의 ▶ 버튼을 단일 이미지에서 시도합니다. 그러면 웹 컨테이너만 시작됩니다: DB 서비스가 없고, 자동 실행이 꺼져 있으며, Laravel은 sqlite(Database file at path [...] does not exist)로 대체하거나 mysql 해결에 실패합니다. 해결책은 항상 compose 스택입니다. 문서의 로컬 테스트 섹션에서 이를 명시하세요.

관련 스킬