본문으로 건너뛰기

빠른 설치 — 2026.05+ 컨테이너 표준

이 페이지는 현장에서 게이트웨이 1대를 설치할 때 쓰는 표준 절차입니다. PlantPulse Edge 는 2026.05부터 단일 Docker 컨테이너 이미지로 배포하며, install.sh 가 OS 의존성부터 systemd 등록까지 한 번에 처리합니다.

이 절차의 결과

설치가 끝나면 plantpulse-edge.service 가 컨테이너를 관리합니다. legacy native 서비스인 plantpulse.service 와 동시에 사용하지 않습니다.

0. 한눈에​

sudo -i
curl -fsSL https://product.kopens.io/plantpulse-edge/install.sh | bash

설치 중 image pull 을 포함해 보통 5-15분 걸립니다. 느린 회선이나 첫 Docker 설치가 필요한 박스에서는 더 오래 걸릴 수 있습니다.

1. 설치 전 1분 확인​

# 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
항목기준
권한root (sudo -i)
네트워크product.kopens.io 로 HTTPS 도달
디스크/opt/kopens 3GB+, /data1 데이터용 100GB+ 권장
메모리8GB 최소, 16GB 이상 권장
기존 서비스plantpulse.service / plantpulse-edge.service 동시 active 금지

설치 전 운영팀 승인 값은 프로덕션 인수 기준에 맞춰 정리합니다.

Java/Docker 가 없어도 먼저 이 절차를 시도

install.sh 가 Docker, OS 패키지, sysctl, firewall, chrony 를 설치/정렬합니다. 사내 정책상 패키지 설치가 막혀 있으면 보안팀/IT 에 허용을 요청하거나 오프라인 설치로 전환하세요.

2. 설치 실행​

권장: 설치 bundle 을 받은 뒤 실행​

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

bundle 방식은 설치 파일을 남기므로 장애 분석과 재실행이 쉽습니다.

설치 후 운영 스크립트는 고정 경로에 놓입니다

번들을 어디에 풀었든, install.sh 는 status.sh · health.sh · upgrade.sh 같은 운영 스크립트를 /opt/kopens/install/bin/ 에 복사합니다. 이후 문서에서 /opt/kopens/install/bin/… 로 안내하는 것은 그 때문입니다 — 번들을 푼 위치를 기억하지 않아도 됩니다.

대체: 원라인 실행​

sudo -i
bash < <(curl -fsSL https://product.kopens.io/plantpulse-edge/install.sh)

3. 사이트 값 / 네트워크 값 지정​

기본값으로도 설치할 수 있지만, 현장 납품에서는 보통 아래 env 를 명시합니다.

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

자주 쓰는 env:

변수의미
EDGE_ID게이트웨이 ID. 예: EDGE_00303
SITE_ID사이트 ID. 예: SITE_00001
SERVER_HOST / SERVER_API_KEY플랫폼 API 연동 정보
LAN1_IFACE / LAN1_IPPLC 망 NIC 와 static IP
LAN2_IFACE / LAN2_IP / LAN2_GATEWAY / LAN2_DNSWAN/외부망 NIC 와 routing
ADMIN_PASS / API_KEY / MQTT_PASS / OPCUA_PASS운영팀이 정한 초기 자격증명으로 override
CERT_PASSTLS keystore 비밀번호. 공식 cert password key 는 이것 하나만 사용
IMAGE_TAG특정 container image tag 고정
SKIP_PULL=1이미 image 를 local load 한 폐쇄망/재실행 케이스

비밀번호/API key 를 shell history 에 남기지 않으려면 secret-safe 설치 env 패턴을 사용합니다. 운영팀이 지정한 비밀번호도 root 0600 파일에 넣고 source 한 뒤 install.sh 를 실행하세요.

4. 설치 중 보이는 정상 출력​

예시는 버전에 따라 조금 다르지만 흐름은 같습니다.

[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.

첫 설치 시 admin/MQTT/OPC-UA/API key 는 박스별 random 으로 생성되고 /etc/kopens/credentials.txt 에 저장됩니다. 이 파일은 chmod 0600 root 로 관리하세요.

5. 설치 후 검증​

# 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

브라우저:

화면URL
웹 UIhttps://<게이트웨이-IP>/ui/main
Node-REDhttps://<게이트웨이-IP>/ui/flow/
Swagger UIhttps://<게이트웨이-IP>/public/swagger-ui/index.html

초기 로그인 비밀번호는 /etc/kopens/credentials.txt 의 admin 항목을 확인합니다. 설치 직후에는 설치 직후 체크리스트와 프로덕션 인수 기준을 이어서 진행하세요.

인수 증거 남기기​

현장 인수 전에는 health 화면 캡처보다 재현 가능한 텍스트 증거가 더 중요합니다.

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

전체 acceptance log 는 인수 증거 수집 명령을 사용합니다.

6. 자주 빠지는 함정​

증상원인 / 대응
Could not resolve host: product.kopens.ioDNS 또는 사내 방화벽. DNS, proxy, allow-list 확인. 안 되면 오프라인 설치
curl: (7) Failed to connectoutbound 443 차단 또는 proxy 필요. HTTPS_PROXY 설정 후 재시도
No space left on device/opt 또는 /data1 여유 부족. df -h 확인 후 공간 확보
docker pull 이 오래 걸림첫 image pull 은 수 GB 입니다. 회선이 느리면 폐쇄망 절차의 image tar.zst 반입도 고려
plantpulse.service 도 activelegacy native 와 충돌. 신규 컨테이너 운영에서는 native 서비스를 중지/비활성화
설치 완료 후 웹 접속 불가먼저 게이트웨이 내부에서 curl -ks https://127.0.0.1/api/v1/system/health 확인. 내부 OK 면 외부 firewall/NAT 문제
인증서 경고self-signed 인증서면 최초 접속 시 브라우저 경고가 정상. 운영 CA 인증서 배포 정책은 현장 보안 기준에 따름
health 가 503journalctl -u plantpulse-edge.service -n 100, docker logs plantpulse-edge 확인

더 자세한 증상별 조치는 설치 트러블슈팅을 봅니다.

7. 다음 단계​

  1. 설치 직후 체크리스트 — health, 첫 로그인, site/edge ID 확인
  2. 프로덕션 인수 기준 — 재시작, 백업, 증거 파일, 보안 잠금
  3. 새 PLC 연결 추가
  4. 태그 등록
  5. 운영 — 컨테이너 모드
  6. 백업 / 복구