FAQ
We have compiled a collection of frequently asked questions and answers for those operating the PlantPulse Platform. If you require more detailed procedures, please refer to the Troubleshooting page.
Installation / Licensing
Q. Which installation method should I choose?
A. One-line installation is the standard. A single command handles everything from OS setup to firewall configuration and container startup; updates and rollbacks are performed using the same tool. For air-gapped networks, see the Air-gapped procedure for Docker installation, and for installations on Kubernetes, see Kubernetes installation.
Q. Can it be installed in an air-gapped network?
A. Yes. Create a bundle using ./airgap-bundle.sh on a node with internet connectivity, transfer it to the air-gapped network via USB or an internal file server, and then execute ./airgap-load.sh. For detailed procedures, please refer to the Docker Installation - Air-gapped Installation section.
Q. How do I obtain a license?
A. Image registry credentials and licenses are issued by the KOPENS operations team. Please inquire via webmaster@kopens.com.
Q. What are the minimum and recommended specifications?
A. Based on a single node:
| Category | Minimum | Recommended |
|---|---|---|
| CPU | 16 vCPU | 32 vCPU |
| Memory | 128GB (Data Lake Master 96GB+, 64GB is not supported) | 256GB |
| Disk | 200GB | 1TB+ (Depending on data volume) |
| OS | RHEL · Rocky · Oracle Linux 8/9/10 · Ubuntu 22.04+ · Amazon Linux 2023 | Same |
For detailed specifications, please refer to the System Requirements page.
Q. Which OS are supported?
A. One-line installation is supported on the following OS:
- RHEL · Rocky Linux · Oracle Linux 8.x · 9.x · 10.x
- Ubuntu 22.04 or higher
- Amazon Linux 2 · 2023
On unverified OS, you can skip the OS setup and perform a manual setup using the SKIP_OS=1 option.
Q. Can it be operated with Podman?
A. Yes. If you change DOCKER_CMD="docker" in bin/env.sh to DOCKER_CMD="podman", all scripts will operate with Podman.
Installation / Startup
Q. How long does installation take?
A. For one-line installation, it takes approximately 10–20 minutes (depending on network speed) for OS setup + Docker installation + image download + container startup. Subsequent internal booting of containers takes an additional 3–5 minutes (Aster TSDB schema migration + JVM warm-up).
Q. Where should I connect after installation?
A. Please access the following address in your browser:
http://[서버IP]/
- The proxy container opens a single port 80. There is no separate management console port.
[서버IP]is the server address specified during installation.- Default administrator account:
admin/admin123! - Please change the password immediately after logging in.
Q. I started the system, but the health is displayed as unhealthy.
A. Booting takes 3–5 minutes. If the status remains unhealthy after 5 minutes, please refer to Troubleshooting - Container Startup Issues.
Q. I changed env.sh, but it is not applied.
A. Changes to env.sh are only reflected at the time of booting. You must restart using the following command for changes to take effect:
cd /opt/kopens/plantpulse-platform-docker/bin
./restart.sh
Q. How can I make the system start automatically after a server reboot?
A. Containers are executed with the --restart unless-stopped policy, so they start automatically when the Docker daemon starts. The Docker daemon itself is configured to start automatically at boot via systemctl enable docker.
Operation / Management
Q. How do I start, stop, or restart the Platform?
A. From the host's /opt/kopens/plantpulse-platform-docker/bin/:
./up.sh # 기동 — 준비될 때까지 대기 (종료 코드 0 = 쓸 수 있다)
./down.sh # 중지 (데이터 보존)
./restart.sh # 재시작 (graceful drain + 준비 대기)
./status.sh # 상태 요약 (0 = 정상 / 2 = 비정상)
For more details, please refer to the Startup Guide page.
Q. Can I restart specific components without restarting the entire system?
A. Yes. However, the method differs depending on whether it is an app or infrastructure.
Since the six apps run in their own containers, restarting the container is equivalent to restarting the app:
cd /opt/kopens/plantpulse-platform-docker
docker compose -f compose/docker-compose.yml restart plantpulse-server-web
Infrastructure components such as storage, analytics, and messaging run together within the data lake container, so you must enter the container and use individual scripts:
./shell.sh
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd restart storage
exit
For a detailed list, refer to Startup Guide — Component-level Restart.
Q. Where can I view the logs?
A. You can view standard container logs from the host and detailed module-specific logs from within the container:
# 전체 컨테이너 로그를 한 화면에 (서비스 이름 접두, 시간순)
./logs.sh
# 특정 컨테이너만
./logs.sh plantpulse-server-web -n 200
# 데이터레이크 안 컴포넌트 로그 파일
./logs.sh cassandra
# 볼 수 있는 대상 전체 목록
./logs.sh --list
# 모듈별 로그를 호스트로 한 번에 복사
./tools/copy-log-to-local.sh
Since there are eight containers, you may miss the cause if you look at only one log. Running ./logs.sh without arguments displays logs from all eight containers merged chronologically.
Q. How do I perform a backup?
A. tar.gz backups are possible at the Docker volume level:
cd /opt/kopens/plantpulse-platform-docker/bin
./backup.sh # 기본 세트 (pp-data · pp-security)
./tools/backup-volume.sh pp-data 7 /data1/pp-backup/docker-volume # 볼륨 하나만
For the recommended backup cycle, please refer to Operation Management - Backup and Recovery.
Q. How do I update when a new version is released?
A. Run the installation one-liner again on the same server (without deleting or cleaning up). The new version's operation scripts, compose, and images will be installed, and the data will remain in the volumes.
sudo -i
curl -fsSL https://product.kopens.io/plantpulse-platform/install.sh | bash
./update.sh is not an official procedure — it only replaces images and does not recognize services created in the new version. For backup and verification methods, see Upgrade.
Q. How do I roll back if a problem occurs after an update?
A. The one-liner backs up the stack immediately before the upgrade; if the upgrade fails, it automatically reverts to the previous version (including data to the backup point — data entered while the new version was running will not be preserved). After fixing the cause, run the same one-liner again. If you need to revert after a successful upgrade, use bin/upgrade-rollback.sh <백업 위치> — Upgrade.
Q. Can I configure a cluster by adding worker nodes?
A. Yes. The authoritative list of workers is compose/workers.roster, and additions are handled by a dedicated script:
cd /opt/kopens/plantpulse-platform-docker/bin
bin/worker-add.sh # 빈 id·주소 자동 선택 (링 합류까지 확인합니다)
For more details, please refer to the Cluster Installation page.
Q. How do I increase container memory?
A. Modify DOCKER_PP_MEMORY in env.sh and then execute one of the following:
./restart.sh
Each container has a separate limit. The data lake uses DOCKER_DATALAKE_MEMORY (default 96G), and apps use service-specific variables like DOCKER_SERVER_MEMORY and DOCKER_BATCH_MEMORY → Environment Variable Reference
Check which container has reached its limit using docker stats --no-stream.
Data / Performance
Q. Where is the data stored?
A. Data is stored in Docker volumes on the host.
| Volume | Purpose |
|---|---|
pp-data | Main data (Aster TSDB, PostgreSQL, RustFS) |
pp-temp | Temporary processing files |
pp-backup | Internal backups |
pp-security | Certificates / Keys |
pp-template | Template data |
The actual host path is /data1/docker-data/volumes/ (can be changed to DOCKER_DATA_DIR in env.sh).
Q. Does the data remain if the container is removed?
A. Yes, ./remove.sh only removes the container while preserving the volumes. If you reinstall, you can use the previous data as is. To completely remove volumes, you must execute ./tools/remove-all-volumes.sh.
Q. Can I adjust the data retention period?
A. You can adjust the retention period of time series data via the Aster TSDB TTL setting. This can be changed in the console's system settings or properties. For more details, please refer to Performance Tuning and Properties Reference.
Q. The response has become slow. How do I diagnose it?
A. Please inspect in the following order:
# 1. 컨테이너 자원 사용량
docker stats --no-stream
# 2. 호스트 부하
top
df -h
# 3. critical 로그 확인
./ops-check.sh
# 4. Cassandra 컴팩션 / 디스크 I/O
./shell.sh
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node compactionstats
For detailed tuning, please refer to the Performance Tuning page.
Q. Aster TSDB disk usage is too high.
A. You can clean it up using the following command:
./shell.sh
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node cleanup # 불필요 데이터 정리
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd node compact # 수동 컴팩션
In the long term, please consider adjusting the retention period (TTL) or expanding the disk.
Security / User
Q. What is the default password, and where do I change it?
A. The default administrator account is admin / admin123!. Please change it immediately after logging in via the User icon in the top right > Change Password menu.
Service account passwords for databases, messaging, etc., are managed by variables in PP_*_PASSWORD of bin/env.sh and are stored in /etc/kopens/plantpulse-platform.env (mode 0600) during the first installation.
Path Verification — The authoritative copy of the secret sidecar is solely
/etc/kopens/plantpulse-platform.env(permissions0600). In old installations, a file with the same name may remain under/opt/kopens/, but it is not read; the installation script reverts it to the authoritative copy → Environment Variable Reference
Q. How is user and permission management handled?
A. Users, roles, and permissions can be managed in the Security Management menu of the console. For more details, please refer to the User Management and Security Settings pages.
Q. How do I change HTTPS certificates?
A. Certificates are stored in the pp-security volume. Regular replacement is recommended. For detailed procedures, please refer to the Security Settings page.
Q. Which ports should be exposed to the outside?
A. For users and external system access, it is recommended to expose only 80, 443, and 4950. If equipment connects directly, add 1883/1884 (MQTT) and 11004/11005 (OPC-UA). Restrict all other ports (DB, Kafka, Cluster, JMX) to be accessible only from the private network. For a detailed list, refer to Port Configuration Information.
Health and management consoles are available on both 4950 (HTTPS) and 4949 (plain text). Use 4950 on untrusted networks as 4949 is plain text.
Q. How is communication between nodes protected in a multi-node environment?
A. Internal cluster communication for JGroups, Aster TSDB, and Kafka is automatically restricted to be accessible only from RFC 1918 private networks (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) and Tailscale CGN ranges (100.64.0.0/10) via source limitation.
Multi-language / Timezone
Q. Can I operate with an English UI?
A. Yes. In env.sh:
export PP_LANG=en
export PP_TZ=America/New_York # 운영 지역 타임존
After modification, run ./restart.sh. However, since Aster TSDB time series data is loaded in KST epoch, you must maintain PP_TZ=Asia/Seoul when operating in Korea.
Q. Can PlantPulse switch between Korean and English UI per user?
A. No. The Platform uses a single locale per server instance model. This is fixed as an environment variable at JVM boot time, and per-user toggling is not supported. Please operate as Korean box = ko, Global box = en.
External System Integration
Q. How do I connect to an OPC-UA server?
A. Register the OPC-UA server information (URL, authentication, security policy) in the Connection Management menu of the console and map the tags to be collected. For detailed procedures, please refer to the Connection Management page.
Q. How do I send data from an MQTT device?
A. Connect to the MQTT broker (HiveMQ) via the host IP on port 1883 (PLAINTEXT) or 18884 (TLS). Authentication credentials are PP_MQ_USER / PP_MQ_PASSWORD in env.sh.
Q. How do I integrate with external systems via API?
A. All functions are also provided via REST API. Please refer to the Developer Guide - API User Manual.
Monitoring / Alarm
Q. How do I integrate the Platform status with an external monitoring system?
A. The monitoring system can poll the health endpoint and ops-check results:
# Healthcheck 엔드포인트 (모니터링용)
curl -kfsS https://[서버IP]:4950/api/health
# 운영 health + critical log (스크립트 호출)
ssh root@[서버IP] /opt/kopens/plantpulse-platform-docker/bin/ops-check.sh
For more details, please refer to the System Monitoring page.
Q. Can I receive alarms via email or SMS?
A. Email is supported through SMTP settings. For each alarm, enable Email Sending or SMS Sending in the External Forwarding Channel of the alarm settings (SMS requires a gateway to be configured). The record of who received the alarm is kept in the alarm recipient panel in Alarm Details. Messenger (e.g., Slack) integration can be configured via external webhooks or the Flow engine.
Support / Inquiries
Q. Where can I get help?
A. Please check the following materials first:
- Troubleshooting — Diagnosis and resolution procedures by symptom
- Operation Management — Daily operation commands
- System Monitoring — Status checks
- Diagnosis tarball: File generated after executing
./doctor.sh
If the issue is not resolved with the above materials, please inquire via webmaster@kopens.com along with the diagnosis tarball.
Q. What information should I send?
A. Please refer to the Troubleshooting - Information Required for Support Request section. The diagnosis tarball generated by ./doctor.sh contains most of the necessary information (sensitive information such as passwords is automatically masked).
Q. Where can I see the latest documentation?
A. You can always find the latest documentation at https://kopens.gitbook.io/plantpulse-platform/.