직접 작성한 Dockerfile

나이트로쉽은 Dockerfile 없이도 Node 서버, JavaScript 프레임워크, 지원하는 백엔드 프레임워크를 감지하고 빌드합니다. 다른 도구 버전, 지원하지 않는 어댑터, 네이티브 의존성, 별도 실행 명령이 필요하면 직접 작성한 Dockerfile을 쓰세요.

build.framework가 없으면 원격 빌더는 Dockerfile을 Next.js·관리형 프리셋·일반 정적 사이트보다 먼저 선택합니다. build.framework를 지정하면 Dockerfile이 있어도 해당 관리형 프리셋을 씁니다. build.framework와 build.dockerfile을 함께 적으면 설정 오류가 납니다.

요구사항제목 링크 복사

• 빌드할 수 있는 Dockerfile. 의존성 설치와 서버 실행 명령이 모두 들어 있어야 합니다.
• 컨테이너 안에서 HTTP 요청을 받는 서버. 어느 포트를 쓰는지는 아래에서 설명합니다.
• 컴퓨트 리전. 기본값이 없으므로 콘솔이나 nitroship.json 중 한 곳에서 꼭 정해야 합니다.

어떤 Dockerfile을 쓰나요제목 링크 복사

빌더는 소스 루트(배포하는 폴더, Git 연동이라면 지정한 루트 디렉터리)에서 아래 순서대로 먼저 찾은 파일 하나를 씁니다.

1. nitroship.json의 build.dockerfile에 적은 파일
2. Dockerfile.nitroship
3. Dockerfile

배포용 Dockerfile을 따로 두고 싶다면 Dockerfile.nitroship을 만들거나 build.dockerfile로 경로를 지정하세요.

{"build": {"dockerfile": "docker/Dockerfile.production"}}

• build.dockerfile은 소스 루트 기준 상대 경로여야 합니다. 절대 경로, 역슬래시, 루트 밖으로 나가는 경로(../), .은 쓸 수 없습니다.
• 지정한 파일이 없거나 심볼릭 링크가 소스 폴더 밖을 가리키면 빌드가 실패합니다. 다른 Dockerfile이나 다른 배포 방식으로 넘어가지 않습니다.

다시 자동 감지를 쓰려면 배포 루트의 Dockerfile과 build.dockerfile 설정을 제거하세요. 파일을 그대로 두고 프리셋을 직접 선택해도 됩니다.

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

예를 들어 Rails가 생성하는 Kamal용 Dockerfile은 80번 포트에서 요청을 받습니다. 관리형 빌드를 쓰려면 build.framework: "rails"를 지정하고, 직접 빌드하려면 Dockerfile을 수정해 권한이 필요 없는 포트의 0.0.0.0:$PORT에서 요청을 받도록 하세요.

배포하기제목 링크 복사

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

FROM node:22-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]

{"compute": {"regions": ["kr-icn"], "port": 3000}}

ntro apps create my-server
ntro deploy . --prod

배포가 끝나면 CLI가 보여 준 주소로 서버 응답을 확인하세요. 잘 안 된다면 ntro builds logs로 빌드 로그와 선택된 포트를 확인합니다.

설정제목 링크 복사

리전·포트 같은 서버 설정은 콘솔의 App Settings > Compute나 nitroship.json의 compute에 적습니다. 둘 다 있으면 항목별로 파일 값이 이깁니다. 전체 항목은 CLI 설정 > 컴퓨트 설정에 있습니다.

nitroship.json의 build.installCommand와 build.command는 Dockerfile 빌드에서 쓰이지 않습니다(빌드 로그에 경고가 나옵니다). 설치·빌드 과정은 모두 Dockerfile에 적으세요.

포트는 이렇게 정해집니다제목 링크 복사

1. 콘솔이나 nitroship.json에 port가 있으면 그 포트
2. 없으면 Dockerfile의 EXPOSE 중 번호가 가장 작은 TCP 포트
3. EXPOSE도 없으면 3000

포트를 여러 개 열었다면 헷갈리지 않게 port를 직접 적어 주세요.

런타임은 프로세스에 PORT를 전달합니다. localhost가 아니라 0.0.0.0에 바인딩하고, 다른 포트를 고정하지 말고 PORT를 읽으세요. EXPOSE는 메타데이터일 뿐, 서버가 실제로 그 포트에서 실행되게 하지는 않습니다.

이미지 안의 정적 파일 함께 게시하기제목 링크 복사

기본으로는 모든 요청을 컨테이너가 처리합니다. JS·CSS·이미지 같은 정적 파일을 컨테이너 대신 정적 스토리지에서 바로 서빙하고 싶다면, 최종 이미지 안에 그 파일이 있는 폴더를 build.outputDirectory로 알려 주세요.

{
  "build": {
    "dockerfile": "docker/Dockerfile.production",
    "outputDirectory": "/app/app/static/assets"
  },
  "compute": {"regions": ["kr-icn"], "port": 3000}
}

• 경로는 최종 이미지 안의 절대 경로입니다(/ 자체는 안 됨). 소스 루트 기준 상대 경로를 쓰는 정적 사이트와 다르니 주의하세요.
• 빌더는 최종 단계(stage)의 파일만 읽습니다. 멀티 스테이지 빌드의 중간 단계는 보지 않고, 심볼릭 링크는 건너뜁니다.
• 폴더 이름이 아니라 폴더 안의 내용이 사이트 루트가 됩니다. 위 예시에서 이미지의 /app/app/static/assets/x.js는 /assets/x.js가 아니라 /x.js로 열립니다.
• SSR·API는 계속 컨테이너가 처리합니다. 컨테이너만 배포하려면 outputDirectory를 빼세요.

설정했다면 배포 후 /x.js 같은 파일 주소를 직접 열어 사이트 루트에서 서빙되는지 확인하세요.

알아둘 점제목 링크 복사

• 관리형 프리셋과 달리 직접 작성한 Dockerfile에서는 의존성 설치, 빌드, 실행, 정적 파일 분리를 모두 직접 정합니다. 관리형 프리셋은 알려진 클라이언트·공개 파일을 자동으로 CDN에 올리지만, 직접 만든 이미지는 build.outputDirectory를 지정해야 합니다.
• Dockerfile 배포는 원격 빌더만 지원합니다. --local을 빼세요.
• 컨테이너는 제한된 권한으로 실행됩니다. 1024 미만 포트 사용, mount, Docker-in-Docker, setuid 프로그램, 특정 장치 접근에 기대는 이미지는 다르게 동작할 수 있습니다. 서버는 3000, 8080처럼 1024 이상 포트에서 띄우세요.
• 루트 파일시스템은 읽기 전용, /tmp는 쓰기 가능한 임시 공간이라고 생각하고 구성하세요. 업로드는 S3·객체 스토리지에, 데이터는 외부 데이터베이스에 저장하세요.
• 배포 과정에서 DB 마이그레이션을 실행하거나 큐 워커·스케줄러를 띄우지 않습니다. 마이그레이션은 CI나 로컬에서 실행하고, 예약 HTTP 작업은 Nitroship Cron을 쓰세요. 인스턴스는 0개까지 줄어들 수 있습니다.

관련 가이드제목 링크 복사

Next.js 관리형 배포 · Node 서버 · 정적 사이트 생성기 · 환경 변수 · 배포 관리