환경 변수 레퍼런스
PlantPulse 의 모든 설정은 환경 변수 한 곳에서 출발합니다. 이 페이지는 설치·운영 시 만나는 변수를 카테고리별로 정리한 레퍼런스입니다.
이 페이지는 인프라/배포 환경 변수(
PP_*·DOCKER_PP_*) 를 다룹니다. 애플리케이션 동작 프로퍼티(engine.*,websocket.*등)는 프로퍼티 레퍼런스 를 참고해 주세요.
1. 설정 파일은 어디에 있나요?
플랫폼은 Docker Compose 스택으로 동작하며, 값의 정의처가 둘입니다.
| 정의처 | 무엇이 여기 있나 | 누가 읽나 |
|---|---|---|
plantpulse-platform-docker/bin/env.sh | 호스트에서 정해지는 값 — 자격증명 기본값, docker 런타임, 네트워크, 호스트에서 계산되는 자원값 | 호스트의 운영 스크립트 |
plantpulse-platform-docker/compose/docker-compose.yml | 컨테이너가 실제로 보는 값 | 컨테이너 |
env.sh 를 읽지 않습니다앱 여섯(plantpulse-server-web · plantpulse-batch-web · plantpulse-warehouse · plantpulse-plugin-opcua-server · plantpulse-plugin-aasx-server · plantpulse-ha)은 env.sh 를 source 하지 않습니다. 앱이 보는 정의처는 compose 하나뿐입니다.
즉 env.sh 에만 있고 compose 에 없는 이름은 앱에 닿지 않고, 앱은 jar/WAR 내장 기본값으로 삽니다. 실제로 데이터레이크에서만 식별자를 바꾼 사이트에서 앱 다섯이 옛 이름을 계속 쓴 사고가 있었습니다(2026-08-29).
티어마다 값이 결정되는 방식이 다릅니다.
| 티어 | 무엇이 값을 결정하나 |
|---|---|
plantpulse-datalake | compose 가 넘긴 값 → 컨테이너의 pd 가 ${VAR:-기본값} 으로 받습니다. 넘긴 값이 이깁니다 |
| 앱 여섯 | compose 가 넘긴 환경변수가 jar/WAR 내장 기본값을 덮습니다 |
plantpulse-certs | compose 의 PP_TLS_* 만 봅니다. 파일을 source 하지 않습니다 |
우선순위 — 무엇이 무엇을 이기나
호스트 쪽에서 bin/env.sh 가 위에서 아래로 도는 순서가 곧 우선순위입니다.
| 우선순위 | 출처 | 이기는 이유 |
|---|---|---|
| 1 (최상) | /etc/kopens/plantpulse-platform.env (시크릿 사이드카) | export VAR=값 무조건 대입이라 셸 export 도 덮습니다 |
| 2 | /etc/kopens/platform.node.env (노드별) | 사이드카 다음에 source, 역시 무조건 대입 |
| 3 | 호출 셸의 export | 기본값의 :- 를 이깁니다 — 단 1·2 가 그 이름을 안 적었을 때만 |
| 4 (최하) | bin/env.sh 의 ${VAR:-기본값} | unset 일 때만 |
설치가 끝난 노드에서 PP_PG_PASSWORD=새값 bin/up.sh 는 조용히 무시됩니다. 사이드카가 이미 그 이름을 들고 있기 때문입니다. 값을 바꾸는 방법은 bin/passwd.sh / bin/rotate-secret.sh 뿐입니다.
🔑 비밀값의 정본은 /etc/kopens/ 밑이다
서비스 계정 비밀번호(PP_PG_PASSWORD · PP_CASSANDRA_PASSWORD · PP_MQ_PASSWORD 등)와 API 키의 실제 값은 repo 트리 밖의 사이드카 파일에 있습니다.
| 파일 | 상태 |
|---|---|
/etc/kopens/plantpulse-platform.env | 현행 정본 — platform · ai · studio 세 제품 공통 규약(plantpulse-<제품>.env), 권한 0600 |
/opt/kopens/plantpulse-platform.env | 옛 경로 (2026-08-25 ~ 08-29 에만 존재) — 읽지도 쓰지도 않습니다. 남아 있으면 설치 스크립트가 정본으로 되돌립니다 |
ls -l /etc/kopens/ 로 정본이 있는지 먼저 확인하세요.
사이드카가 bin/env.sh 를 이깁니다. env.sh 는 맨 위에서 사이드카를 먼저 source 하고, 그 아래 값들이 전부 ${VAR:-기본값} 형태이기 때문입니다. 그래서 env.sh 의 비밀번호만 고치면 아무 일도 일어나지 않습니다 — 사이드카의 옛 값이 계속 이깁니다.
install.sh 는 bin/env.sh 의 기본값을 그대로 사이드카에 싣습니다. 그러니 커미셔닝 때 반드시 교체해야 합니다 → 초기 비밀번호
compose 는 비밀번호를 ${PP_X:?} 로 요구하므로, 값이 비어 있으면 스택이 «반쯤 설정된 채로 부팅»하지 않고 아예 뜨지 않습니다.
사이드카를 고치는 것만으로는 반영이 끝나지 않습니다. PostgreSQL · Cassandra 처럼 서버 계정이 정본인 값은 서버측도 함께 바꿔야 하고, 순서를 틀리면 플랫폼이 기동하지 않습니다.
전용 절차를 쓰세요 — 비밀번호 변경 (크리덴셜 회전). 커미셔닝 때 한 번 바꾸고 끝내는 작업입니다.
🔑 표시는 비밀값입니다. git·이슈·채팅에 원문을 넣지 마세요.
1.5 컨테이너 런타임 · 호스트 자원 (DOCKER_*)
bin/env.sh 가 정하는 값입니다. 아래 자원값은 고정 기본값이 아니라 호스트를 보고 계산됩니다 — 상수를 쓰면 작은 호스트에서 기동 자체가 거부되거나(--cpus 가 실제 코어보다 크면 docker 가 거부합니다) 부팅 중 OOM-kill 되기 때문입니다. 박스별로 지정한 값이 항상 이깁니다.
| 변수 | 어떻게 정해지나 |
|---|---|
DOCKER_CMD | docker (podman 도 가능) |
DOCKER_REGISTRY | docker.kopens.io/pp — 스택 이미지 여덟의 레지스트리 prefix |
PP_IMAGE_TAG | latest. 릴리즈 시에는 2026.08 같은 고정 태그를 권장합니다 |
DOCKER_PP_CPUS | nproc (읽기 실패 시 8) |
DOCKER_PP_CLUSTER_CORES | DOCKER_PP_CPUS - 2, 최소 4 · 최대 30. 컨테이너에 PP_CLUSTER_CORES 로 전달 |
DOCKER_PP_MEMORY | 호스트 RAM 의 90%, 최소 8G |
DOCKER_DATALAKE_MEMORY | 80G. 호스트가 그보다 작으면 RAM 의 90% (2026-09-04 에 64G 에서 올랐습니다 — 아카이버의 spark-submit 이 이 컨테이너 안에서 돌게 되면서 64g 한계에서 OOM 이 났습니다. 실측 피크 63.9G) |
DOCKER_PW_MEMORY | DOCKER_DATALAKE_MEMORY 와 같은 값 — 워커가 데이터레이크와 같은 이미지를 쓰므로 같은 예산을 줍니다 |
DOCKER_PP_DATA_DISK_NAME | / 를 받치는 실제 디스크를 findmnt + lsblk 로 역추적 (LVM/dm 도 물리 디스크까지). 실패 시 sda |
DOCKER_PP_EXTERNAL_IP | 기본 빈 값. NAT 환경에서만 실제 공인 IP |
DOCKER_PP_EXTERNAL_IP 에 유효하지 않은 IP 를 넣지 마세요이 값은 PP_SERVICE_IP 를 거쳐 TLS 인증서의 SAN 으로 들어갑니다. 형식이 맞지 않는 IP 가 하나라도 섞이면 openssl 이 확장 파일 전체를 거부해 인증서가 한 장도 생성되지 않습니다.
네트워크
| 변수 | 기본값 | 설명 |
|---|---|---|
DOCKER_PP_NETWORK | pp-net | docker network 이름 |
DOCKER_SUBNET | 10.99.0.0/24 | 서브넷 (다른 컨테이너망과 겹치지 않게) |
DOCKER_GATEWAY | 10.99.0.1 | 게이트웨이 |
DOCKER_PP_IP | 10.99.0.100 | 데이터레이크의 고정 IP |
앱별 메모리 한계 — compose 가 정합니다
앱마다 mem_limit 을 따로 두는 것이 컨테이너 분리의 첫 번째 목적(OOM 격리) 입니다. 한 앱이 한계에 닿아도 다른 앱과 인프라는 살아 있습니다.
| 변수 | 기본값 | 서비스 |
|---|---|---|
DOCKER_SERVER_MEMORY / DOCKER_SERVER_HEAP | 16g / 12g | plantpulse-server-web |
DOCKER_BATCH_MEMORY / DOCKER_BATCH_HEAP | 4g / 3g | plantpulse-batch-web |
DOCKER_WAREHOUSE_MEMORY | 8g | plantpulse-warehouse |
DOCKER_OPCUA_MEMORY | 4g | plantpulse-plugin-opcua-server |
DOCKER_AASX_MEMORY | 4g | plantpulse-plugin-aasx-server |
DOCKER_HA_MEMORY | 2g | plantpulse-ha |
DOCKER_DATALAKE_MEMORY | 80g | plantpulse-datalake |
볼륨
| 변수 | 기본값 | 용도 |
|---|---|---|
DOCKER_PP_DATA_VOLUME | pp-data | 데이터 영구 저장 |
DOCKER_PP_TEMP_VOLUME | pp-temp | 임시 데이터 |
DOCKER_PP_BACKUP_VOLUME | pp-backup | 백업 저장소 |
DOCKER_PP_SECURITY_VOLUME | pp-security | TLS 자재 |
DOCKER_PP_PROXY_CERTS_VOLUME | pp-proxy-certs | 프록시 인증서 |
install.sh 일회성 옵션
| 변수 | 효과 |
|---|---|
SKIP_OS=1 | OS 셋업 생략 |
SKIP_LOGIN=1 | 레지스트리 로그인 생략 |
SKIP_FW=1 | 방화벽 설정 생략 |
DOCKER_DATA_DIR | Docker data-root 경로 (기본 /data1/docker-data) |
2. 최소한 이것만은 확인하세요
신규 단일 서버 설치에서 실제로 손대는 것은 몇 개 없습니다. 자원값은 설치가 호스트를 보고 계산하기 때문입니다.
| 무엇 | 어디서 | 비고 |
|---|---|---|
🔑 각종 *_PASSWORD · API 키 | bin/passwd.sh / bin/rotate-secret.sh | 커미셔닝 때 반드시 교체. 파일 편집으로는 바뀌지 않습니다 |
PP_LANG | bin/env.sh | 한국어 운영이면 ko (기본 en) |
PP_TZ | bin/env.sh | 한국 운영은 Asia/Seoul 유지 |
DOCKER_PP_EXTERNAL_IP | bin/env.sh | NAT 뒤일 때만. 아니면 빈 값 그대로 |
DOCKER_DATALAKE_MEMORY | bin/env.sh | 기본 80G. 호스트가 작으면 자동으로 낮아집니다 |
PP_* 는 «컨테이너가 보는 이름» 입니다PP_HOST_IP · PP_DATA_DIR · PP_CLUSTER_CORES 같은 값은 컨테이너 안에서 통하는 이름이고, 호스트에서 그 값을 정하는 것은 compose 와 bin/env.sh 의 DOCKER_* 입니다(§1.5). 예를 들어 코어 수는 DOCKER_PP_CLUSTER_CORES 가 계산해 컨테이너에 PP_CLUSTER_CORES 로 전달됩니다.
호스트에서 PP_CLUSTER_CORES 만 고쳐 놓고 반영되기를 기대하지 마세요 — 넘기지 않으면 16 vCPU 박스가 있지도 않은 30 코어를 믿고 Kyuubi 가 영영 뜨지 않습니다.
3. 플랫폼 기본 / 네트워크 / 자원
| 변수 | 기본값 | 설명 |
|---|---|---|
PP_HOME | /opt/kopens/plantpulse-platform | 설치 루트 (컨테이너 내부 동일) |
PP_SCHEME | PP | 배포 식별 스킴 |
PP_MODE | MASTER | 노드 역할 (MASTER / 워커) — 클러스터링(수평 확장) 축 |
PP_TIER | FULL | 이 노드가 띄우는 계층 게이트 (FULL / DATALAKE / APP) — PP_MODE 와 직교. FULL=인프라+앱 올인원, DATALAKE=인프라만, APP=앱만(원격 데이터레이크 접속). 상세는 2노드 분리 설치 |
PP_OPTIONS | {} | 개별 서비스 on/off 전용 JSON. 계층 게이트는 PP_TIER 로 이관됨 (아래 §3.3 참고) |
PP_HOST_IP | 127.0.0.1 | 이 노드의 IP |
PP_SERVICE_IP | 127.0.0.1 | 서비스 바인드 IP |
PP_MASTER_IP | 127.0.0.1 | 워커/APP 티어가 바라보는 마스터(데이터레이크) IP. Kafka advertised.listeners 의 소스이기도 함. DATALAKE 티어 설치 시 미지정이면 호스트 IP 로 자동 감지 |
PP_DATALAKE_ANCHOR | (파생) | 데이터스토어 HOST 5종의 기본 IP 앵커. APP 티어=PP_MASTER_IP(원격 데이터레이크), 그 외(FULL/DATALAKE)=PP_HOST_IP(자기 IP). 직접 설정하지 않는 파생값 (아래 §3.2 참고) |
PP_PUBLIC_IP | 127.0.0.1 | 외부 공개 IP (NAT 환경) |
PP_DATA_DIR | /data1/pp-data | 데이터 루트 |
PP_TEMP_DIR | /data1/pp-temp | 임시 파일 루트 |
PP_BACKUP_DIR | /data1/pp-backup | 백업 루트 |
PP_DATA_DISK_NAME | sdb | 데이터 디스크 장치명 |
PP_CLUSTER_CORES | 30 | 사용 코어 수 |
PP_CLUSTER_MEMORY_BY_CORE | 2G | 코어당 메모리 할당 |
PP_LANG | en | 기본 언어 |
PP_TZ | Asia/Seoul | 타임존 (모든 java 프로세스에 자동 적용) |
3.1 PP_TIER — 계층 기동 게이트
PP_TIER 는 이 노드가 어떤 계층을 기동할지 정하는 게이트입니다. 클러스터링 축인 PP_MODE(MASTER/WORKER)와 완전히 독립입니다.
PP_TIER | 기동 계층 |
|---|---|
FULL (기본) | 인프라 + 애플리케이션 (단일 박스 올인원 — 미지정 시 기존 설치와 동일) |
DATALAKE | 인프라 계층만 (Cassandra/PG/Kafka/MQTT/Redis/MinIO/Spark/Hive/TSE/CEP/Data Gateway/Temporal/Kestra/Monitor) |
APP | 애플리케이션 계층만 (Server/Batch/Warehouse/OPC-UA/AASX/HA — 원격 데이터레이크 접속) |
데이터레이크/애플리케이션을 두 박스로 나누는 절차는 2노드 분리 설치 를 참고해 주세요.
3.2 PP_DATALAKE_ANCHOR — 데이터스토어 앵커 (파생값)
개념:
PP_REDIS_HOST·PP_POSTGRES_HOST·PP_CASSANDRA_HOST·PP_MINIO_HOST·PP_TSE_HOST·PP_TEMPORAL_HOST·PP_KESTRA_HOST·PP_DATA_GATEWAY_HOST·PP_CEP_HOST의 기본 호스트는 모두${PP_DATALAKE_ANCHOR}로 해석됩니다.
APP티어에서는 저장소가 원격(데이터레이크 노드)이므로PP_DATALAKE_ANCHOR = PP_MASTER_IP.- 그 외(
FULL/DATALAKE)에서는 자기 IP 로 바인딩하므로PP_DATALAKE_ANCHOR = PP_HOST_IP.이 값은
PP_TIER로부터 자동 파생되므로 직접 설정하지 않습니다.APP노드는PP_MASTER_IP만 지정하면 모든 데이터스토어 호스트가 자동으로 데이터레이크를 가리킵니다.
3.3 PP_OPTIONS — 개별 서비스 on/off
PP_OPTIONS 는 개별 컴포넌트를 켜고 끄는 JSON 입니다. 기본값 {} 이며, 미지정 키는 모두 true(활성)로 간주됩니다. 계층 단위 활성화(구 use-infra / use-app)는 PP_TIER 로 이관되었습니다.
예) 외부 관리형 Redis 를 사용해 내장 Valkey 를 끄려면:
export PP_OPTIONS='{"enable-valkey":false}'
사용 가능한 enable-* 키 (전부 기본 true):
enable-messaging · enable-valkey · enable-postgres · enable-cassandra · enable-spark · enable-minio · enable-tse · enable-cep · enable-workflow · enable-data-gateway · enable-sql · enable-hive · enable-gravitino · enable-kyuubi · enable-grafana · enable-monitor
4. 데이터스토어
| 변수 | 기본값 | 설명 |
|---|---|---|
PP_REDIS_HOST / PP_REDIS_PORT | ${PP_DATALAKE_ANCHOR} / 6379 | Valkey/Redis (TLS 리스너 6380) |
PP_REDIS_USER / 🔑 PP_REDIS_PASSWORD | redis / — | Redis 계정 |
PP_POSTGRES_HOST / PP_POSTGRES_PORT | ${PP_DATALAKE_ANCHOR} / 5432 | PostgreSQL 18 (Percona) |
PP_PG_USER / 🔑 PP_PG_PASSWORD | plantpulse / — | PostgreSQL 계정 |
PP_CASSANDRA_HOST / PP_CASSANDRA_PORT | ${PP_DATALAKE_ANCHOR} / 9042 | Cassandra |
PP_CASSANDRA_USER / 🔑 PP_CASSANDRA_PASSWORD | cassandra / — | Cassandra 계정 |
PP_STORAGE_PORT | 9042 | 스토리지 계층 클라이언트가 재사용하는 Cassandra 포트 |
PP_MINIO_HOST / PP_MINIO_PORT | ${PP_DATALAKE_ANCHOR} / 9000 | MinIO 오브젝트 스토리지 |
PP_MINIO_USER / 🔑 PP_MINIO_PASSWORD | minio / — | MinIO 계정 |
PP_MINIO_BUCKET | plantpulse | 기본 버킷 |
PP_DB_NAME | pp | PostgreSQL 데이터베이스명 |
PP_KEYSPACE | pp | Cassandra 키스페이스명 |
PP_HIVE_DB | hive-metastore-230 | Hive 메타스토어 DB |
5. 메시징
| 변수 | 기본값 | 설명 |
|---|---|---|
PP_MQ_USER / 🔑 PP_MQ_PASSWORD | mq / — | Kafka·MQTT 공용 계정 (Kafka 전용 계정은 없습니다) |
PP_TOPIC_PREFIX | pp | Kafka 토픽 접두어 (pp-tag-point 등) |
PP_KAFKA_HOST / PP_KAFKA_PORT | PP_MASTER_IP / 9092 | Kafka 브로커 |
PP_KAFKA_TLS_PORT | 9094 | Kafka 외부 TLS |
PP_KAFKA_CONTROLLER_PORT | 9093 | Kafka KRaft 컨트롤러 |
PP_MQTT_HOST / PP_MQTT_PORT | PP_MASTER_IP / 1883 | MQTT (HiveMQ) |
PP_MQTT_TLS_PORT | 1884 | MQTT TLS |
브라우저 실시간 푸시가 SSE 로 바뀌면서 STOMP 브로커가 데이터레이크 이미지에서 제외되었습니다. PP_STOMP_* 변수와 61000/61004 포트는 더 이상 서비스되지 않습니다. 옛 방화벽 규칙에 남아 있다면 정리해 주세요.
6. 처리 · 시계열 · 분석 · 워크플로우
| 변수 | 기본값 | 설명 |
|---|---|---|
PP_CEP_HOST / PP_CEP_PORT / PP_CEP_TLS_PORT | ${PP_DATALAKE_ANCHOR} / 7400 / 7401 | CEP 서버 |
PP_CEP_PROTOCOL | http | CEP 접속 프로토콜. 분산/컨테이너는 https 권장 |
PP_CEP_CONNECT_PORT | (파생) | server-web→CEP 접속 포트. 프로토콜에 자동 정렬 (http→7400, https→7401). 명시하면 그 값 우선 |
PP_DATA_GATEWAY_HOST / PP_DATA_GATEWAY_PORT / PP_DATA_GATEWAY_TLS_PORT | ${PP_DATALAKE_ANCHOR} / 5500 / 5501 | Data Gateway |
PP_DATA_GATEWAY_PROTOCOL | http | DGW 접속 프로토콜 (내부 loopback 기본 http) |
PP_DATA_GATEWAY_CONNECT_PORT | (파생) | DGW 접속 포트. 프로토콜에 자동 정렬 (http→5500, https→5501). 명시하면 그 값 우선 |
PP_TSE_HOST / PP_TSE_PORT / PP_TSE_TLS_PORT | ${PP_DATALAKE_ANCHOR} / 7800 / 7801 | 시계열 엔진(TSE). 서버는 http 7800·https 7801 둘 다 listen |
PP_TSE_PROTOCOL | http | TSE 클라 접속 프로토콜. 내부 구간 통신이라 평문 http 기본 — TLS 마스터스위치(PP_TLS_ENABLED)와 분리(2026-08) |
PP_TSE_CONNECT_PORT | (미설정) | env.sh 가 export 하지 않는 운영자 명시 오버라이드 훅. 템플릿이 ${PP_TSE_CONNECT_PORT:7800} 폴백으로 소비 |
PP_TSE_JDBC_SCHEME | ts | JDBC scheme. 평문 ts 기본 (jdbc.tse.url 템플릿은 ts 하드코딩) |
PP_TSE_USER / 🔑 PP_TSE_PASSWORD | tse / — | TSE 계정 |
PP_ANALYTICS_USER / 🔑 PP_ANALYTICS_PASSWORD | spark / — | 분석(Spark/Kyuubi 클라) 계정. Kyuubi 내부 메타스토어(PP_HIVE_*)와 분리된 별도 자격증명 |
PP_HIVE_HOST / PP_HIVE_PORT | PP_MASTER_IP / 9083 | Hive 메타스토어 |
PP_HIVE_USER / 🔑 PP_HIVE_PASSWORD | hive / — | Hive 계정 |
PP_SPARK_HOST / PP_SPARK_PORT | PP_MASTER_IP / 7077 | Spark 마스터 |
PP_KYUUBI_PORT | 10000 | Kyuubi SQL 게이트웨이 |
PP_GRAVITINO_USER / 🔑 PP_GRAVITINO_PASSWORD | gravitino / — | Gravitino 카탈로그 |
PP_TEMPORAL_HOST / PP_TEMPORAL_PORT | ${PP_DATALAKE_ANCHOR} / 7233 | Temporal 엔진 (Web UI 8233) |
PP_TEMPORAL_USER / 🔑 PP_TEMPORAL_PASSWORD | temporal / — | Temporal 계정 |
PP_KESTRA_HOST / PP_KESTRA_PORT | ${PP_DATALAKE_ANCHOR} / 8380 | Kestra 스케줄러 |
PP_KESTRA_ADMIN_EMAIL / 🔑 PP_KESTRA_ADMIN_PASSWORD | admin@plantpulse.io / — | Kestra 관리자 |
PP_KESTRA_DB_USER / 🔑 PP_KESTRA_DB_PASSWORD | kestra / — | Kestra 메타 DB |
7. 플러그인 · 관측 · 웹 계층
| 변수 | 기본값 | 설명 |
|---|---|---|
PP_OPCUA_PORT / PP_OPCUA_TCP_PORT | 11004 | OPC-UA opc.tcp 프로토콜 포트 |
PP_OPCUA_TLS_PORT | 11005 | OPC-UA TLS |
PP_AAS_V3_PORT | 8090 | AAS(BaSyx V3) API. UI 는 8091, Registry/AAS 포트(4800/4801)는 코드에 고정되어 env 로 바뀌지 않습니다 |
PP_GRAFANA_PORT | 3000 | Grafana 대시보드 |
PP_GRAFANA_ADMIN_USER / 🔑 PP_GRAFANA_ADMIN_PASSWORD | admin / — | Grafana 관리자 |
PP_WEBSOCKET_PORT / PP_WEBSOCKET_PORT_SSL | 8000 / 8004 | 실시간 푸시 WebSocket |
PP_WEBSOCKET_USER / 🔑 PP_WEBSOCKET_SERVER_PASSWORD | ws / — | WebSocket 서버 계정 |
PP_MAIL_SMTP_PORT | 25 | 알람/리포트 메일 발송 SMTP |
PP_MAIL_SMTP_USER / 🔑 PP_MAIL_SMTP_PASSWORD | webmaster@kopens.com / — | SMTP 계정 |
PP_MAIL_SMTP_AUTH / PP_MAIL_SMTP_STARTTLS | false / false | SMTP 인증·STARTTLS |
8. TLS / SSL
| 변수 | 기본값 | 설명 |
|---|---|---|
PP_TLS_ENABLED | true | TLS 마스터 스위치 — 서비스 클라이언트 기본 프로토콜을 결정 |
PP_DEFAULT_PROTOCOL | (파생: PP_TLS_ENABLED) | 서비스 클라 기본 프로토콜. PP_TLS_ENABLED=true→https, false→http. TSE 등이 이 값을 상속해 프로토콜/포트가 스위치와 모순되지 않게 함 |
PP_TLS_CERT_DIR | /var/security/plantpulse | 인증서 디렉터리 |
PP_TLS_DOMAIN | plantpulse.io | 인증서 도메인 |
🔑 PP_TLS_KEYSTORE_PASSWORD / 🔑 PP_TLS_TRUSTSTORE_PASSWORD | — | keystore/truststore 비밀번호 (전 노드 동일해야 함) |
PP_TLS_VALID_DAYS | 3650 | 인증서 유효기간(일) |
PP_TLS_SAN_IPS | PP_HOST_IP,…,127.0.0.1 | 인증서 SAN IP. 운영에서는 외부 접속 IP(예: 공인 IP)를 반드시 포함 |
PP_TLS_SAN_DNS | localhost,<hostname>,<도메인> | 인증서 SAN DNS |
PP_TLS_NODE_NAMES | master worker-1 … worker-5 | 클러스터 노드 이름 |
PP_TLS_FORCE_REGENERATE | false | true 시 인증서 강제 재생성 |
9. API 키 / AI 게이트웨이
모두 개발용 기본값(fallback)이 있습니다. 운영/고객 납품 시 Docker
-e또는export로 반드시 교체하세요.
| 변수 | 설명 |
|---|---|
🔑 PP_API_KEY | 플랫폼 내부 API 키 (서버 ↔ 엣지 에이전트 인증) |
🔑 PP_DATA_GATEWAY_API_KEY | server-web → data-gateway JDBC 인증 |
🔑 PP_CEP_API_KEY | server-web → CEP 서버 X-API-Key (CEP 서버 cep.api.key 와 일치해야 함) |
🔑 PP_FLOW_WEBHOOK_API_KEY | Flow Engine 외부 웹훅 인증 |
PP_AI_OPENAI_ENABLED | AI 게이트웨이 활성화 (기본 false) |
PP_AI_OPENAI_BASE_URL | OpenAI 호환 LLM 프록시 URL (기본 https://api.openai.com) |
🔑 PP_AI_OPENAI_API_KEY | LLM API 키 (PP_AI_OPENAI_ENABLED=true 일 때 필요) |
PP_AI_OPENAI_MODEL | 사용할 모델 (기본 gpt-5-mini) |
10. 변경 후 적용 절차
cd /opt/kopens/plantpulse-platform-docker/bin
vi env.sh # 호스트 쪽 값 (DOCKER_* · PP_LANG · PP_TZ 등)
./restart.sh # 스택 재시작 — 준비될 때까지 대기 (종료 코드 0 = 쓸 수 있다)
컨테이너가 보는 값을 바꿔야 한다면 compose/docker-compose.yml 을 고친 뒤 같은 방법으로 재시작합니다. 설정 템플릿은 호스트의 /etc/kopens/conf 에 바인드 마운트되어 있어 호스트에서 바로 편집할 수 있고, 재설치해도 보존됩니다.
변수를 바꿨는데 반영이 안 된다면 순서대로 확인해 주세요.
| 확인 | 내용 |
|---|---|
| ① 사이드카가 이기고 있지 않은가 | /etc/kopens/plantpulse-platform.env 에 같은 이름이 있으면 env.sh 도 셸 export 도 집니다 → 우선순위 |
| ② 앱에 닿는 이름인가 | 앱 여섯은 env.sh 를 읽지 않습니다. compose 에 없으면 앱에 닿지 않습니다 |
| ③ 재시작했는가 | 로케일·타임존을 포함해 대부분의 값이 부팅 시점에만 반영됩니다 |
| ④ 비밀번호인가 | 비밀번호는 파일 편집으로 바뀌지 않습니다 → 비밀번호 회전 |
자세한 절차는 시작 가이드 를 참고해 주세요.
env-reset.sh 를 컨테이너 안에서 실행하지 마세요데이터레이크 컨테이너 안의 env-reset.sh 는 모든 PP_* 를 unset 한 뒤 env.sh 를 다시 읽는 개발 전용 도구입니다. 여기서 실행하면 compose 가 주입한 값까지 사라지고 이미지 내장 기본값으로 되돌아갑니다.