원라인 설치 (권장)

개요

PlantPulse 플랫폼을 단 한 줄의 명령으로 설치할 수 있는 가장 빠른 방법입니다. 다운로드 서버에서 설치 스크립트를 받아 OS 셋업, Docker 설치, 방화벽 구성, Docker Compose 스택 기동까지 자동으로 수행합니다.

언제 사용하나요? 표준 환경(Oracle Linux 8 / RHEL 9 / Ubuntu 20.04+ / Amazon Linux 2023)에서 기본 설정으로 빠르게 설치하고 싶을 때 적합합니다. 세부 설정을 단계별로 검토해야 하는 운영 환경에서는 Docker 설치 페이지의 수동 설치 절차를 권장합니다.

설치 모드 선택

설치 전에 어떤 구성으로 설치할지 먼저 결정하세요.

구성	서버 대수	권장 상황	가이드
단일 박스 (FULL) — 기본	1대 (권장 256GB, 최소 128GB)	표준 구성. 이 페이지 절차 그대로	이 페이지
2노드 분리 (DATALAKE/APP)	2대 (64GB + 48GB)	단일 서버 메모리가 부족하거나 데이터 부하와 콘솔을 분리하고 싶을 때	2노드 분리 설치
폐쇄망 (Airgap)	—	인터넷 미연결 환경	Docker 설치의 폐쇄망 절

아래 절차는 단일 박스(FULL) 기준입니다. 환경 변수 없이 실행하면 FULL로 설치됩니다.

지원 환경

OS	버전
Oracle Linux	8.x
RHEL / Rocky Linux	8.x, 9.x
Ubuntu	20.04+ (20 / 22 / 24)
Amazon Linux	2, 2023

사전 준비

• 인터넷 연결이 가능한 서버 (다운로드 서버 product.kopens.io 접근 필요)
• root 권한
• 최소 16 vCPU / 64GB RAM / 200GB 디스크 (기본 32 vCPU / 128GB RAM · 운영 권장 256GB RAM)

폐쇄망(Airgap) 환경에서는 원라인 설치를 사용할 수 없습니다. Docker 설치 페이지의 폐쇄망 설치 절차를 참고해 주세요.

설치 실행

서버에 SSH로 접속한 후 아래 명령을 실행합니다.

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

스크립트가 자동으로 수행하는 작업:

1. OS 자동 감지 (RHEL/Rocky/Oracle 8·9, Ubuntu 20+, Amazon Linux)
2. Docker Engine + Compose v2 설치 및 데몬 설정 (data-root)
3. 커널 / 리소스 튜닝 (limits.conf, sysctl.conf, chrony.conf, tmpfiles.d)
4. SELinux permissive 전환 및 swap 비활성화
5. 방화벽 포트 자동 오픈 — 공개 포트(80/443/7443/4949/4950)와 사설망 제한 포트
6. 서비스 자격 사이드카(/etc/kopens/plantpulse-platform.env) 생성
7. 컨테이너 레지스트리(docker.kopens.io) 로그인
8. Docker 네트워크 / 볼륨 생성 후 compose 스택 기동

무엇이 뜨는지

설치가 끝나면 컨테이너 아홉 개가 정의되고 그중 여덟 개가 상시 동작합니다 — 인프라(plantpulse-datalake), 앱 여섯(plantpulse-server-web · plantpulse-batch-web · plantpulse-warehouse · plantpulse-plugin-opcua-server · plantpulse-plugin-aasx-server · plantpulse-ha), 엣지(plantpulse-proxy). 나머지 하나(plantpulse-certs)는 TLS 자재를 굽고 끝나는 원샷이라 Exited (0) 이 정상입니다.

자세한 구성은 Docker 설치 — 설치되는 모양을 참고해 주세요.

설치 스크립트는 스택 기동 후 준비될 때까지 폴링합니다. 프로세스 기동 자체는 3~5분(JVM 워밍업)이지만, 클린 설치는 Cassandra 스키마 마이그레이션과 안정화 때문에 전 컴포넌트가 안정되기까지 15~18분이 걸립니다. 재시작은 스키마가 이미 존재하므로 훨씬 빠릅니다.

설치 옵션

# Docker가 이미 설치된 경우 OS 셋업 단계 생략
curl -fsSL https://product.kopens.io/plantpulse-platform/install.sh | bash -s -- --skip-os

옵션	효과
--skip-os	OS 셋업 및 Docker 설치 생략 (이미 Docker가 설치된 경우)

참고: 원라인 설치는 레지스트리 인증이 자동 구성되므로 별도의 docker login 이 필요 없습니다. 방화벽 생략(SKIP_FW=1), 레지스트리 로그인 생략(SKIP_LOGIN=1), Docker data-root 경로 변경(DOCKER_DATA_DIR, 기본 /data1/docker-data)은 노드에 내려받은 bin/install.sh 를 직접 실행할 때 환경 변수로 지정합니다 → Docker 설치

설치 확인

설치가 완료되면 아래 명령으로 상태를 확인합니다.

cd /opt/kopens/plantpulse-platform-docker/bin
./status.sh        # 0 = 정상 / 2 = 비정상
./ops-check.sh

curl -kfsS https://<서버IP>:4950/api/health | jq   # "status":"OK" 또는 "WARN" 이면 정상
docker ps          # 여덟 개가 (healthy), plantpulse-certs 는 Exited (0)

