Skip to main content

Frequently Asked Questions (FAQ)

Search by symptom or question. Answers are kept short, with detailed procedures linked.

Configuration​

Sidecar fixed, but the change isn't applied​

There is no sidecar file inside the container. Values enter as environment variables when compose recreates the container. docker restart merely restarts it with the same environment variables.

cd /opt/kopens/plantpulse-platform-docker/bin
./restart-datalake.sh

If it still doesn't work, check ① which file is winning via bin/env.sh --print, and ② whether compose passes that name to the data lake → When changes aren't applied

Edited config files inside the container, but they reverted​

That's expected. Everything under PP_HOME inside conf/ is a generated artifact, and pd start rewrites it from a template on each load. The place to edit is /etc/kopens/conf/<파일>.template on the host → Editing templates

export PP_PG_PASSWORD=… bin/up.sh is silently ignored​

If the sidecar already carries that name, the sidecar wins. The only way to change a value on an already-installed node is bin/passwd.sh → Changing passwords · API keys

Uploaded a new image, but the new config defaults didn't come in​

/etc/kopens/conf is a host file and won't change by itself. The startup tool merges three-way on each deployment, but preserves operator-edited files and notifies via [WARN] operator edit kept, but THE IMAGE DEFAULT CHANGED. That file must be merged manually.

docker exec plantpulse-datalake pd config diff --templates     # differs / missing 인 파일
TEMPLATE_FORCE_SEED=1 ./restart-datalake.sh                    # 통째로 이미지 기본값으로 (백업은 도구가 남긴다)

Other boxes (edge · AI · worker) can't connect to this data lake​

Check whether the node file contains this host's LAN address. If left empty, it uses the address inside the compose network (10.99.0.100), so communication only works within the same box.

sudo vi /etc/kopens/platform.node.env      # PP_MASTER_IP=<이 호스트의 LAN IP>
./restart-datalake.sh

If only Kafka won't connect, it's the advertised address → Node file

Renderer rejects with exit 8​

The advertised address is 127.0.0.1. Provide the actual address in PP_HOST_IP · PP_MASTER_IP · PP_KAFKA_ADVERTISED_HOST of the node file. The error message tells you which name to fix.

Renderer stops with exit 3 or exit 4​

  • exit 3 — a required secret is empty. The message lists all names. Put them in the sidecar and recreate.
  • exit 4 — the ${PP_*} in the template has no value. It appears in the message as 이름@템플릿:줄. Provide a value in the node file or edit the template.

Can I turn off a single component (e.g., Hive)?​

There's an pd switch in PD_OPTIONS='{"enable-hive": false}', but the current compose stack does not pass this variable to the container. Even if you write it in the sidecar or node file, it doesn't reach the container, so nothing gets disabled. This has been reported as a product-side improvement needed. The old name PP_OPTIONS is not read anywhere.

How to change the language to Korean​

Write PP_LANG=ko in the sidecar and run restart.sh (since it affects the app as well, a full restart is required). The management console is separate — append ?lang=ko to the URL.

Passwords · Accounts​

Changed the password, but the platform won't load​

Only one side has been updated — either the server-side account or the sidecar. First verify which value is valid.

docker exec plantpulse-datalake bash -c 'PGPASSWORD="<구값>" psql -U plantpulse -h 127.0.0.1 -c "SELECT 1;"'
docker exec plantpulse-datalake bash -c 'PGPASSWORD="<신값>" psql -U plantpulse -h 127.0.0.1 -c "SELECT 1;"'

If you can log in with the old value, the server side hasn't been updated. If you can log in with the new value, just fix the sidecar. From now on, use passwd.sh → Changing passwords · API keys

passwd.sh rejects with «variable not in the registry»​

That key isn't eligible for rotation. Only the 11 items listed in --list are. The rest require manual procedures. If it's a typo, it suggests similar keys.

Rotation failed partway through​

Run the exact same command again. The journal knows how far it got and continues from there. There is no rollback. If it ends with probe=NEITHER or verify 실패, a human must connect directly to that component and check its state.

Worker nodes exist, but passwd.sh rejects​

This is intentional. If you rotate only the master, workers retain the old value, leaving the cluster half-updated. Follow the manual procedure, then update the sidecar and restart each worker.

Management console login screen says «not configured»​

PP_DATALAKE_ADMIN_PASSWORD is empty. This is not an outage.

bin/passwd.sh PP_DATALAKE_ADMIN_PASSWORD     # --list 에 이 키가 있으면
# 없으면 (2026-09-05 이전 패키지) 사이드카에 줄을 적고 ./restart-datalake.sh

→ Web console login accounts

Data Gateway · CEP console logins fail​

PP_DATA_GATEWAY_WEB_PASSWORD · PP_CEP_WEB_PASSWORD have no defaults, and if empty, only that console is closed. Write them in the sidecar and run restart-datalake.sh → Query consoles

Dashboards in PlantPulse Dashboard revert when the container is recreated​

Resolved as of 2026-09-08. The PlantPulse Dashboard repository has been moved from in-image SQLite to PostgreSQL, so dashboards · data sources · users · alert rules survive container recreation.

