axhub.yaml Reference

Canonical deploy manifest schema from the current ax-hub-backend manifest domain

axhub.yaml is the deploy contract committed to the app repository. The backend resolver reads axhub.yaml first and falls back to legacy apphub.yaml only for migration. If both exist, axhub.yaml wins.

Minimal example

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

All fields are optional. Unset values fall back to DB settings or resolver defaults.

Files and precedence

Item	Current contract
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

Top-level fields

Field	Type	Description
`version`	string	Documented value: `axhub/v1`. Unknown versions may be accepted for forward compatibility, but known fields are still checked.
`name`	string	Display-only label. Not enforced against stored app name.
`runtime`	object	Port and health probe path.
`build`	object	Build/deploy method and command hints.
`env`	object	Required/optional env names and scopes. Values never live here.
`ci`	object	Pre-build CI commands and timeout.

runtime

Field	Type	Limit
`port`	integer	1–65535. Falls back to Dockerfile `EXPOSE` or adapter default.
`health_path`	string	Liveness/readiness probe path. Empty falls back to `/`.

build

Field	Values	Description
`strategy`	`auto	pinned`
`framework`	`node	python
`install`	string	Install command for framework presets.
`build`	string	Build command.
`start`	string	Runtime start command.
`dockerfile`	path	Dockerfile path override.
`deploy_method`	`docker	compose`
`compose_file`	path	Compose file for compose mode. Default `docker-compose.yml`.

deploy_method is immutable on the app DB row. Changing it usually means recreating the app.

env

The manifest declares env names and scopes only. Store values via 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	Injection
`build`	build args only
`runtime`	pod env only
`both`	required in both channels

Names cannot be empty or contain newline/= characters.

ci

Field	Limit
`commands`	max 10
`timeout`	1–600 seconds

CI commands run before the image build. Failure stops the deploy.