Installation Troubleshooting

This section lists the most frequently encountered symptoms during or immediately after installation (Single Line Installation / Factory Line Installation / Air-Gapped Network Installation), ordered by frequency. Container mode is the standard installation method. For errors occurring during operation after installation, refer to Container Mode Operation or Diagnosis and Inspection.

Quick Verification After Installation in Container Mode 2026.05+

sudo bash /opt/kopens/install/bin/status.sh   # 한 줄 상태
sudo bash /opt/kopens/install/bin/health.sh   # exit 0/1
curl -ks https://127.0.0.1/api/v1/system/version | python3 -m json.tool   # image_tag / build_date / container_mode
curl -ks https://127.0.0.1/api/v1/system/health  | python3 -m json.tool   # components UP

If install.sh fails, check /var/log/kopens-install.log. If a container is unhealthy, use journalctl -u plantpulse-edge.service -n 100 or docker logs plantpulse-edge. Details: Container Mode Operation.

Preserve Evidence Before Troubleshooting

Before performing reinstallation, clean, or restore on a box intended for deployment, first capture doctor.sh and the acceptance log whenever possible. Do not share passwords in plain text.

sudo bash /opt/kopens/install/bin/doctor.sh || true
sudo journalctl -u plantpulse-edge.service -n 200 --no-pager \
  > /root/pp-edge-journal-$(date +%Y%m%d-%H%M%S).txt

1. Download / Installation Phase

1.1 `curl: (6) Could not resolve host: product.kopens.io`

Cause: DNS resolution failure.

Resolution:

nslookup product.kopens.io
# Server: ... (사내 DNS) — 응답이 없으면 DNS 가 안 풀림

# /etc/resolv.conf 확인
cat /etc/resolv.conf
# nameserver 8.8.8.8 또는 사내 DNS 가 있어야 함

# 임시로 공인 DNS 추가
echo "nameserver 8.8.8.8" | sudo tee -a /etc/resolv.conf

In an environment with DNS blocking on the corporate network, add IPs directly to /etc/hosts:

# product.kopens.io 의 실제 IP 를 운영팀에 문의 후 등록
echo "X.X.X.X product.kopens.io" | sudo tee -a /etc/hosts

For field sites with only product.kopens.io open, also check .com in the same manner.

1.2 `curl: (7) Failed to connect to product.kopens.io port 443`

Cause: Corporate firewall blocks outbound 443 or a proxy is required.

Resolution:

# 프록시 환경이면 export HTTP_PROXY / HTTPS_PROXY
export HTTPS_PROXY=http://proxy.company.local:8080
export HTTP_PROXY=http://proxy.company.local:8080