If you have an existing installation, 🔴 existing content does not migrate automatically. Pointing to an empty PostgreSQL results in an empty PlantPulse Dashboard → Time series · PlantPulse Dashboard

pd start stops with exit 3 (PlantPulse Dashboard)​

PP_GRAFANA_DB_PASSWORD is empty. This became a startup-required value on 2026-09-08 — put it in the sidecar and restart.

SQL tool card disappeared​

SQL runs in the Data Gateway console (https://<server-ip>:5501/). The Data Gateway card is on the Tools screen of the management console.

Startup · Status​

pd status shows one STOPPED, but it just started​

This is startup in progress. Kyuubi in analytics starts last, taking about 54 seconds from spark-master. Check again after a minute. If it persists, see pd logs --lines 100 <서비스>.

docker ps is Up, but all services are dead​

Suspect memory OOM. Since PID 1 is systemd, only Java dies while the container stays alive.

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

→ Increasing the memory limit

pd stop ended with STILL RUNNING (exit 7)​

Don't immediately pd start. Check what's left with pd kill --dry-run, confirm it's empty with pd kill → pd status, then pd start.

pd start rejects as «already running»​

It's already running. To bring it up again, start from pd stop. Don't use FORCE=1 — it starts another process on the same port on top of a live one.

First boot takes over 10 minutes​

On first boot, Aster TSDB schema creation can take up to 500 seconds for storage alone. That's why the container startup grace period is 900 seconds. Watch progress via bin/logs.sh -f plantpulse-datalake.

Console shows «Another job is already running on this node»​

This is a symptom of admin-api images prior to 2026-09-04. Check pd env of IMAGE_BUILT_AT, and if it's old, update.sh. Even with new images, the «Run inspection» button accepts only one at a time — wait a moment and try again.

pd gives «command not found» on the host​

pd exists only inside the container. Enter via docker exec plantpulse-datalake pd … or bin/shell.sh and run it there.

Data​

Data isn't coming in​

Use pd flow to see where the MQTT → Kafka → consumer chain is blocked.

docker exec plantpulse-datalake pd flow

If LAG is large, the consumer (server · CEP · batch) is slow or stopped. NA means «never read» — if MEMB is 0, the consumer isn't running; if it's greater than 0 but the topic is empty, that's normal. The Topology screen in the management console shows the same thing graphically.

Disk is filling up / not shrinking​

docker exec plantpulse-datalake pd storage        # 얼마나 있나 — 볼륨 · WAL · 슬롯 · 스냅샷
docker exec plantpulse-datalake pd retention      # 언제 사라지나 — TTL · 토픽 보존 · 콜드 티어
  • If snapshots in Aster TSDB is large, run pd node cleanup (snapshot deletion — destructive).
  • If slot.orphan appears, a removed worker's replication slot is holding onto the WAL — check host ops-check.sh --reclaim.
  • If it's logs from a stopped module, use pd clean.
  • In pd retention, TTL none doesn't mean «no expiry» — it means «no table default». Tables with a per-row TTL (ts_data_points) still expire normally.
  • If last advance of cold_tier hasn't moved in over 48 hours, the archive job is stalled — this is often the real cause of the hot disk not shrinking.

Kafka shows DOWN with «advertises 127.0.0.1»​

The node file's address is empty → Node file. The broker.properties · server.properties inside the container are example files from the Kafka distribution — don't be alarmed. The broker reads only kafka.properties.

Time series data disappears after a few days​

The lifespan of a single time series point is PP_TSE_DATAPOINT_TTL (default 365 days). Before 2026-09-05, it was a 31-day literal. The value is stamped at write time, so raising it doesn't resurrect already-written rows → Variable reference

Backup​

How do I see if backups are being taken?​

docker exec plantpulse-datalake pd backup schedule      # 잡 다섯의 일정 · 마지막 결과
docker exec plantpulse-datalake pd backup list          # 세트 목록

The Backup screen in the management console shows the same → Backup · restore

How to change the night backup time​

docker exec plantpulse-datalake pd backup schedule set --job postgres-diff --cron "0 45 2 * * ?"

It survives container recreation — the value is stored in the backup_schedule row of the data lake DB.

--calendar is an old flag

It's still accepted, but a warning appears. Worse, it passes the value through as-is — this column holds a Quartz cron (초 분 시 일 월 요일, six fields). Writing systemd syntax (*-*-* 02:45:00) stores an invalid expression. Use --cron instead.

cassandra-full stays at fail (exit 120 (medusa))​

Images prior to 2026-09-04 never filled in Medusa settings, so backups failed daily. Now pd rewrites it at Aster TSDB startup — verify with pd restart storage after pd backup run --engine cassandra --type full.

Logs​

Where do I see logs?​

On the host, use bin/logs.sh plantpulse-datalake (last 200 lines, follow with -f); inside the container, use pd logs [서비스]. App container logs aren't in pd logs — view them via logs.sh <서비스> → Logs and health

I want to know who took a service down and when​

Check the event journal plantpulse-datalake-admin-api/logs/pd-events.jsonl, or the Events screen in the management console. Commands run in the console are recorded as operator:<name>. Settings changed in the console appear on the Audit screen.

See Also​