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/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 전용. |
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는 웹 푸시를 위해 함께 나타납니다; 둘 다 설치해도 괜찮습니다.extensions.system_binaries— OS 바이너리가 필요한 패키지(Chromium, wkhtmltopdf, ffmpeg). 이미지를 비대화시키기 전에 코드가 실제로 사용하는지 확인하세요(클래스명으로 grep); 사용 중이면references/variants.md참조.queues—needs_worker및worker_queue_arg. 워커의--queue=는 모든 명명된 큐(fromonQueue,$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.phpLaravel ≤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: 앱이 읽지만 예제에 없는 키를 추가하세요(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의 배너/자동화를 건너뛰어 일회성 명령이 깔끔한 출력을 생성하도록 합니다.)
확인하고 각 결과를 보고하세요:
- 모든 서비스
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에서 전달된 클로저는 워커에서 실패합니다(평가된 코드를 역직렬화할 수 없음) — 이는 테스트 아티팩트일 뿐 버그가 아닙니다. 또한 테스트 수신자를 선택할 때 앱 자체의shouldSend/권한 부여를 존중하세요. - 스토리지: 워커에서
public디스크에 파일을 쓰고, 앱에서localhost:8080/storage/...를 통해 가져온 다음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 <PAT with write:packages> | docker login ghcr.io -u <user> --password-stdin- 커밋, 그런 다음
scripts/docker-build-push.sh(더티 트리 거부;--load는 로컬 전용 빌드용). references/coolify.md의 Coolify 단계 — 특히 서버가 비공개 패키지에 대해 읽기 전용 GHCR 로그인이 필요하며sudo docker login으로 수행(Coolify는 root로 풀링; 비루트 로그인은 보이지 않음), 도메인은https://domain:8080으로 입력(:8080= 컨테이너 포트).- 알림: 마이그레이션 시 이전
APP_KEY(및 VAPID 또는 기타 장기 키) 재사용; 새 배포가 라이브가 되면 기존 SSH/FTP 배포 워크플로우를 비활성화.
사용자가 로그인하면 푸시를 대신 실행하겠다고 제안하세요.
일반적인 사용자 혼란 예방
사용자는 종종 docker run <image> 또는 Docker Desktop의 ▶ 버튼을 단일 이미지에서 시도합니다. 그러면 웹 컨테이너만 시작됩니다: DB 서비스가 없고, 자동 실행이 꺼져 있으며, Laravel은 sqlite(Database file at path [...] does not exist)로 대체하거나 mysql 해결에 실패합니다. 해결책은 항상 compose 스택입니다. 문서의 로컬 테스트 섹션에서 이를 명시하세요.