Skip to main content

FAQ

Frequently asked questions from PlantPulse Platform operators and their answers. For more detailed procedures, see Troubleshooting.

Installation / Licensing​

Q. Should I choose Docker installation or binary installation?​

A. Unless there is a specific reason, we recommend one-line installation (Docker-based). A single command automatically handles OS setup, firewall configuration, container startup, and makes updates and rollbacks simple. Binary installation is recommended only in environments where Docker cannot be used.

Q. Can I install in an air-gapped network?​

A. Yes. Generate a bundle using ./airgap-bundle.sh on an internet-connected node, transfer it to the air-gapped network via USB or internal file server, then run ./airgap-load.sh. For detailed procedures, see Docker Installation - Air-Gapped Installation.

Q. How do I obtain a license?​

A. Image registry credentials and licenses are issued by the KOPENS operations team. Please contact webmaster@kopens.com.

A. Single-node basis:

CategoryMinimumRecommended
CPU16 vCPU32 vCPU
Memory64GB200GB
Disk200GB1TB+ (depending on data volume)
OSOracle Linux 8 / RHEL 9 / Ubuntu 22.04 / Amazon Linux 2023Same

See System Requirements for detailed specifications.

Q. Which operating systems are supported?​

A. One-line installation is supported on the following operating systems:

  • Oracle Linux 8.x
  • RHEL / Rocky Linux 8.x, 9.x
  • Ubuntu 22.04+
  • Amazon Linux 2, 2023

On unvalidated operating systems, you can skip OS setup using the SKIP_OS=1 option and perform manual setup.

Q. Can I operate with Podman?​

A. Yes. Change DOCKER_CMD="docker" to DOCKER_CMD="podman" in bin/env.sh, and all scripts will work with Podman.

Installation / Startup​

Q. How long does installation take?​

A. Based on one-line installation, OS setup + Docker installation + image download + container startup takes approximately 10–20 minutes (depending on network speed). Subsequent container internal boot takes an additional 3–5 minutes (Cassandra schema migration + JVM warm-up).

Q. Where do I log in after installation?​

A. Open the following address in your browser:

http://[서버IP]:7500
  • [서버IP] is the DOCKER_PP_EXTERNAL_IP value from env.sh.
  • Default admin account: admin / admin123!
  • Change the password immediately after login.

Q. After startup, the health shows unhealthy.​

A. Startup takes 3–5 minutes. If it remains unhealthy after 5 minutes, see Troubleshooting - Container Startup Issues.

Q. I changed env.sh but it is not applied.​

A. env.sh changes are reflected only at boot time. You must restart using the following command for changes to apply:

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

Q. How do I make it start automatically after server reboot?​

A. The container runs with --restart unless-stopped policy, so it starts automatically when the Docker daemon starts. The Docker daemon itself is configured to start automatically at boot with systemctl enable docker.

Operations / Administration​

Q. How do I start / stop / restart the Platform?​

A. From /opt/kopens/plantpulse-platform-docker/bin/ on the host:

./up.sh              # 기동 — 준비될 때까지 대기 (종료 코드 0 = 쓸 수 있다)
./down.sh            # 중지 (데이터 보존)
./restart.sh         # 재시작 (graceful drain + 준비 대기)
./status.sh          # 상태 요약 (0 = 정상 / 2 = 비정상)

See Startup Guide for details.

Q. Can I restart only some components without restarting everything?​

A. Yes. However, the method differs depending on whether it is an app or infrastructure.

The six apps each run in their own container, so restarting that container restarts 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 inside the data lake container, so you enter it and use individual scripts.

./shell.sh
/opt/kopens/plantpulse-platform/plantpulse-datalake-cli/bin/pd restart storage
exit

See Startup Guide — Component-Level Restart for a detailed list.

Q. Where can I see logs?​

A. You can view container standard logs from the host and detailed module logs from inside the container.

# 전체 컨테이너 로그를 한 화면에 (서비스 이름 접두, 시간순)
./logs.sh

# 특정 컨테이너만
./logs.sh plantpulse-server-web -n 200

# 데이터레이크 안 컴포넌트 로그 파일
./logs.sh cassandra

# 볼 수 있는 대상 전체 목록
./logs.sh --list

# 모듈별 로그를 호스트로 한 번에 복사
./tools/copy-log-to-local.sh
When you don't know which container is the problem

With eight containers, looking at just one log can cause you to miss the issue. ./logs.sh without arguments shows all eight intermixed in time order.

Q. How do I back up?​

A. tar.gz backup is possible on a per-Docker-volume basis.

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   # 볼륨 하나만

See Operations Management - Backup and Recovery for recommended backup frequency.

Q. How do I update when a new version is released?​

A. Use the zero-downtime update command.

cd /opt/kopens/plantpulse-platform-docker/bin
./update.sh

Automatic execution: docker pull → graceful shutdown → recreate with new image → health validation → automatic rollback on failure. Data is stored separately in volumes, so it is safe.

Q. How do I roll back if there is a problem after updating?​

A. ./update.sh automatically rolls back on health validation failure. If issues persist after automatic rollback or manual rollback is needed, change PP_IMAGE_TAG in env.sh to a previous stable version and run ./update.sh again.

Q. Can I add worker nodes to form a cluster?​

A. Yes. The authoritative source for the worker list is compose/workers.roster, and addition uses a dedicated script.

cd /opt/kopens/plantpulse-platform-docker/bin
bin/worker-add.sh          # 빈 id·주소 자동 선택 (링 합류까지 확인합니다)

