Skip to main content

How to Change Configuration

The file you edit and how the change takes effect depend on what you're changing. Find your case in the table below first.

What to changeExampleEditTakes effect
Passwords · API keysPostgreSQL password, CEP API keybin/passwd.shTool restarts automatically
This box's address · identityAddress for other boxes to connect, Kafka advertised address, NAT public IP/etc/kopens/platform.node.envbin/restart-datalake.sh
Non-secret values common to all nodesLanguage · timezone, backup schedule toggle, console log endpoint/etc/kopens/plantpulse-platform.envbin/restart-datalake.sh
Container resourcesData lake memory limit/etc/kopens/platform.node.env (DOCKER_DATALAKE_MEMORY)bin/restart-datalake.sh
Engine config «lines»postgresql.conf parameters, Kafka retention period, Cassandra heap/etc/kopens/conf/<파일>.templatebin/restart-datalake.sh or inside container pd config render + pd restart <서비스>
Backup scheduleNightly backup timeInside container pd backup schedule setImmediate
Published portsPort exposed to hostcompose/docker-compose.ymlbin/restart-datalake.sh — caution
Verification after changes is always the same
cd /opt/kopens/plantpulse-platform-docker/bin
./status.sh                                       # 0 = 정상
docker exec plantpulse-datalake pd config diff    # 런타임 파일 = 렌더 결과인가 (0 = 같다)
docker exec plantpulse-datalake pd doctor         # FAIL 0

1. Passwords · API keys​

Do not open the file. passwd.sh handles server-side account change → sidecar refresh → config re-render → restart in one command.

cd /opt/kopens/plantpulse-platform-docker
bin/passwd.sh --list                 # 바꿀 수 있는 키
bin/passwd.sh PP_PG_PASSWORD         # 값은 프롬프트로 (권장)

Details are in Change passwords · API keys.

2. This box's address and identity — node file​

/etc/kopens/platform.node.env is the file for values that are true only on this box. Do not copy it to another box — we have actually seen a second box silently reinstall with the wrong role when a file from one box was copied to it.

VariableWhen to setIf empty
PP_MASTER_IPWhen another box (Edge, AI, Worker) must connect to this data lake — the LAN address of this hostAddress within compose network (10.99.0.100) — integration only within the same box
PP_KAFKA_ADVERTISED_HOSTOnly when behind NAT or connecting to Kafka via a second interfaceTool prompts at startup (operator value > PP_MASTER_IP > host default IP). Usually leave empty
DOCKER_PP_EXTERNAL_IPPublic IP in NAT environment. Goes into TLS certificate SANLeave empty — putting a wrong IP will prevent any certificate from being generated
PP_NODE_IDWhen there are two or more boxes, a short unique name for this boxDerived from container hostname — with two boxes they push each other out. Set before attaching the second box
sudo vi /etc/kopens/platform.node.env
#   PP_MASTER_IP=192.168.10.20

cd /opt/kopens/plantpulse-platform-docker/bin
./restart-datalake.sh        # 데이터레이크만 재생성 + 준비 대기 + 의존 앱 판정
If advertised address is 127.0.0.1, render rejects it (exit 8)

When the server tells a client «reconnect here» (Kafka advertised.listeners, Cassandra broadcast_rpc_address, Temporal broadcastAddress) and the address is loopback, that server works fine locally but every other container connects to itself. All port checks show UP yet clients cannot connect at all. The error message names what to fix — PP_HOST_IP · PP_MASTER_IP · PP_KAFKA_ADVERTISED_HOST in the node file.

3. Non-secret values common to all nodes — sidecar​

The sidecar /etc/kopens/plantpulse-platform.env is not just for secrets. Non-secret common values also go in as VAR=값 one line per variable, and bin/env.sh reads them and passes them to compose. All available variables are in compose/platform.env.example with comments — pick lines from there and copy them.

Commonly used:

VariableDefaultMeaning
PP_LANGenIf operating in Korean, set to ko
PP_TZAsia/SeoulTime series are stored as this timezone epoch; Korean operations should maintain it
PP_BACKUP_SCHEDULE_ENABLEDtrueIf false, backup timers log only «skipped» and exit
PP_DATALAKE_ADMIN_LOGS_ENABLEDtrueIf false, only console log screen (endpoint) goes down
PP_KEYSPACE · PP_DB_NAME · PP_TOPIC_PREFIXppIdentifiers data lake «creates» and app «reads». Do not change after installation
sudo vi /etc/kopens/plantpulse-platform.env
#   PP_LANG=ko

cd /opt/kopens/plantpulse-platform-docker/bin
./restart.sh                 # 언어 · 타임존은 앱에도 닿으므로 전체 재시작
Do not touch the first two lines of the sidecar

# generated: and # last rotation: are managed by the tool. The rest only need VAR=값. Old export VAR=값 lines are still read but rewritten in new format on next upgrade.

4. Container memory​

The data lake container's memory limit is in DOCKER_DATALAKE_MEMORY. Default 80G; if the host is smaller, it auto-calculates to 90% of RAM. The value differs per box, so it goes in the node file.

sudo vi /etc/kopens/platform.node.env
#   DOCKER_DATALAKE_MEMORY=64g

cd /opt/kopens/plantpulse-platform-docker/bin
./restart-datalake.sh
Too small and you get «Up but dead»

PID 1 inside the container is systemd, so only the Java process gets OOM-killed by cgroup while docker ps keeps showing Up. Kill records live only in the host's dmesg. This actually happened on 2026-09-04 at a 64G limit (measured peak 63.9G), which is why the default rose to 80G.