# 그 후 install.sh 다시 실행
bash < <(curl -fsSL https://product.kopens.io/plantpulse-edge/install.sh)

If a proxy is not possible, use the Air-Gapped Network Installation procedure to transport via USB.

1.3 `tar: KOPENS_EDGE_*.tar.zstd: Cannot open: No such file or directory`

Cause: Interruption during download — insufficient disk space or a broken connection.

Resolution:

# 디스크 공간
df -h /opt /tmp

# 다시 다운로드 (`-C` 로 이어받기)
curl -O -C - https://product.kopens.io/plantpulse-edge/KOPENS_EDGE_V2026.tar.zstd

# 무결성 확인 (있으면 sha256)
sha256sum KOPENS_EDGE_V2026.tar.zstd

1.4 `bash: java: command not found`

Cause: Java not installed. For 2026.05+ container installation, the packages requiring install.sh are usually installed automatically, but if the package installation step fails due to corporate security policies or repository blocking, a manual installation may be necessary.

Resolution:

# Fedora / RHEL
sudo dnf install -y java-17-amazon-corretto-devel

# Ubuntu / Debian
sudo apt-get install -y temurin-17-jdk

# 확인
java -version
# openjdk version "17.x" ...

For a new container installation, rather than manually configuring Java, first resolve the cause of the package installation failure in install.sh.

1.5 `docker: command not found`

Cause: Docker not installed or failure of the Docker installation step in install.sh.

Resolution:

# Fedora
sudo dnf -y install docker-ce docker-ce-cli containerd.io
sudo systemctl enable --now docker

# Ubuntu
curl -fsSL https://get.docker.com | sudo sh
sudo systemctl enable --now docker

# 확인
docker --version

2. Boot / Startup Phase

2.0 Health Status 503 in Container Mode

Cause: One of the components is DOWN. First, check the component name in the health JSON.

Resolution:

curl -ks https://127.0.0.1/api/v1/system/health | python3 -m json.tool
sudo bash /opt/kopens/install/bin/status.sh
sudo bash /opt/kopens/install/bin/logs.sh tomcat | tail -100
sudo bash /opt/kopens/install/bin/logs.sh cassandra | tail -100
sudo bash /opt/kopens/install/bin/logs.sh mqtt | tail -100
sudo bash /opt/kopens/install/bin/logs.sh node-red | tail -100

Check the logs for each component to identify the cause, then take action. If recovery is not achieved within 30 minutes, execute backup.sh and doctor.sh according to the escalation procedure in Container Mode Operation.

2.1 Stuck at `[4] DB START` Phase (60+ Seconds)

Cause: Cassandra is committing log recovery. This is normal during the first boot or after an abnormal shutdown — it just takes more time.

Resolution:

# 별도 ssh 세션에서 실시간 로그
tail -f /opt/kopens/plantpulse-edge/db/logs/system.log

# `Listening for thrift clients` 또는 `Startup complete` 가 보이면 OK
# 그 후 메인 화면의 [4] 단계가 자동 진행됨

If no message appears after 10 minutes — heap / disk / sstable corruption. Retry after bin/node-cleanup.sh.

2.2 Server Doesn't Start After `[7] SERVER START` — `Connection refused`

Cause A: Tomcat is not listening for 1–2 seconds immediately after startup — normal.

Cause B: Ports 80 / 443 are bound by another process.

Resolution:

# 포트 점유 확인
sudo ss -lntp | grep -E ':80 |:443 '

# 점유 중이면 그 프로세스 정리 (예: nginx)
sudo systemctl stop nginx

# tomcat 재시작
sudo /opt/kopens/plantpulse-edge/bin/restart.sh

Cause C: startup error in catalina.out.

sudo tail -100 /opt/kopens/plantpulse-edge/server/logs/catalina.out | grep -E 'SEVERE|ERROR|Exception'

Take action based on messages such as Address already in use, Cannot find class, Failed to load app.properties.

2.3 Node-RED Fails to Boot

Cause A: Port 1880 is in use. Cause B: Permission issue with userDir (/opt/kopens/.../node/userDir). Cause C: flows.json is corrupted.

Resolution:

# 1880 포트 점유?
sudo ss -lntp | grep 1880

# userDir 권한
ls -la /opt/kopens/plantpulse-edge/node/userDir/

# Node-RED 로그 (container)
sudo bash /opt/kopens/install/bin/logs.sh node-red | tail -50

# 플로우 도구 로그
tail -50 /opt/kopens/plantpulse-edge/node/log/node-red.log

# flows.json 손상 시 백업본으로 복원
cd /opt/kopens/plantpulse-edge/node/userDir
cp .flows.json.backup flows.json

# 재시작
/opt/kopens/plantpulse-edge/node/bin/stop.sh
/opt/kopens/plantpulse-edge/node/bin/start.sh

2.4 `INSTALL COMPLETED` Appears But Web Interface Doesn't Open (External Access)

Cause: Firewall blocks 80/443 for external access.

Resolution:

# 게이트웨이 자체에서는 되는지
curl -kI https://127.0.0.1/api/v1/system/health
# HTTP/1.1 200 이면 게이트웨이 정상, 외부 접근만 차단됨

# firewalld 확인
sudo firewall-cmd --list-all
# 80/tcp, 443/tcp 가 ports 에 없으면 추가

sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --reload

For iptables environments:

sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT

3. Network / Time Synchronization

3.1 SSH Connection Lost After Setting Static IP During Installation

Cause: The IP, gateway, or subnet for NET1_IP / NET2_IP provided in install.sh are incorrect. (If you used the old scripts set-1.sh / set-2.sh, they are no longer available — installation now sets these directly via nmcli.)

Resolution (via console — KVM / IPMI / VM console):

# 현재 NIC 상태
nmcli dev show
ip a

# IP 수정 (예: enp1s0 의 IP 변경)
sudo nmcli con modify enp1s0 ipv4.address 192.168.0.50/24 ipv4.gateway 192.168.0.1
sudo nmcli con up enp1s0

# 재부팅 권장
sudo reboot

3.2 Time Shows 1970 / NTP Synchronization Fails

Cause: chrony service disabled or NTP unreachable.

Resolution:

# chrony 상태
sudo systemctl status chronyd
# Active: inactive (dead) 면 시작
sudo systemctl enable --now chronyd

# 동기 강제
sudo chronyc makestep
sudo chronyc tracking
# Reference ID 가 채워지면 OK

# 사내 NTP 서버 사용 시 /etc/chrony.conf 의 server 라인 수정
# server <internal-ntp-ip> iburst

3.3 Internet Appears to Leak Through the PLC Network (NIC 2)

Cause: Both NICs have a default route.

Resolution:

# default route 확인
ip route | grep default

# 두 NIC 가 default 면 NIC 2 (PLC 망) 의 never-default 설정
sudo nmcli con modify enp2s0 ipv4.never-default yes
sudo nmcli con up enp2s0

4. Permissions / SELinux

4.1 `Permission denied` (binding port 80)

Cause: Running as a non-root user.

Resolution: Run all commands as sudo -i after. If registered as a systemd service, it runs as root automatically.

4.2 `avc: denied` Message (SELinux)

Cause: SELinux is in enforcing mode — certain paths are denied.

Resolution:

# 임시로 SELinux 끄기 (테스트용)
sudo setenforce 0

# 영구 (운영 환경에서 비추천)
sudo sed -i 's/^SELINUX=enforcing/SELINUX=permissive/' /etc/selinux/config

# 정식: 거부된 path 에 컨텍스트 부여 (운영팀과 함께)
sudo semanage fcontext -a -t bin_t '/opt/kopens/.*\.sh'
sudo restorecon -Rv /opt/kopens

5. Disk

5.1 `/data1` Directory Doesn't Exist

Cause: Separate disk not mounted.

Resolution:

# 현재 마운트
df -h

# /data1 이 없으면 디스크 인식 → mkfs → mount
lsblk
# /dev/sdb 같은 디스크 확인 후
sudo mkfs.xfs /dev/sdb
sudo mkdir -p /data1
sudo mount /dev/sdb /data1
echo '/dev/sdb  /data1  xfs  defaults,noatime  0 2' | sudo tee -a /etc/fstab

5.2 `/opt` Disk Full — Extraction of Output Fails

Resolution: Refer to Cleanup and Purge — run clean.sh + node-cleanup.sh + delete old backups.

6. First Run — Data / Registration

6.1 Platform API Server Card 🔴 Connection Failed

Cause: server.host / port / username in app.properties are incorrect, or the platform is not running, or the corporate firewall blocks outbound connections.

Resolution:

# 외부에서 플랫폼 도달 가능?
curl -I https://<server.host>:<server.port>/

# 사내 방화벽 outbound 정책 — 운영팀에 문의 (HTTPS / 80 / 443)

# app.properties 수정 → 저장 → restart.sh

6.2 Edge ID is Empty or Different from Intended

Cause: edge.id not set in app.properties.

Resolution: Go to Web UI System Configuration → edge.id=EDGE_<number> → Save → restart.sh.

6.3 After PLC Registration, Collection Status Stuck at Unknown

Cause A: Registered with auto_collect=false — manual start required. Cause B: PLC network NIC is down or PLC IP is unreachable.

Resolution:

# PLC IP ping
ping -c 3 192.168.100.20

# PLC 포트 도달 (Modbus 502 예시)
nc -vz 192.168.100.20 502

# 도달 OK 면 화면에서 ▶ 시작 누르기

7. Other

7.1 systemd `plantpulse-edge.service` Not Activated

This is the standard service for container mode.

Resolution:

sudo systemctl daemon-reload
sudo systemctl enable --now plantpulse-edge.service
sudo systemctl status plantpulse-edge.service --no-pager
sudo journalctl -u plantpulse-edge.service -n 100 --no-pager

If it's Unit not found, then /opt/kopens/install/install.sh failed before systemd unit deployment. Check /var/log/kopens-install.log, then re-run bash /opt/kopens/install/install.sh.

7.3 Automatic Start Not Working After Reboot

sudo systemctl is-enabled plantpulse-edge.service
# enabled 가 아니면
sudo systemctl enable plantpulse-edge.service

7.4 firefox / GUI Tools Not Installed (Server Mode)

Cause: No GUI packages on the headless server.

Resolution: Ignore — it does not affect gateway operation. Remove firefox from setup.sh or skip it in dnf install.

8. Log Locations — Where to Look

Component	Log Location
Tomcat (Web / REST API)	`/opt/kopens/plantpulse-edge/server/logs/catalina.out`
Cassandra	`/opt/kopens/plantpulse-edge/db/logs/system.log`
HiveMQ (MQTT)	`/opt/kopens/plantpulse-edge/mqtt/log/hivemq.log`
Node-RED	`/opt/kopens/plantpulse-edge/node/log/node-red.log`
timeseries-engine	`/opt/kopens/plantpulse-edge/timeseries/engine/log/*.log`
systemd (container)	`journalctl -u plantpulse-edge.service -n 200`
Aggregated tail	`/opt/kopens/plantpulse-edge/bin/log-viewer.sh`

9. If It Still Doesn't Work

For container mode, capture the output of status.sh, health.sh, journalctl -u plantpulse-edge.service -n 200
Send the results of df -h, free -h, systemctl status ... and the above log excerpts to the operations team
Re-run install.sh from Single Line Installation — it is idempotent, so running it multiple times is safe.

10. Learn More

Standard procedure: Single Line Installation
Air-gapped networks: Air-Gapped Network Installation
Post-installation checklist: Post-Installation Inspection
Diagnostics during operation: Diagnosis and Inspection

1. Download / Installation Phase​

1.1 curl: (6) Could not resolve host: product.kopens.io​

1.2 curl: (7) Failed to connect to product.kopens.io port 443​

1.3 tar: KOPENS_EDGE_*.tar.zstd: Cannot open: No such file or directory​

1.4 bash: java: command not found​

1.5 docker: command not found​

2. Boot / Startup Phase​

2.0 Health Status 503 in Container Mode​

2.1 Stuck at [4] DB START Phase (60+ Seconds)​

2.2 Server Doesn't Start After [7] SERVER START — Connection refused​

2.3 Node-RED Fails to Boot​

2.4 INSTALL COMPLETED Appears But Web Interface Doesn't Open (External Access)​

3. Network / Time Synchronization​

3.1 SSH Connection Lost After Setting Static IP During Installation​

3.2 Time Shows 1970 / NTP Synchronization Fails​

3.3 Internet Appears to Leak Through the PLC Network (NIC 2)​

4. Permissions / SELinux​

4.1 Permission denied (binding port 80)​

4.2 avc: denied Message (SELinux)​

5. Disk​

5.1 /data1 Directory Doesn't Exist​

5.2 /opt Disk Full — Extraction of Output Fails​

6. First Run — Data / Registration​

6.1 Platform API Server Card 🔴 Connection Failed​

6.2 Edge ID is Empty or Different from Intended​

6.3 After PLC Registration, Collection Status Stuck at Unknown​

7. Other​

7.1 systemd plantpulse-edge.service Not Activated​

7.3 Automatic Start Not Working After Reboot​

7.4 firefox / GUI Tools Not Installed (Server Mode)​

8. Log Locations — Where to Look​

9. If It Still Doesn't Work​

10. Learn More​

1. Download / Installation Phase

1.1 `curl: (6) Could not resolve host: product.kopens.io`

1.2 `curl: (7) Failed to connect to product.kopens.io port 443`

1.3 `tar: KOPENS_EDGE_*.tar.zstd: Cannot open: No such file or directory`

1.4 `bash: java: command not found`

1.5 `docker: command not found`

2. Boot / Startup Phase

2.0 Health Status 503 in Container Mode

2.1 Stuck at `[4] DB START` Phase (60+ Seconds)

2.2 Server Doesn't Start After `[7] SERVER START` — `Connection refused`

2.3 Node-RED Fails to Boot

2.4 `INSTALL COMPLETED` Appears But Web Interface Doesn't Open (External Access)

3. Network / Time Synchronization

3.1 SSH Connection Lost After Setting Static IP During Installation

3.2 Time Shows 1970 / NTP Synchronization Fails

3.3 Internet Appears to Leak Through the PLC Network (NIC 2)

4. Permissions / SELinux

4.1 `Permission denied` (binding port 80)

4.2 `avc: denied` Message (SELinux)

5. Disk

5.1 `/data1` Directory Doesn't Exist

5.2 `/opt` Disk Full — Extraction of Output Fails

6. First Run — Data / Registration

6.1 Platform API Server Card 🔴 Connection Failed

6.2 Edge ID is Empty or Different from Intended

6.3 After PLC Registration, Collection Status Stuck at Unknown

7. Other

7.1 systemd `plantpulse-edge.service` Not Activated

7.3 Automatic Start Not Working After Reboot

7.4 firefox / GUI Tools Not Installed (Server Mode)

8. Log Locations — Where to Look

9. If It Still Doesn't Work

10. Learn More