환경변수

API 키·DB 주소 같은 설정값을 코드 밖에 안전하게 두고, 빌드/실행 시점에 주입하는 방법이에요.

환경변수는 API 키, DB 주소처럼 코드에 박으면 안 되는 설정값을 두는 곳이에요. AxHub가 암호화해서 저장하고, 빌드하거나 앱을 실행할 때 주입해 줘요. 코드에는 process.env.DATABASE_URL처럼 이름으로만 읽으면 돼요.

어디서 설정하나요

웹 콘솔 — 앱 상세 → 환경변수 탭 → 변수 추가. Key, Value, Stage를 정해요.

환경변수를 추가하거나 바꾸면 다시 배포해야 적용돼요 — 실행 중인 앱에 자동으로 반영되지는 않아요. (Key는 만든 뒤엔 바꿀 수 없고, 값과 Stage만 수정할 수 있어요.)

CLI — axhub env set으로도 해요. 자세한 건 아래 CLI로.

이름 규칙

Key는 대문자로 시작하고 영문 대문자·숫자·밑줄(_)만 써요 — 패턴 ^[A-Z][A-Z0-9_]*$.

DATABASE_URL   OPENAI_API_KEY   NEXT_PUBLIC_API_URL   ✅
databaseUrl    1ST_KEY          MY-KEY                ❌

Stage — 언제 주입되나요

값이 어느 시점에 들어갈지 정해요.

Stage	언제 주입되나요	예시
Runtime (기본)	앱이 실행 중인 pod에만 (빌드 때는 없음)	DB 비밀번호, 외부 API 키
Build	빌드 시점 build-arg에만 (실행 때는 없음)	빌드에만 필요한 토큰
Both	빌드와 실행 양쪽 모두	양쪽에서 다 필요할 때

Runtime 전용 값은 빌드 로그나 이미지 캐시에 남지 않아요 — 비밀값은 Runtime으로 두는 게 안전해요.
프론트엔드 번들에 들어가는 NEXT_PUBLIC_·VITE_·PUBLIC_ 값은 브라우저에 그대로 노출돼요. 비밀값을 이런 이름으로 두면 안 돼요.

비밀값 다루기

비밀값으로 저장하면 화면·응답에서 ***로 가려지고 암호화돼 저장돼요. 코드·git·manifest에는 절대 넣지 마세요 — 이름과 Stage만 선언하고 값은 환경변수로 따로 둬요.

CLI로

# 일반 값 — KEY VALUE 를 그대로
axhub env set NEXT_PUBLIC_API_URL https://api.example.com --app demo --plain --stage build

# 비밀 값 — 값을 stdin 으로 받아 명령 기록에 안 남게
axhub env set DATABASE_URL --app demo --secret --stage runtime --from-stdin

axhub env list --app demo
axhub env get DATABASE_URL --app demo

--secret을 쓰면 값은 positional 대신 --from-stdin으로 넣어요(명령 히스토리·로그에 노출 방지).

manifest에 선언

axhub.yaml에는 이름과 stage만 적어요. 값은 절대 넣지 않아요.

axhub.yaml

env:
  required:
    - name: DATABASE_URL
      scope: runtime
    - name: NEXT_PUBLIC_API_URL
      scope: build

manifest의 scope가 콘솔·CLI의 Stage와 같은 뜻이에요(build·runtime·both). 전체 스키마는 axhub.yaml 레퍼런스에 있어요.