See Cluster Installation for details.

Q. How do I increase container memory?​

A. Modify DOCKER_PP_MEMORY in env.sh and run one of the following:

./restart.sh
First decide which container's memory to increase

Each container has a separate limit. Data lake is DOCKER_DATALAKE_MEMORY (default 80G), and apps have service-specific variables like DOCKER_SERVER_MEMORY · DOCKER_BATCH_MEMORY → Environment Variable Reference

Check which container has reached its limit with docker stats --no-stream.

Data / Performance​

Q. Where is data stored?​

A. Data is stored in Docker volumes on the host.

VolumePurpose
pp-dataMain data (Cassandra, PostgreSQL, MinIO)
pp-tempTemporary processing files
pp-backupSelf-backup
pp-securityCertificates / keys
pp-templateTemplate data

The actual host path is /data1/docker-data/volumes/ (can be changed with env.sh to DOCKER_DATA_DIR).

Q. Does data remain if I remove the container?​

A. Yes, ./remove.sh removes only the container and preserves volumes. When you reinstall, you can use the previous data as-is. To completely remove volumes, run ./tools/remove-all-volumes.sh.

Q. Can I adjust the data retention period?​

A. You can adjust the retention period for time series data using Cassandra TTL settings. You can change this in the console system settings or properties. See Performance Tuning and Properties Reference for details.

Q. Response has become slow. How do I diagnose this?​

A. Check 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

See Performance Tuning for detailed tuning.

Q. Cassandra disk usage is too large.​

A. You can clean it up with 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      # 수동 컴팩션

Long-term, consider adjusting retention period (TTL) or expanding disk space.

Security / Users​

Q. What is the default password and where do I change it?​

A. The default admin account is admin / admin123!. Change it immediately after login from the user icon in the upper right > Change password menu.

Service account passwords for database, messaging, and other services are managed by PP_*_PASSWORD variables in bin/env.sh and stored in /etc/kopens/plantpulse-platform.env on first installation (mode 0600).

Path verification — The authoritative source for the secrets sidecar is only /etc/kopens/plantpulse-platform.env (permission 0600). Old installations may have the same name remaining under /opt/kopens/, but it is not read, and the installation script restores it to the authoritative copy → Environment Variable Reference

Q. How do I manage users and permissions?​

A. Users, roles, and permissions can be managed from the Security Management menu in the console. See User Management and Security Settings for details.

Q. How do I change the HTTPS certificate?​

A. Certificates are stored in the pp-security volume. Regular replacement is recommended. See Security Settings for detailed procedures.

Q. Which ports need to be exposed externally?​

A. For user and external system access, we recommend exposing only 80, 443, 7443, 4950. If equipment connects directly, add 1883/1884 (MQTT) and 11004/11005 (OPC-UA). Restrict access to remaining ports (DB, Kafka, cluster, JMX) to private networks only. See Port Configuration Information for a detailed list.

Health and management consoles are available on both 4950 (HTTPS) and 4949 (plaintext). Use 4950 for untrusted networks since 4949 is plaintext.

Q. How is inter-node communication protected in multi-node environments?​

A. Source restrictions are automatically applied to cluster internal communication (JGroups, Cassandra, Kafka, etc.) to allow access only from RFC 1918 private networks (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) and Tailscale CGN range (100.64.0.0/10).

Internationalization / 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, ./restart.sh. However, since Cassandra time series data is ingested with KST epoch, you must maintain PP_TZ=Asia/Seoul for Korean operations.

Q. Can PlantPulse switch between Korean and English UI per user?​

A. No. The Platform uses a single locale per server instance model. It is fixed by environment variables at JVM boot time, and per-user toggle is not supported. Operate Korean boxes with ko and global boxes with en.

External System Integration​

Q. How do I connect to an OPC-UA server?​

A. Register OPC-UA server information (URL, authentication, security policy) in the Connection Management menu in the console and map the tags to collect. See Connection Management for detailed procedures.

Q. How do I send data from MQTT devices?​

A. Connect to the MQTT broker (HiveMQ) on port 1883 (PLAINTEXT) or 18884 (TLS) at the host IP. Authentication information is PP_MQ_USER / PP_MQ_PASSWORD in env.sh.

Q. How do I integrate with external systems via API?​

A. All features are also available via REST API. See Developer Guide - API Usage Manual.

Monitoring / Alarms​

Q. How do I integrate Platform status with an external monitoring system?​

A. Health endpoints and ops-check results can be polled by monitoring systems.

# Healthcheck 엔드포인트 (모니터링용)
curl -kfsS https://[서버IP]:4950/api/health

# 운영 health + critical log (스크립트 호출)
ssh root@[서버IP] /opt/kopens/plantpulse-platform-docker/bin/ops-check.sh

See System Monitoring for details.

Q. Can I receive alarms via email or SMS?​

A. Email is supported via SMTP settings. You can configure this in the console under Alarms > Notification Settings. SMS and messenger (Slack, etc.) integration can be configured via external webhook or Flow engine.

Support / Contact​

Q. Where can I get help?​

A. Check the following resources first:

If the above resources do not resolve the issue, contact webmaster@kopens.com with the diagnostic tarball.

Q. What information should I send along?​

A. See Troubleshooting - Information Required for Support Requests. The diagnostic tarball generated by ./doctor.sh contains most of the necessary information (sensitive information like passwords is automatically masked).

Q. Where can I find the latest documentation?​

A. You can always check the latest documentation at https://kopens.gitbook.io/plantpulse-platform/.