docker ps 에 plantpulse-platform 이 없다고 실패한 것이 아닙니다

그 이름의 단일 컨테이너 구성은 폐기되었습니다. 컨테이너 이름은 위 아홉 개이며, 옛 런북의 docker logs plantpulse-platform 은 동작하지 않습니다. 로그는 ./logs.sh 로 보세요.

모든 항목이 정상이면 브라우저에서 웹 콘솔에 접속합니다.

https://[서버IP]          # 웹 콘솔 (80/443, plantpulse-proxy 가 받습니다)
https://[서버IP]:7443     # 관리 UI
https://[서버IP]:4950     # 모니터 UI

• 기본 관리자 계정: admin / admin123!
• 로그인 후에는 반드시 비밀번호를 변경해 주세요. → 초기 비밀번호

설치 후 환경 변수 조정

원라인 설치는 호스트를 보고 자원값을 자동으로 계산하므로, 대부분의 서버에서는 손댈 것이 없습니다. 로케일처럼 자동으로 정할 수 없는 값만 조정하면 됩니다.

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

자주 조정하는 항목:

변수	설명	기본값
PP_LANG	플랫폼 로케일 (ko / en)	en — 한국어 운영이면 ko
PP_TZ	플랫폼 타임존	Asia/Seoul
DOCKER_PP_CPUS	컨테이너에 줄 vCPU 수	nproc 결과 (자동)
DOCKER_PP_MEMORY	메모리 상한	호스트 RAM 의 90% (자동)
DOCKER_DATALAKE_MEMORY	데이터레이크 메모리 상한	80G, 호스트가 작으면 RAM 의 90%
DOCKER_PP_DATA_DISK_NAME	데이터 디스크 이름	자동 역추적 (실패 시 sda)
DOCKER_PP_EXTERNAL_IP	NAT 환경의 외부 advertise IP	빈 값 — NAT 뒤가 아니면 비워 둡니다

DOCKER_PP_EXTERNAL_IP 는 함부로 채우지 마세요

이 값은 TLS 인증서의 SAN 목록으로 들어갑니다. 유효하지 않은 IP 를 넣으면 인증서가 한 장도 생성되지 않아 스택이 뜨지 못합니다.

다국어 박스: 기본 로케일은 en 입니다. 한국어 환경에서는 PP_LANG=ko 로 변경한 후 ./restart.sh 로 적용합니다. 단, Cassandra 시계열 데이터가 KST epoch 로 적재되므로 한국 운영 시에는 반드시 Asia/Seoul 을 유지해야 합니다.

전체 환경 변수 목록은 환경 변수 레퍼런스를 참고해 주세요.

자주 쓰는 운영 명령

cd /opt/kopens/plantpulse-platform-docker/bin

./preflight.sh           # 설치 전 비파괴 사전 점검
./up.sh                  # 기동 — 준비될 때까지 대기 (0 = 준비 완료)
./down.sh                # 정지 (상태 보존)
./restart.sh             # graceful 재시작 (drain + 준비 대기)
./status.sh              # 서비스 / health / 볼륨 요약 (0=정상 / 2=비정상)
./logs.sh [서비스]       # 로그 보기 (1회 출력, -f 로 따라가기). 인자가 없으면 전체, 목록은 --list
./shell.sh [서비스]      # 컨테이너 bash 진입 (인자 없으면 데이터레이크)
./ops-check.sh           # 운영 health + 최근 critical log 점검
./update.sh              # 이미지 갱신 (pull + recreate + 실패 시 rollback)
./remove.sh              # 컨테이너 제거 (볼륨은 보존)
./doctor.sh              # 장애 진단 tarball 생성

모든 동사가 --help 를 지원합니다. 옛 이름(stack-run.sh · stack-stop.sh · stack-bash.sh · stack-update.sh · stack-remove.sh)도 그대로 동작합니다.

문제 해결

다운로드 스크립트 실행 실패

# 다운로드 서버 접근 가능 여부 확인
curl -fsSL https://product.kopens.io/plantpulse-platform/install.sh -o /tmp/install.sh
ls -al /tmp/install.sh

# 회사 방화벽 / 프록시로 차단된 경우 네트워크 관리자에게 도메인 허용 요청:
#   product.kopens.io, docker.kopens.io

컨테이너가 healthy 상태로 전환되지 않음

어떤 컨테이너가 문제인지부터 좁힙니다.

cd /opt/kopens/plantpulse-platform-docker/bin
./status.sh                              # 어떤 서비스가 비정상인가
./logs.sh --list                         # 볼 수 있는 서비스 목록
./logs.sh plantpulse-server-web -n 200   # 그 컨테이너의 로그

./doctor.sh    # 진단 tarball 생성 후 기술 지원팀에 전달 (모든 컨테이너를 담습니다)

Cassandra 스키마 마이그레이션 실패 또는 /data1/pp-data 권한 문제일 가능성이 높습니다. 자세한 절차는 Docker 설치 — 스택이 뜨지 않는 경우에 있습니다.

추가 문의

기타 문제는 Docker 설치 페이지의 문제 해결 섹션을 먼저 확인해 주시고, 해결되지 않는 경우 webmaster@kopens.com 으로 연락해 주세요.