배포 규격·SSO 헤더

AxHub가 내 앱을 어떻게 빌드하는지, 로그인한 사용자를 어떻게 읽는지 — 개발자가 알아야 할 두 가지예요.

앱을 직접 손보는 개발자가 알아야 할 핵심은 두 가지예요 — AxHub가 내 코드를 어떻게 빌드하는지(배포 규격), 그리고 로그인한 사용자를 어떻게 읽는지(SSO 헤더). 템플릿으로 만든 앱은 이 둘이 이미 맞춰져 있고, 코드를 직접 올릴 때 알아두면 돼요.

배포 규격 — AxHub가 빌드를 정하는 순서

AxHub는 저장소 파일을 보고 이 순서로 빌드 방법을 정해요. 위에서 하나라도 맞으면 거기서 멈춰요.

axhub.yaml — 있으면 이 manifest를 우선 적용
Dockerfile — 루트에 있으면 단일 이미지로 빌드
Compose 파일 — docker-compose.yml · docker-compose.yaml · compose.yaml · compose.yml
Railpack 자동 감지 — 위가 없으면 마커 파일로 프레임워크를 추론 (package.json→node, go.mod→go, requirements.txt/pyproject.toml→python, Cargo.toml→rust 등)

넷 다 없으면 빌드할 수 없어 실패해요.

빌드·실행 명령이 애매하거나 고정하고 싶으면 axhub.yaml을 두세요.

axhub.yaml

version: axhub/v1
runtime:
  port: 3000
  health_path: /
build:
  deploy_method: docker
  dockerfile: Dockerfile
env:
  required:
    - name: DATABASE_URL
      scope: runtime

axhub.yaml은 옛 apphub.yaml을 대신하는 현재 이름이에요. 둘 다 있으면 axhub.yaml이 우선해요. 전체 필드는 axhub.yaml 레퍼런스에 있어요.

SSO 헤더 — 로그인한 사용자 읽기

AxHub 뒤에 있는 앱은 자체 로그인을 만들 필요가 없어요. 게이트가 인증을 처리하고, 통과한 요청에 사용자 정보 6개 헤더를 붙여 줘요.

헤더	값
`X-AxHub-User-ID`	사용자 UUID
`X-AxHub-User-Email`	base64로 인코딩된 이메일
`X-AxHub-User-Name`	base64로 인코딩된 이름
`X-AxHub-App-Role`	`owner` · `platform_admin` · `tenant_admin` · `app_member` · `tenant_member`
`X-AxHub-Is-Admin`	`true` · `false`
`X-AxHub-Tenant-Slug`	테넌트 slug

서버에서 이렇게 읽어요.

export function currentAxHubUser(req: Request) {
  const h = req.headers;
  return {
    id: h.get('x-axhub-user-id'),
    email: Buffer.from(h.get('x-axhub-user-email') ?? '', 'base64').toString('utf8'),
    name: Buffer.from(h.get('x-axhub-user-name') ?? '', 'base64').toString('utf8'),
    role: h.get('x-axhub-app-role'),
    isAdmin: h.get('x-axhub-is-admin') === 'true',
    tenant: h.get('x-axhub-tenant-slug'),
  };
}

반드시 서버에서 읽으세요. 클라이언트가 보낸 X-AxHub-* 값은 게이트가 덮어써요 — 접근이 거부되면 6개 헤더가 모두 빈 값으로 와요. 그래서 X-AxHub-User-ID가 비어 있으면 미인증으로 처리하면 돼요.

코드 바꾸면 다시 배포

연결된 저장소에 새 commit을 push하면 배포가 다시 시작돼요. 웹 콘솔의 배포 탭에서 수동으로 새 배포를 만들 수도 있어요.