dmesg -T | grep -i "memory cgroup"
docker inspect plantpulse-datalake --format '{{.State.OOMKilled}}'

5. Engine config «lines» — templates​

When you add lines, not values — like adding parameters to postgresql.conf or changing Kafka's retention period — you edit the template on the host. Which template becomes which file is in template list.

# 1. 호스트에서 템플릿 편집
sudo vi /etc/kopens/conf/postgresql.conf.template

# 2-a. 데이터레이크 전체 재시작 — 기동 때 자동 렌더
cd /opt/kopens/plantpulse-platform-docker/bin
./restart-datalake.sh

# 2-b. 또는 서비스 하나만 — 컨테이너 안에서
docker exec plantpulse-datalake pd config diff        # 무엇이 바뀔지 먼저 본다
docker exec plantpulse-datalake pd config render      # 생성물을 실제로 쓴다
docker exec plantpulse-datalake pd restart storage    # 그 서비스만 재기동

# 3. 확인
docker exec plantpulse-datalake pd config diff        # 0 = 런타임이 렌더 결과와 같다

Just running pd config render without restarting is not «applied». The file has changed, that is all. pd restart <서비스> completes the cycle.

When the image ships new defaults — 3-way merge​

/etc/kopens/conf is a host file, so it does not auto-change even when the image brings new defaults. That is why the startup tool compares sets per deployment — this image's default, the previous deployment's default (/etc/kopens/conf.dist), and the host file.

SituationWhat the tool does
Operator did not touch file, defaults changedReplace with new defaults
Operator edited file, defaults also changedKeep operator file as-is + [WARN] operator edit kept, but THE IMAGE DEFAULT CHANGED + print default change diff
Operator edited file, defaults unchangedKeep (silently)
Image adds a new templateInstall it
Image removes a templateLeave host file, warn

In output from restart.sh · update.sh, when you see [WARN] operator edit kept lines, you must merge by hand — your edits and the new defaults together. The same line tells you where the new defaults file is.

To see how your template differs from the image default, check inside the container.

docker exec plantpulse-datalake pd config diff --templates
#   same     — 같다
#   differs  — 호스트 사본이 다르다 (렌더는 이쪽을 쓴다)
#   local    — 운영자가 추가한 파일
#   missing  — 이미지엔 있는데 호스트엔 없다

To reset a host directory entirely to the image default (the tool backs up to /etc/kopens/conf.backup/<시각>/):

cd /opt/kopens/plantpulse-platform-docker/bin
TEMPLATE_FORCE_SEED=1 ./restart-datalake.sh
/etc/kopens/conf in batches before 2026-09-03 will self-reseed

If old plantpulse-startup batches (with no .template suffix in the filename) are still present, pd has nothing to render. The startup tool detects this, backs up, re-seeds from the image, and reports it with [WARN] stale template layout. Old edits survive only in the backup and are not auto-migrated.

6. Backup schedule​

Do not edit files. Inside the container, pd backup schedule set validates and writes systemd timers. The admin console's backup screen «Schedule editor» runs the same command.

docker exec plantpulse-datalake pd backup schedule                                   # 지금 일정
docker exec plantpulse-datalake pd backup schedule set --job postgres-diff --calendar "*-*-* 02:45:00"
docker exec plantpulse-datalake pd backup schedule set --job purge --enabled false
docker exec plantpulse-datalake pd backup schedule reset --job postgres-diff         # 기본값으로

Five job names: postgres-diff · postgres-full · cassandra-diff · cassandra-full · purge. Calendar uses systemd syntax (*-*-* 02:45:00 every day, Sun *-*-* 01:00:00 Sundays). Malformed expressions are rejected and nothing is written. Your choice persists in /data1/pp-data/backup/schedule.json and survives container recreation → backup · restore

7. Published ports​

The ports exposed to the host are set by plantpulse-datalake service ports: in compose/docker-compose.yml. When changing them, watch two things:

  • The port the container listens on inside is set by defaults.env (PP_*_PORT) and templates. If you change only the published port, you get «container binds to 6379, compose publishes 6399» — a mismatch. You must review both.
  • 1883 / 1884 (MQTT) are published by the proxy container, not the data lake. Adding the same port to the data lake will fail startup with a bind conflict.

See ports and service management for the full port list and firewall.

When changes don't take effect — check in order​

CheckWhat to look for
① Which file winsbin/env.sh --print column # source:. Node file > sidecar > shell > defaults
② Is it a name compose knowsNames compose does not write are not injected → variable reference
③ Did you recreate the containerSidecar · node file values enter only on container recreation. docker restart is not enough — use restart-datalake.sh
④ Did it renderIs pd config diff zero? If 1, then pd config render then restart
⑤ Is it a passwordFile editing does not change passwords → passwd.sh
⑥ Is the template oldIn pd config diff --templates check differs · missing → 3-way merge above

Do not​

  • Do not edit PP_HOME/…/conf/* inside the container. It vanishes on next boot, and until it does, nobody knows which is real.
  • Do not try to apply value changes with docker restart plantpulse-datalake. Environment variables are set when you recreate the container. restart-datalake.sh does that job.
  • Do not use FORCE=1 pd start. It binds another process to the same port.
  • Do not change PP_KEYSPACE · PP_DB_NAME · PP_TOPIC_PREFIX after installation. A new empty repository is created and old data stays under the old name.