PHP
PHP 앱을 관리형 FrankenPHP 컨테이너로 배포합니다.
배포 루트에 composer.json이나 index.php가 있고 더 구체적인 PHP 프레임워크가 감지되지 않으면 나이트로쉽이 일반 PHP 프리셋을 선택합니다. Laravel·Symfony·WordPress는 우선순위가 더 높은 전용 프리셋이 있습니다.
일반 프리셋은 PHP 애플리케이션 서버인 FrankenPHP로 HTTP 앱을 실행합니다. 다른 프레임워크의 초기 설정 명령·마이그레이션·캐시 디렉터리·환경 변수 규칙을 추측해 적용하지는 않습니다.
배포하기
CLI 설치
curl -fsSL https://nitroship.co/install.sh | bash
ntro login이미 설치했다면 다음 단계로 넘어가세요. 설치 옵션, PATH 설정 및 업데이트는 CLI 설치에서 확인하세요.
컴퓨트 리전을 고르고, PHP를 명시적으로 선택하려면 다음과 같이 적습니다.
{
"build": {"framework": "php"},
"compute": {"regions": ["kr-icn"]}
}앱의 프로덕션 환경 변수를 설정한 뒤 배포하세요.
ntro apps create my-php-app
ntro deploy . --prod관리형 PHP 컨테이너는 호스팅 빌더가 필요합니다. --local이 있다면 빼세요. PHP 요청은 정적 파일로 제공하는 대신 컴퓨트에서 처리하므로 컴퓨트 리전이 꼭 필요합니다.
문서 루트와 결과물
프로젝트에 public/이 있으면 이 디렉터리가 문서 루트입니다. 없으면 배포 루트를 문서 루트로 사용합니다. 웹에 공개할 파일을 앱 코드·Composer 파일·설정과 분리할 수 있도록 public/ 사용을 권장합니다. 루트를 사용한다면 웹 서버가 어떤 파일을 노출할 수 있는지 확인하세요. CDN에서 서버 소스를 제외한다고 해서 안전한 앱 디렉터리 구성이 불필요해지는 것은 아닙니다.
composer.json이 있으면 빌더가 composer install --no-dev로 프로덕션 의존성을 설치합니다. package.json에 build 스크립트도 있으면 Node 22로 프런트엔드 파일을 빌드합니다. FrankenPHP는 0.0.0.0:$PORT에서 요청을 받고 기본 포트는 3000입니다.
문서 루트에서 허용된 브라우저용 확장자를 가진 파일은 생성된 이미지의 /nitroship/static으로 복사한 뒤 자동으로 추출해 CDN에서 제공합니다. CDN이 이 파일을 먼저 제공하고 동적 페이지·API는 컴퓨트의 PHP 컨테이너가 처리합니다. build.outputDirectory를 설정할 필요는 없습니다.
허용하는 확장자는 .css, .js, .mjs, .html, .txt, .webmanifest, .png, .jpg, .jpeg, .gif, .webp, .avif, .ico, .svg, .woff, .woff2, .ttf, .otf, .eot, .mp4, .webm, .pdf입니다. PHP 파일·심볼릭 링크·숨김 경로·문서 루트의 vendor/와 node_modules/는 복사하지 않습니다.
app·bootstrap·config·resources·routes·storage·src·templates·tests·test·bin·parts·patterns라는 디렉터리도 제외합니다. 파일 이름에 config나 server가 들어간 JS/MJS, *.blade.html·*.twig.html, 이름이 readme·license·changelog로 시작하는 파일도 추출하지 않습니다. 배포 루트를 문서 루트로 사용하면 JS/MJS는 추가로 assets/·js/·static/·wp-includes/js/·wp-admin/js/·wp-content/ 아래에서만 추출합니다. 문서 루트가 public/이면 이 추가 JS/MJS 경로 제한은 적용하지 않습니다.
추출 시 경로와 확장자를 검사할 뿐 파일 내용을 판단하지는 않습니다. 서버 소스·템플릿·비밀값·빌드 설정은 공개 문서 루트 밖에 두세요. 공개하면 안 되는 파일이라도 허용된 확장자가 있으면 CDN에 게시될 수 있습니다. 배포 루트가 문서 루트이기도 한 경우에는 특히 주의하세요.
PHP와 도구 버전
프리셋은 먼저 composer.json의 require.php를 읽고, 없으면 .tool-versions의 PHP 선언을 확인합니다. 선언된 메이저 버전 안에서 가장 가까운 지원 PHP 버전을 선택하며, PHP 8.2·8.3·8.4·8.5용 버전이 고정된 FrankenPHP 기반 이미지를 사용합니다. 선언이 없거나 지원하지 않는 버전이면 현재 기본값인 PHP 8.5를 씁니다. 선언만으로 임의의 이미지 태그나 지원하지 않는 PHP 릴리스를 설치하지는 않습니다.
관리형 이미지에는 일반적인 DB·GD·intl·zip 확장 모듈이 포함되며, Composer에 선언된 ext-* 요구사항도 확장 설치 도구가 지원하는 범위에서 설치합니다. 다른 런타임·지원하지 않는 확장 모듈·시스템 패키지·별도 빌드나 시작 명령이 필요하면 일반 프리셋이 설정해 줄 것으로 기대하지 말고 직접 만든 Dockerfile을 사용하세요.
프로덕션 설정과 저장소
PHP 코드에서 실제로 읽는 변수를 환경 변수로 설정하세요. 예를 들어 DB 접속 정보·앱 비밀값·공개 URL은 앱에서 사용할 때만 효과가 있습니다. 앱의 프로덕션 설정으로 디버그 출력을 끄세요. 일반 프리셋은 환경 변수를 프레임워크 설정에 자동 연결하거나 DB를 만들어 주지 않습니다.
인스턴스가 교체되어도 데이터를 유지하거나 여러 인스턴스에서 공유해야 한다면 외부 DB와 외부 세션·캐시 저장소를 사용하세요. 생성된 컨테이너는 루트가 아닌 사용자로 실행됩니다. 인스턴스 파일시스템은 임시 저장소입니다. 임시 파일은 /tmp에 쓰고, 앱의 캐시·로그·세션 경로도 이에 맞춰 설정하세요. 영구 데이터를 소스 디렉터리에 쓰는 방식에 의존하지 마세요.
업로드는 S3 같은 오브젝트 스토리지에 저장하세요. 실행 중 생성한 업로드는 빌드 시 CDN 추출에 포함되지 않으며, 인스턴스에 저장한 파일은 공유되거나 영구 보관되지 않습니다.
운영 시 주의할 점
나이트로쉽은 데이터베이스 마이그레이션·큐 워커·스케줄러를 자동으로 실행하지 않습니다. 외부 DB의 프로덕션 연결 정보를 사용해 CI나 로컬 컴퓨터에서 마이그레이션을 실행하세요. 백그라운드 워커는 별도로 운영해야 합니다. 정기적인 HTTP 작업은 Cron 작업을 참고하세요.
프리셋은 HTTP 앱 하나를 제공합니다. 앱 전용 시작 명령을 찾아 실행하거나 별도의 워커 프로세스를 계속 띄워 주지는 않습니다. 별도 웹 서버·파일시스템 구성·시작 전 준비 과정이 필요한 앱은 직접 만든 Dockerfile을 사용하세요.
직접 만든 Dockerfile 사용하기
build.framework가 없으면 설정된 build.dockerfile, Dockerfile.nitroship, Dockerfile 순서로 먼저 선택합니다. 그다음 Next.js, 감지된 관리형 프리셋 중 우선순위가 가장 높은 것, 일반 정적 출력 순서입니다.
build.framework: "php"는 일반 프리셋을 명시적으로 선택하므로 자동 감지와 자동으로 발견한 Dockerfile보다 우선합니다. build.framework와 build.dockerfile은 함께 설정할 수 없습니다. 직접 만든 이미지를 쓰려면 build.framework를 지우고 Dockerfile 가이드를 따르세요.
관련 가이드
Laravel · Symfony · WordPress · 환경 변수 · Cron 작업 · Dockerfile 배포