Quick Install — 2026.05+ Container Standard
This page describes the standard procedure for installing a single gateway in the field.
From 2026.05 onward, PlantPulse Edge ships as a single Docker container image, and
install.sh handles everything from OS dependencies to systemd registration in one pass.
Once installation completes, plantpulse-edge.service manages the container.
Do not run it alongside the legacy native service plantpulse.service.
0. At a Glance
sudo -i
curl -fsSL https://product.kopens.io/plantpulse-edge/install.sh | bash
Installation normally takes 5–15 minutes, including the image pull. It can take longer on slow links or on boxes where Docker has to be installed for the first time.
1. One-Minute Pre-Install Check
# Linux / 권한
uname -a
id
# 외부 다운로드 도달성
curl -I https://product.kopens.io/plantpulse-edge/install.sh
# 디스크 / 메모리
df -h /opt /data1 2>/dev/null || df -h /opt
free -h
| Item | Requirement |
|---|---|
| Privileges | root (sudo -i) |
| Network | HTTPS reachability to product.kopens.io |
| Disk | /opt/kopens 3GB+, /data1 100GB+ recommended for data |
| Memory | 8GB minimum, 16GB or more recommended |
| Existing services | plantpulse.service / plantpulse-edge.service must not be active at the same time |
Organize the values approved by the operations team before installation according to the Production Acceptance Criteria.
install.sh installs and aligns Docker, OS packages, sysctl, firewall, and chrony.
If internal policy blocks package installation, request an exception from your security/IT team
or switch to Offline Installation.
2. Running the Installation
Recommended: Download the install bundle, then run it
sudo -i
curl -fsSLO https://product.kopens.io/plantpulse-edge/plantpulse-edge-docker.tar.gz
mkdir -p /opt/kopens/plantpulse-edge-docker
tar xzf plantpulse-edge-docker.tar.gz -C /opt/kopens/plantpulse-edge-docker --strip-components=1
cd /opt/kopens/plantpulse-edge-docker/bin
bash install.sh
The bundle approach leaves the installation files on disk, which makes fault analysis and re-runs easier.
No matter where you extracted the bundle, install.sh copies operations scripts such as
status.sh · health.sh · upgrade.sh to /opt/kopens/install/bin/.
That is why the rest of the documentation refers to /opt/kopens/install/bin/… —
you do not need to remember where you extracted the bundle.
Alternative: One-line execution
sudo -i
bash < <(curl -fsSL https://product.kopens.io/plantpulse-edge/install.sh)
3. Specifying Site and Network Values
You can install with the defaults, but field deliveries normally specify the env values below.
sudo -i
cd /opt/kopens/install
EDGE_ID=EDGE_00303 \
SITE_ID=SITE_00001 \
SERVER_HOST=192.168.0.41 \
SERVER_API_KEY='<platform-api-key>' \
LAN1_IFACE=enp1s0 \
LAN1_IP=192.168.100.10/24 \
LAN2_IFACE=enp2s0 \
LAN2_IP=192.168.0.10/24 \
LAN2_GATEWAY=192.168.0.1 \
LAN2_DNS=192.168.0.1 \
bash install.sh
Commonly used env variables:
| Variable | Meaning |
|---|---|
EDGE_ID | Gateway ID. Example: EDGE_00303 |
SITE_ID | Site ID. Example: SITE_00001 |
SERVER_HOST / SERVER_API_KEY | Platform API integration details |
LAN1_IFACE / LAN1_IP | PLC network NIC and static IP |
LAN2_IFACE / LAN2_IP / LAN2_GATEWAY / LAN2_DNS | WAN/external network NIC and routing |
ADMIN_PASS / API_KEY / MQTT_PASS / OPCUA_PASS | Override with the initial credentials set by the operations team |
CERT_PASS | TLS keystore password. This is the only official cert password key |
IMAGE_TAG | Pin a specific container image tag |
SKIP_PULL=1 | For air-gapped network or re-run cases where the image is already loaded locally |
To keep passwords and API keys out of shell history, use the secret-safe install env
pattern. Put operations-assigned passwords in a root-owned 0600 file, source it, and then run install.sh.
4. Normal Output During Installation
The example varies slightly by version, but the flow is the same.
[install] prepare directories ... OK
[install] install packages / docker ... OK
[install] configure sysctl / firewall / chrony ... OK
[install] generate TLS material ... OK
[install] write /etc/kopens/app.properties ... OK
[install] docker pull docker.kopens.io/pe/plantpulse-edge:<tag> ... OK
[install] install systemd unit plantpulse-edge.service ... OK
[install] start service ... OK
[install] health probe /api/v1/system/health ... OK
INSTALL COMPLETED.
On first install, the admin/MQTT/OPC-UA/API keys are generated randomly per box and stored in
/etc/kopens/credentials.txt. Manage this file with chmod 0600 root.
5. Post-Install Verification
# service 상태
systemctl is-active plantpulse-edge.service
systemctl status plantpulse-edge.service --no-pager
# 설치 도구의 한 줄 점검
sudo bash /opt/kopens/install/bin/status.sh
# version: container_mode=true 여야 함
curl -ks https://127.0.0.1/api/v1/system/version | python3 -m json.tool
# health: HTTP 200 + components UP
curl -ks https://127.0.0.1/api/v1/system/health | python3 -m json.tool
Browser:
| Screen | URL |
|---|---|
| Web UI | https://<gateway-ip>/ui/main |
| Node-RED | https://<gateway-ip>/ui/flow/ |
| Swagger UI | https://<gateway-ip>/public/swagger-ui/index.html |
For the initial login password, check the admin entry in /etc/kopens/credentials.txt.
Right after installation, continue with the Post-Install Checklist and the Production Acceptance Criteria.
Capturing Acceptance Evidence
Before field acceptance, reproducible text evidence matters more than screenshots of the health page.
sudo bash /opt/kopens/install/bin/health.sh
sudo bash /opt/kopens/install/bin/status.sh > /root/pp-edge-status-$(date +%Y%m%d-%H%M%S).txt
For the full acceptance log, use the commands in Collecting Acceptance Evidence.
6. Common Pitfalls
| Symptom | Cause / Response |
|---|---|
Could not resolve host: product.kopens.io | DNS or corporate firewall. Check DNS, proxy, and allow-list. If it still fails, use Offline Installation |
curl: (7) Failed to connect | Outbound 443 blocked, or a proxy is required. Configure HTTPS_PROXY and retry |
No space left on device | Not enough free space on /opt or /data1. Check df -h and free up space |
docker pull takes a long time | The first image pull is several GB. On a slow link, consider bringing in the image tar.zst via the air-gapped procedure |
plantpulse.service is also active | Conflict with the legacy native service. In container-based operation, stop and disable the native service |
| Cannot reach the web UI after installation completes | First check curl -ks https://127.0.0.1/api/v1/system/health from inside the gateway. If it works internally, the problem is an external firewall/NAT issue |
| Certificate warning | With a self-signed certificate, a browser warning on first access is expected. The deployment policy for production CA certificates follows the site security standard |
| Health returns 503 | Check journalctl -u plantpulse-edge.service -n 100 and docker logs plantpulse-edge |
For more detailed, symptom-specific actions, see Installation Troubleshooting.
7. Next Steps
- Post-Install Checklist — health, first login, site/edge ID verification
- Production Acceptance Criteria — restart, backup, evidence files, security lockdown
- Adding a New PLC connection
- Registering tags
- Operations — Container Mode
- Backup / Restore