Laravel

배포 루트에 artisan이 있고 composer.json이 laravel/framework에 의존하면 나이트로쉽이 Laravel을 감지합니다. 관리형 프리셋이 컨테이너를 만들어 주므로 Dockerfile을 직접 작성할 필요가 없습니다.

배포하기제목 링크 복사

컴퓨트 리전을 고르고, Laravel을 명시적으로 선택하려면 배포 루트에 다음 파일을 만드세요.

curl -fsSL https://nitroship.co/install.sh | bash
ntro login

{
  "build": {"framework": "laravel"},
  "compute": {"regions": ["kr-icn"]}
}

배포 전에 아래의 프로덕션 환경 변수를 설정하세요.

ntro apps create my-laravel-app
ntro deploy . --prod

관리형 Laravel 프리셋은 호스팅 빌더에서만 빌드할 수 있습니다. 명령에 --local이 있다면 빼세요. PHP 요청을 서버에서 처리하므로 컴퓨트 리전이 꼭 필요합니다.

빌드와 실행 방식제목 링크 복사

• composer install --no-dev로 프로덕션 PHP 의존성을 설치합니다.
• package.json에 build 스크립트가 있으면 관리형 Node 22 도구로 프런트엔드 파일도 빌드합니다.
• PHP 애플리케이션 서버인 FrankenPHP를 사용하며, 문서 루트는 public/입니다. 서버는 0.0.0.0:$PORT에서 요청을 받고 기본 포트는 3000입니다.
• 실행 시점의 환경 변수를 읽은 뒤, 서버 시작 시 Laravel의 설정·라우트·뷰 캐시를 만듭니다. 앱에서 이 캐시 명령들이 정상적으로 실행되어야 합니다.
• 쓰기 가능한 storage/와 bootstrap/cache/는 /tmp/nitroship 아래에 두고, 서버 시작 시 초기 파일을 준비합니다. 앱 디렉터리에 직접 쓰는 방식에 의존하지 않습니다.

public/ 아래에서 허용된 브라우저용 확장자를 가진 파일은 생성된 이미지의 /nitroship/static으로 복사합니다. 나이트로쉽이 이 디렉터리를 자동으로 추출하고, CDN이 해당 파일을 먼저 제공한 뒤 나머지 요청을 컴퓨트의 Laravel로 보냅니다. 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로 시작하는 파일도 추출하지 않습니다.

추출 시 경로와 확장자를 검사할 뿐 파일 내용을 판단하지는 않습니다. 서버 소스·템플릿·비밀값·빌드 설정은 공개 문서 루트 밖에 두세요. 공개하면 안 되는 파일이라도 허용된 확장자가 있으면 CDN에 게시될 수 있습니다.

PHP와 도구 버전제목 링크 복사

프리셋은 먼저 composer.json의 PHP 요구사항(require.php)을 읽고, 없으면 .tool-versions의 PHP 선언을 확인합니다. 지원하는 PHP 버전은 8.2·8.3·8.4·8.5이며, 선언된 메이저 버전 안에서 가장 가까운 지원 버전과 버전이 고정된 FrankenPHP 기반 이미지·도구를 선택합니다. 선언이 없거나 지원하지 않는 버전이면 현재 기본값인 PHP 8.5를 씁니다. 선언만으로 임의의 이미지 태그나 지원하지 않는 릴리스를 설치하지는 않습니다. 선택된 런타임이나 제공되는 확장 모듈이 앱에 맞지 않으면 직접 만든 Dockerfile을 사용하세요.

프로덕션 환경 변수제목 링크 복사

프로덕션 .env를 저장소에 넣지 말고 환경 변수로 비밀값을 설정하세요.

프리셋은 DB·Redis·세션 저장소를 만들어 주지 않습니다. 로컬 파일 세션과 캐시는 인스턴스 사이에 공유되지 않으며 임시 저장소와 함께 사라집니다. 업로드는 S3 같은 오브젝트 스토리지에 저장하세요. /tmp와 Laravel의 로컬 storage는 영구 업로드 저장소가 아닙니다.

운영 시 주의할 점제목 링크 복사

생성된 컨테이너는 루트가 아닌 사용자로 실행됩니다. 인스턴스 파일시스템은 임시 저장소입니다. 임시 파일은 /tmp에 쓰고, 인스턴스가 교체되어도 남아야 하는 데이터는 외부에 저장하세요.

나이트로쉽은 데이터베이스 마이그레이션·큐 워커·스케줄러를 자동으로 실행하지 않습니다. 프로덕션 연결 정보를 사용해 CI나 로컬 컴퓨터에서 외부 DB에 마이그레이션을 적용하세요. 큐 워커는 별도로 운영해야 합니다. 정기적인 HTTP 작업은 Cron 작업을 참고하세요. Laravel을 배포해도 schedule:work나 queue:work가 실행되지는 않습니다.

추가 PHP 확장 모듈·OS 패키지·별도 문서 루트·다른 시작 순서가 필요한 패키지는 직접 만든 이미지가 필요할 수 있습니다. 앱 자체에서 라우트·뷰 캐시가 동작해야 하며 프리셋이 호환되지 않는 앱 코드를 수정하지는 않습니다.

직접 만든 Dockerfile 사용하기제목 링크 복사

build.framework가 없으면 빌더는 설정된 build.dockerfile, Dockerfile.nitroship, Dockerfile 순으로 먼저 찾습니다. Dockerfile이 없으면 Next.js, 감지된 관리형 프리셋 중 우선순위가 가장 높은 것, 일반 정적 출력 순으로 선택합니다.

build.framework: "laravel"을 설정하면 이 프리셋을 명시적으로 선택하므로 자동으로 발견한 Dockerfile보다 우선합니다. build.framework와 build.dockerfile은 함께 설정할 수 없습니다. 직접 만든 이미지를 사용하려면 build.framework를 지우고 Dockerfile 가이드를 따르세요.

관련 가이드제목 링크 복사

환경 변수 · Cron 작업 · Dockerfile 배포