CLI 설정

공통 옵션제목 링크 복사

모든 ntro 명령에 붙일 수 있는 옵션입니다.

--api와 --identity는 보통 바꿀 일이 없습니다. 바꿔야 한다면 플래그 → 환경 변수(NITROSHIP_API_URL, NITROSHIP_IDENTITY_URL) → 저장된 값 → 기본값 순서로 먼저 있는 값을 씁니다.

대화형 모드와 자동화제목 링크 복사

ntro는 빠진 인자를 물어보거나 삭제·승격 같은 작업을 한 번 더 확인합니다. 이런 질문은 아래 조건을 모두 만족할 때만 나타납니다.

• 표준 입력(stdin)과 표준 오류(stderr)가 모두 터미널이다.
• --json을 쓰지 않았다.
• CI 환경 변수가 없다. (빈 값이라도 설정되어 있으면 자동화로 봅니다.)

자동화에서는 질문할 수 없으므로 다음을 지켜 주세요.

• 앱·팀·배포 ID, 팀원 이메일·역할처럼 필요한 인자를 모두 적습니다.
• 확인이 필요한 작업(삭제, 취소, 승격, 롤백 등)에는 --yes를 붙입니다.
• 연결되지 않은 폴더를 배포할 때는 --app <앱>을 붙입니다.

인증제목 링크 복사

CLI는 아래 순서로 먼저 찾은 인증 정보를 씁니다.

1. --token 플래그
2. NITROSHIP_TOKEN 환경 변수
3. ntro login으로 저장한 로그인 정보

• 사람이 쓸 때: ntro login으로 로그인합니다. 자세한 내용은 로그인 문서를 참고하세요.
• 자동화: ntro_ API 토큰을 NITROSHIP_TOKEN으로 넘깁니다. 자세한 내용은 API 토큰 문서를 참고하세요.
• 로그아웃: ntro logout은 저장된 로그인을 서버에서 무효화하고 로컬 파일에서 지웁니다.

어느 쪽이든 CLI는 실제 API 요청에 5분짜리 접속 토큰을 쓰고, 만료되면 알아서 새로 받습니다.

로컬에 저장되는 파일제목 링크 복사

NITROSHIP_CONFIG_DIR을 지정하면 ~/.nitroship 대신 그 폴더를 씁니다.

앱 연결제목 링크 복사

폴더를 앱에 연결해 두면 그 폴더에서 실행하는 명령에 --app을 붙이지 않아도 됩니다. 연결 정보는 앱 ID로 저장되므로 앱 슬러그를 바꿔도 다시 연결할 필요가 없습니다.

ntro apps create my-app   # 앱을 만들고 현재 폴더에 연결
ntro link my-app          # 현재 폴더를 기존 앱에 연결 (또는 바꾸기)
ntro unlink               # 현재 폴더의 연결 해제

• apps create는 기본으로 현재 폴더를 연결합니다. 원하지 않으면 --no-link를 붙이세요. --json에서도 연결하지 않습니다.
• ntro link를 인자 없이 실행하면 앱 목록에서 고를 수 있습니다. 자동화에서는 앱 이름을 꼭 적어야 합니다.
• ntro unlink는 .nitroship/app.json(과 예전 형식인 .nitroship/project.json)만 지웁니다. 앱은 삭제되지 않으며, 로그인도 필요 없습니다. 연결이 없어도 성공합니다.
• 다른 팀의 앱을 쓰게 되었거나, 연결한 앱의 팀이 바뀌었다면 다시 연결하세요.

빌드 프레임워크제목 링크 복사

배포 루트의 nitroship.json에 build.framework를 적으면 관리형 프레임워크를 직접 선택할 수 있습니다.

{
  "build": {
    "framework": "nuxt"
  }
}

허용되는 값은 정확히 다음과 같습니다.

• nextjs, static
• nuxt, solidstart, analog, tanstack-start, sveltekit, astro, react-router, remix, angular, qwik
• gatsby, docusaurus, vitepress, eleventy, hugo, jekyll, mkdocs
• nestjs, express, fastify, hono, koa
• vite, create-react-app
• laravel, symfony, wordpress, rails, django, phoenix
• fastapi, flask, spring-boot, dotnet, go, rust, php

직접 지정한 build.framework는 자동 감지보다 우선하며, 루트에 Dockerfile.nitroship이나 Dockerfile이 있어도 마찬가지입니다. build.framework와 build.dockerfile을 함께 지정하면 오류가 납니다. 직접 작성한 Dockerfile을 쓰려면 build.framework를 지우세요. 자세한 내용은 Dockerfile 문서를 참고하세요.

