(legacy) Full H/W Installation — native tools/setup.sh
This page is a legacy procedure kept as a reference for maintaining native deployment boxes older than 2026.05.
For new H/W, production shipments, and new field installations, use Quick Install (install.sh).
tools/setup.sh assumes a native plantpulse.service and a direct-on-host execution structure.
The 2026.05+ container standard has a single plantpulse-edge.service managing the runtime.
Mixing the two modes on the same box causes port and data path conflicts.
Use it only when you must reinstall or recover an older box already running in native mode, or when you need to cross-check legacy field handover documents. For a new box, go back to Installation — At a Glance.
1. Prerequisites (legacy native)
| Item | Value |
|---|---|
| OS | Fedora 38 (the validation baseline at the time — other RHEL-family distributions may work, but require separate validation) |
| Privileges | root (sudo -i or direct root login) |
| Network | Internet connection (dnf packages + legacy native bundle download) |
| Disk | ~3GB on /opt, 100GB+ for data on /data1 (separate partition recommended) |
| Memory | 8GB minimum (Cassandra 4GB heap + Tomcat 4GB) |
| NIC count | 2 (NIC 1 = WAN/external, NIC 2 = PLC/internal) — industrial appliance standard |
| Time | Internet NTP reachable (chrony installed) |
1.1 Recommended H/W Specifications
| Class | CPU | RAM | SSD | NIC | Price class |
|---|---|---|---|---|---|
| Small (≤ 1k tags) | 4 cores / 2.0GHz+ | 8GB | 256GB | 2x 1Gbps | Industrial mini PC |
| Medium (1k–10k tags) | 8 cores / 2.5GHz+ | 16GB | 512GB SSD + 1TB HDD | 2x 1Gbps | Industrial appliance |
| Large (10k+ tags) | 16 cores / 3.0GHz+ | 32GB+ | 1TB NVMe | 2x 10Gbps | 1U server |
2. Location
/opt/kopens/tools/setup.sh ← 메인 setup 스크립트
/opt/kopens/tools/net/ ← 네트워크 set-1.sh / set-2.sh / status.sh / ping.sh
/opt/kopens/tools/firewall/open.sh ← firewalld 포트 오픈
/opt/kopens/tools/file/run.sh ← TCP / file limit / sysctl 튜닝
/opt/kopens/tools/file/sysctl.conf ← 커널 튜닝
/opt/kopens/tools/file/limits.conf ← 프로세스 리소스 한도
/opt/kopens/tools/file/chrony.conf ← NTP
/opt/kopens/tools/docker/setup.sh ← Docker CE 설치
/opt/kopens/tools/java/setup.sh ← Amazon Corretto 17
/opt/kopens/tools/python/setup.sh ← Python 3 + pip
/opt/kopens/tools/nodejs/setup.sh ← Node.js + npm
/opt/kopens/tools/ssl/gen.sh ← 자체 서명 인증서 발급 (CA + 서버)
/opt/kopens/tools/vpn/setup.sh ← VPN 클라이언트
/opt/kopens/tools/service/plantpulse.service ← systemd unit
/opt/kopens/tools/service/service-start.sh ← systemd ExecStart → bin/start.sh
/opt/kopens/tools/service/service-stop.sh ← systemd ExecStop → bin/stop.sh
3. Execution — legacy native one-liner
# 1) root 권한
sudo -i
# 2) 작업 디렉토리
cd /opt/kopens/tools
# 3) 실행 (대화형 — 호스트명 + 네트워크 설정을 묻습니다)
./setup.sh
Total time: 15–30 minutes (depending on internet speed + dnf package downloads + tuned boot).
When it finishes, the box reboots automatically after 10 seconds — the legacy plantpulse.service starts automatically after reboot.
4. Step-by-Step Input Guide (interactive prompts)
The following inputs are requested in order during installation.
4.1 Hostname
[?] INPUT THIS EDGE GATEAY HOSTNAME :
=> EDGE_00303
Used to identify the gateway. Enter EDGE_<4-digits> or follow your site convention. Example: EDGE_00303.
4.2 NIC 1 (WAN / external network) — enp1s0
[?] ETHERNET [enp1s0] MODE [DHCP|STATIC] :
| Mode | Input | Then |
|---|---|---|
DHCP | IP obtained automatically | No further input |
STATIC | Use static IP | Additional input for IP/mask, gateway, DNS |
Additional prompts when STATIC:
[?] ETHERNET [enp1s0] IP/SUBNETMASK : 192.168.0.50/24
[?] ETHERNET [enp1s0] GATEWAY : 192.168.0.1
[?] ETHERNET [enp1s0] DNS : 8.8.8.8
This NIC is used to reach the default gateway (external internet / cloud / Platform API). DNS is either your corporate DNS or a public DNS.
4.3 NIC 2 (PLC / internal network) — enp2s0
The same sequence once more. Since this is dedicated to the PLC network, STATIC is normally used for clean separation:
[?] ETHERNET [enp2s0] MODE [DHCP|STATIC] : STATIC
[?] ETHERNET [enp2s0] IP/SUBNETMASK : 192.168.100.10/24
[?] ETHERNET [enp2s0] GATEWAY : 192.168.100.1
[?] ETHERNET [enp2s0] DNS : 192.168.100.1
This NIC is not used as the default gateway (
ipv4.never-default yes) — it is dedicated to private-network communication with the PLCs, separated from WAN routing.
4.4 Network Verification + Time Synchronization
setup.sh automatically runs nmcli con up, then verifies external reachability with ping and synchronizes NTP with chronyc makestep. The output is normal if you see OK or an IP / RTT.
5. All 22 setup.sh Steps — In Detail
| # | Step | Action | Expected output |
|---|---|---|---|
| 1 | Register KOPENS_HOME environment variables | Appended to /etc/bashrc | (silent) |
| 2 | Set hostname | hostnamectl set-hostname | (silent) |
| 3 | Create ${PE_HOME}/conf/env.sh | PE_HOME / PE_DATA_DIR / JAVA_HOME / CLEAN_ON_STARTUP | env.sh output |
| 4 | Create ${PE_DATA_DIR} (/data1) directories | mkdir -p | /data1 |
| 5 | Network configuration | net/set-1.sh (NIC 1, WAN), net/set-2.sh (NIC 2, PLC), NetworkManager restart | nmcli output |
| 6 | Verify net/status.sh + net/ping.sh | Interface status + external ping | RTT output |
| 7 | Locale / timezone | ko_KR.utf8 + Asia/Seoul | date |
| 8 | OS update | dnf -y update | dnf progress display |
| 9 | Install required packages | tar / htop / fping / pv / firefox / java-17-openjdk-devel / jna / jemalloc / zstd / curl-devel / chrony / tuned / net-tools / numactl / nodejs / npm / python3 / fail2ban / gcc / glibc-devel / NetworkManager-tui | dnf progress |
| 10 | Tuning | tuned-adm profile throughput-performance + disable GNOME power saving | Active profile: throughput-performance |
| 11 | Firewall | tools/firewall/open.sh (see table 5.1 below) | firewall-cmd --list-all |
| 12 | NTP (chrony) | Apply chrony.conf + enable service + sync via hwclock -w | chronyc ntpdata |
| 13 | TCP / file limit / sysctl | tools/file/run.sh (see table 5.2 below) | (silent) |
| 14 | CPU governor | All CPUs to performance mode | (silent) |
| 15 | NUMA + Hugepages | vm.zone_reclaim_mode=0 + disable transparent hugepages + reserve 9216 hugepages | numactl --show |
| 16 | Docker | tools/docker/setup.sh (Docker CE) | docker version |
| 17 | Java 17 | Amazon Corretto | java -version |
| 18 | Python 3 / NodeJS | dnf install | python3 --version |
| 19 | Issue SSL certificate | tools/ssl/gen.sh — self-signed CA + server cert (/var/security/plantpulse/) | openssl output |
| 20 | VPN | tools/vpn/setup.sh | VPN client installed |
| 21 | dnf clean all | Cache cleanup | (silent) |
| 22 | Register systemd | Copy /etc/systemd/system/plantpulse.service + systemctl enable plantpulse | service registered |
| 23 | Automatic reboot | After a 10-second countdown | *** NOW REBOOT AFTER 10 SEC! *** |
set -e is enabled, so the script aborts immediately if any step fails.
5.1 Firewall — Ports Opened Automatically
tools/firewall/open.sh permanently adds the following TCP ports to the public zone:
| Port | Purpose |
|---|---|
| 22 (TCP/UDP) | SSH |
| 80, 443 (TCP) | Web UI (/ui/main) |
| 123 (TCP/UDP) | NTP |
| 1880 (TCP) | Node-RED (backend of /ui/flow) |
| 3000 (TCP) | Grafana (time series dashboards) |
| 4000 (TCP) | APM / monitoring |
| 7000, 7001, 9042 (TCP) | Cassandra (gossip / SSL gossip / client) |
| 7799 (TCP) | JMX (Tomcat monitor) |
| 7800, 7801 (TCP) | timeseries-engine |
| 9090 (TCP) | Cockpit (server management) |
| 12000, 12443 (TCP) | OPC-UA (TCP / TLS) |
| 19999 (TCP) | NetData |
In addition, --add-masquerade is enabled so Docker containers are NATed onto the host network.
5.2 sysctl Tuning (part of /etc/sysctl.conf)
net.ipv4.tcp_keepalive_time = 60 # PLC TCP keepalive 빠르게
net.ipv4.tcp_keepalive_probes = 3
net.ipv4.tcp_keepalive_intvl = 10
net.core.rmem_max = 16777216 # 16MB 수신 버퍼
net.core.wmem_max = 16777216 # 16MB 송신 버퍼
net.core.somaxconn = 1024
net.ipv4.tcp_rmem = 4096 87380 16777216
net.ipv4.tcp_wmem = 4096 65536 16777216
vm.max_map_count = 1048575 # Cassandra mmap
vm.overcommit_memory = 1 # Cassandra hint
vm.swappiness = 1 # 최소 스왑
6. After Reboot — Verify Native Operation (1 minute)
# 1) systemd 서비스 살아있는지
systemctl status plantpulse
# 예: active (running) since ...
# 2) 모든 컴포넌트 프로세스
/opt/kopens/plantpulse-edge/bin/ps.sh
# 3) 시스템 헬스 (200 OK 면 게이트웨이 정상)
curl -s http://127.0.0.1/api/v1/system/health | jq
# 4) OPC-UA 트리 (등록된 OPC 가 0 이어도 OK — 빈 배열)
curl -s http://127.0.0.1/ui/opcua/tree | jq '.data.tree | length'
# 5) 웹 UI
# 브라우저 → https://<gateway>/ui/main
# 좌상단 로고 + 30개 카드가 보이면 정상
7. Integrated systemd Operation (legacy native)
After installation, systemd manages the gateway automatically:
sudo systemctl start plantpulse # 시작 (start.sh 호출)
sudo systemctl stop plantpulse # 정지 (stop.sh 호출)
sudo systemctl status plantpulse # 상태
sudo systemctl restart plantpulse # 풀스택 재시작 (60초+ 다운타임)
sudo journalctl -u plantpulse -n 100 # systemd 로그 마지막 100줄
Restarting Tomcat only (to apply code /
app.propertieschanges) isbin/restart.sh(~6 seconds). systemdrestartis a full-stack restart (stop.sh→start.sh).
Internal wiring:
plantpulse.service→ExecStart=service-start.sh→bin/start.shplantpulse.service→ExecStop=service-stop.sh→bin/stop.sh
8. Common Pitfalls
| Step | Symptom | Cause / Resolution |
|---|---|---|
| 5 (network) | SSH drops after set-1.sh | Network interface / gateway misconfigured. Access via console (KVM/IPMI) and recover nmcli con modify enp1s0 ipv4.address ... manually |
| 5 (network) | NIC name is not enp1s0 (e.g. eth0, eno1) | Check the NIC names on the OS (nmcli dev). Edit the IF=enp1s0 lines in tools/net/set-1.sh to the actual names, then rerun setup.sh |
| 8 (dnf) | dnf update hangs | Check the line / corporate dnf mirror. On a corporate network, add the internal mirror to /etc/yum.repos.d/ |
| 9 (packages) | Some packages missing (e.g. firefox not available) | Minimal installation ISO. The gateway itself works fine without those packages — ignore and continue |
| 10 (tuned) | tuned-adm not found | dnf install tuned missing. Install it manually, then resume setup.sh from step 11 |
| 11 (firewall) | firewall-cmd --reload fails | firewalld not running. Run systemctl start firewalld manually. Also check whether SELinux is enforcing |
| 15 (hugepages) | Hugepages are released after boot | Add vm.nr_hugepages = 9216 permanently to /etc/sysctl.d/99-plantpulse.conf |
| 22 (systemd) | Gateway does not come up after reboot | Check the unit failure cause with journalctl -u plantpulse --no-pager. Run bin/start.sh directly to find where it stalls |
set -e | Aborts midway | Check the preceding step named in the message body. Run only that step manually, then resume setup.sh from the next step |
| General | Script execution permission | chmod +x /opt/kopens/tools/setup.sh (rarely needed) |
9. Recommended First Tasks After Installation
- Log in to the web UI and change the password —
/ui/main→ user menu at top right → change password - Verify site / edge ID —
site.id,edge.idin System Configuration - Set up Sparkplug B integration — Sparkplug B (if needed)
- Add the first PLC connection — Adding a New PLC Connection
- Register a scheduled backup cron — Backup (
backup.sh)
10. Learn More
- Quick / one-line installation (when the OS is already prepared): Quick Install (one-liner)
- Operations script catalog: Operations — At a Glance
- Upgrade procedure: Upgrade (
upgrade.sh) - Environment variables / configuration: System Configuration (
app.properties) - Restoring from backup: Backup (
backup.sh)