환경 변수 레퍼런스
스튜디오 서버가 읽는 환경 변수 전체입니다. 화면(환경설정)에서 바꾸는 값과 달리, 여기 값들은 파일을 고치고 재기동해야 반영됩니다.
정본은 /etc/kopens/plantpulse-studio.env
/etc/kopens/plantpulse-studio.env
.env 는 더 이상 읽지 않습니다옛 경로(설치 디렉터리의 .env)에 값을 넣어도 반영되지 않습니다. 옛 파일이 남아
있으면 스크립트가 그 사실을 알려 줍니다. 값을 고칠 때는 위 정본 경로를 쓰세요.
권한은 chmod 600 으로 두세요 — API 키가 들어 있는 파일입니다.
이미지와 버전
| 변수 | 기본값 | 설명 |
|---|---|---|
REGISTRY | docker.kopens.io/ps | 이미지를 받아올 레지스트리. 비우면 로컬 태그만 씁니다(직접 빌드한 경우) |
TAG | (빈 값) | 이미지 태그 |
AGENT_SERVER_TAG | 설치본마다 다름 | 에이전트 서버 이미지 태그 |
TAG 는 비워 두는 것이 권장입니다비워 두면 bin/start.sh 가 VERSION 파일의 칼버를 써서 릴리즈마다 자동으로 따라갑니다.
여기에 달을 손으로 적으면 그 값이 그대로 굳습니다 — 실제로 그래서 한 달 전 이미지가
뜬 적이 있습니다.
특정 릴리즈 시점에 고정하려면 스냅샷 태그를 쓰세요 — 예: TAG=2026.08-20260810.
로케일과 시간대
플랫폼·Edge 와 같은 변수 이름을 씁니다.
| 변수 | 기본값 | 설명 |
|---|---|---|
PP_LANG | en | 웹 기본 언어(ko / en). 브라우저에 저장된 값이 우선합니다 |
PP_TZ | Asia/Seoul | IANA 시간대 ID. "오늘 / 어제" 같은 상대 시간 해석 기준 |
한국어 현장이면 PP_LANG=ko 로 두세요.
데이터 저장 위치
| 변수 | 기본값 | 설명 |
|---|---|---|
DATA_ROOT | /var/lib/pp-studio | 워크스페이스·빌드 산출물·상태·번들 PG 데이터가 전부 이 아래 저장됩니다 |
백업 대상이 이 경로입니다 → 백업과 복구.
데이터베이스 — 두 모드 중 하나
(a) 번들 PostgreSQL (기본) — 스튜디오가 자기 PG 컨테이너를 띄웁니다.
| 변수 | 기본값 |
|---|---|
COMPOSE_PROFILES | bundled-pg |
PG_DB | ppstudio |
PG_USER | ppstudio |
PG_PASSWORD | change-me-please — 반드시 바꾸세요 |
(b) 공용 PostgreSQL — 플랫폼 PG 를 같이 씁니다(이중 인프라 제거).
COMPOSE_PROFILES 줄을 지우고 접속 주소만 지정합니다.
| 변수 | 예 |
|---|---|
DATABASE_URL | postgres://<user>:<password>@<db-host>:5432/ps |
번들 PG 는 첫 기동에서 데이터 디렉터리를 만들 때 계정을 굽습니다. 나중에 PG_PASSWORD
만 고치면 DB 안의 계정과 어긋나 스택이 뜨지 않습니다. 바꾸려면 PostgreSQL 안에서
계정 비밀번호를 먼저 바꾸세요 — 비밀번호 · API 키 변경
의 passwd.sh 가 그 순서를 대신 밟아 줍니다.
플랫폼 연동
| 변수 | 예 | 설명 |
|---|---|---|
PLATFORM_API_TARGET | https://192.168.0.41 | 실데이터 조회와 로그인 인증을 위임하는 플랫폼 주소 |
앱 리스너 (프리뷰 · 배포앱)
| 변수 | 기본값 | 설명 |
|---|---|---|
APPS_PORT | 5171 | 프리뷰와 배포된 앱을 서빙하는 별도 리스너 포트 |
- 포트로 직접 접속하는 설치 — 방화벽에서 이 포트도 열어야 프리뷰·배포앱·QR 접속이 됩니다.
- 리버스 프록시 뒤 — 열지 않아도 됩니다. 프록시가 같은 도메인의
/container·/preview·/apps를 이 리스너로 넘깁니다 → 도메인과 리버스 프록시.
APPS_ORIGIN)은 없어졌습니다2026-08-23 에 제거했습니다. 그 값이 비면 프리뷰 URL 이 요청호스트:5171 로 떨어져
80/443 만 공개하는 구성에서 라이브 프리뷰가 통째로 죽었습니다. 지금은 클라이언트가
상대 경로만 씁니다.
AI 프로바이더
여기 값은 초기값입니다. 화면(환경설정 → AI)에서 넣은 값이 이 값을 덮습니다.
| 변수 | 기본값 | 설명 |
|---|---|---|
AI_PROVIDER | openai-compatible | 비우면 언제나 openai-compatible 입니다 |
AI_BASE_URL | (빈 값) | 게이트웨이 주소. 기본값을 두지 않습니다 |
AI_MODEL | gpt-4o | 모델명 |
AI_API_KEY | (빈 값) | OpenAI 호환 키 |
ANTHROPIC_API_KEY | (빈 값) | 클라우드 Claude 를 쓸 때만 |
AI_BASE_URL 에 그럴듯한 기본값을 넣지 않는 이유게이트웨이가 그 호스트에 없으면 채팅이 통째로 fetch failed 가 되는데, 값이 그럴듯해
보여 원인 찾기가 비쌉니다. 실제 주소를 적으세요. 넣은 값이 맞는지는 환경설정 → AI 탭의
연결 테스트로 저장 전에 확인할 수 있습니다 → 환경설정(관리자).
예전에는 어떤 키가 들어 있느냐로 프로바이더를 골랐는데, env 구성에 따라 무엇으로 뜰지 예측할 수 없어 없앴습니다(2026-08-23).
CORS
| 변수 | 기본값 | 설명 |
|---|---|---|
STUDIO_CORS_ORIGINS | (빈 값 = same-origin) | 별도 도메인에서 접근할 때만 지정 |
env 로 나르지 않는 것
사용자 계정과 역할은 환경 변수로 정하지 않습니다. 서버가 계정이 하나도 없을 때
관리자 하나를 DB 에 심고, 그 뒤로는 앱의 사용자 관리 화면에서 추가·삭제하고
역할(admin / builder / viewer)도 거기서 줍니다.
관련 문서
- 설치 — 처음 값을 채우는 절차
- 비밀 관리 — 키를 어디에 두는가
- 환경설정(관리자) — 화면에서 바꾸는 값
- 도메인과 리버스 프록시