axhub.yaml 레퍼런스

ax-hub-backend deploy manifest domain 기준 canonical manifest schema

axhub.yaml은 repository에 commit하는 배포 계약이에요. Backend resolver는 axhub.yaml을 먼저 읽고, 없을 때만 legacy apphub.yaml을 fallback으로 읽어요. 둘 다 있으면 axhub.yaml이 이겨요.

최소 예시

axhub.yaml

version: axhub/v1
name: hello-axhub
runtime:
  port: 3000
  health_path: /
build:
  strategy: auto
  framework: node
  deploy_method: docker
  dockerfile: Dockerfile
env:
  required:
    - name: DATABASE_URL
      scope: runtime
  optional:
    - name: NEXT_PUBLIC_API_URL
      scope: build
ci:
  commands:
    - npm test
  timeout: 300

모든 field는 optional이에요. 비어 있는 값은 DB 설정 또는 resolver 기본값으로 떨어져요.

파일과 우선순위

항목	현재 계약
canonical filename	`axhub.yaml`
legacy fallback	`apphub.yaml` (migration dual-read only)
max size	8 KiB
priority	manifest > DB AppSpecData > resolver default
deploy resolution	manifest → Dockerfile → Compose → Railpack auto-detection

최상위 필드

필드	타입	설명
`version`	string	현재 문서화 값은 `axhub/v1`. unknown 값은 forward-compatible하게 받아들일 수 있지만 known fields 검증은 유지돼요.
`name`	string	표시용 label. 저장된 앱 이름과 강제 동기화하지 않아요.
`runtime`	object	port와 health probe path.
`build`	object	build/deploy method와 command hints.
`env`	object	필요한 env 이름과 scope. 값은 절대 manifest에 저장하지 않아요.
`ci`	object	build 전 CI command와 timeout.

runtime

필드	타입	제한
`port`	integer	1~65535. 비어 있으면 Dockerfile `EXPOSE` 또는 adapter 기본값.
`health_path`	string	liveness/readiness probe path. 비어 있으면 `/` fallback.

build

필드	값	설명
`strategy`	`auto	pinned`
`framework`	`node	python
`install`	string	framework preset용 install command.
`build`	string	framework preset용 build command.
`start`	string	runtime start command.
`dockerfile`	path	기본 `Dockerfile` 대신 사용할 Dockerfile path.
`deploy_method`	`docker	compose`
`compose_file`	path	compose mode에서 사용할 compose file. 기본 `docker-compose.yml`.

deploy_method는 앱 DB에서도 immutable이에요. 바꾸려면 보통 새 앱으로 재생성해야 해요.

env

Manifest에는 env 이름과 scope만 적어요. 값은 axhub env set/update로 저장해요.

env:
  required:
    - name: DATABASE_URL
      scope: runtime
    - name: NEXT_PUBLIC_API_URL
      scope: build
  optional:
    - name: SENTRY_DSN
      scope: both

scope	주입 위치
`build`	build arg로만 전달
`runtime`	pod env로만 전달
`both`	build와 runtime 양쪽에 필요

이름은 비어 있거나 줄바꿈/= 문자를 포함할 수 없어요.

ci

필드	제한
`commands`	최대 10개
`timeout`	1~600초

CI command는 build 전에 실행되고, 실패하면 deploy가 멈춰요.