build.framework가 없으면 다음 순서로 감지합니다.

1. build.dockerfile로 지정한 파일, 지정하지 않았다면 루트의 Dockerfile.nitroship, 그다음 루트의 Dockerfile.
2. 전용 어댑터로 처리하는 Next.js.
3. 관리형 프레임워크 레지스트리.
4. 감지된 프레임워크가 없으면 일반 정적 파일.

관리형 프리셋은 네 가지 결과 유형 중 하나를 만듭니다.

유형은 프레임워크와 설정에 따라 달라지며 build.framework에 넣는 값이 아닙니다. 예를 들어 Astro는 정적 파일이나 독립 실행형 Node.js 서버를 만들 수 있습니다. 로컬 배포는 관리형 Next.js 빌드를 포함한 정적·Node.js 결과물을 지원합니다. container와 container-static 프리셋은 호스팅 빌드가 필요합니다.

컴퓨트 설정제목 링크 복사

서버(Next.js, 관리형 Node.js·컨테이너 프리셋, 직접 작성한 Dockerfile)를 실행할 리전과 사양입니다. 콘솔의 App Settings > Compute나 배포 루트 nitroship.json의 compute에 적습니다. 정적 파일만 배포할 때는 컴퓨트 설정이 필요 없습니다.

{
  "compute": {
    "regions": ["kr-icn"],
    "tier": "standard",
    "minInstances": 0,
    "maxInstances": 4,
    "port": 3000
  }
}

생성된 Go/Rust 이미지에는 기본값이 3000인 PORT가 주입되지만, 앱은 직접 이를 읽어 0.0.0.0:$PORT에 바인딩해야 하며 프리셋은 하드코딩된 바인딩 주소를 바꿀 수 없습니다.

일반 배포에서는 같은 항목이 여러 곳에 있으면 항목별로 다음 순서대로 먼저 있는 값을 씁니다.

1. CLI 플래그 (--local·--image·--bundle-dir 직접 업로드에서만)
2. nitroship.json
3. 콘솔 App Settings > Compute 또는 컴퓨트 설정 API로 저장한 앱 설정
4. 기본값

값은 빌드를 시작할 때 고정되며, 앱 설정을 저장하는 것만으로 기존 배포는 바뀌지 않습니다. nitroship.json에 리전, 티어, 인스턴스 수, 포트가 선언되어 있어도 콘솔·API 수정은 언제든 가능합니다. 지금 적용으로 다시 빌드하지 않고 프로덕션을 재배포하면, 콘솔·API의 null이 아닌 값이 이전 배포의 파일·플래그 값보다 우선합니다. 설정하지 않은 항목은 이전 값을 유지합니다.

일반 배포를 할 때마다 nitroship.json에 선언한 항목이 다시 콘솔·API 설정보다 우선하며, 지원되는 CLI 플래그는 여전히 파일보다 우선합니다. 즉, 지금 적용으로 파일 값을 잠시 덮어쓸 수 있지만 다음 일반 배포에서는 위 우선순위로 돌아갑니다. 자세한 내용은 배포 관리 문서를 참고하세요.

크론 설정제목 링크 복사

nitroship.json의 최상위 crons에 선언하거나, App Settings > Cron Jobs 또는 크론 작업 API로 관리하세요. 콘솔·API 수정은 언제든 가능하고 즉시 적용됩니다. crons를 선언한 프로덕션 배포를 할 때마다(빈 배열 포함) 배포의 목록이 다시 콘솔 목록보다 우선합니다. crons를 선언하지 않은 프로덕션 배포는 저장된 콘솔 목록을 사용합니다. 콘솔에서 계속 관리하려면 crons 키를 지우고 배포하세요. 자세한 내용은 크론 작업 문서를 참고하세요.

준비 상태 확인 방식제목 링크 복사

새 인스턴스가 요청을 받기 전에 나이트로쉽은 앱이 준비됐는지 확인합니다.

• healthPath가 비어 있을 때 (지정하지 않았거나 ""): 서버 포트가 연결을 받기 시작하면 준비된 것으로 봅니다.
• healthPath가 있을 때 (/ 포함): 그 경로로 GET 요청을 보내 2xx, 3xx, 404 응답이면 준비된 것으로 봅니다. 요청 한 번에 응답 헤더를 최대 2초 기다리며 다시 시도합니다.
• 어느 쪽이든 전체 제한 시간은 30초입니다.

직접 지정한 healthPath는 프레임워크 기본값(Next.js의 /__nitroship/health)보다 우선합니다. 예전에 만든 배포에 /가 저장되어 있다면 재배포·승격·롤백 뒤에도 HTTP 방식 그대로 유지됩니다.