> For the complete documentation index, see [llms.txt](https://kopens.gitbook.io/plantpulse-platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kopens.gitbook.io/plantpulse-platform/installation/docker.md).

# Docker 설치

## 개요

PlantPulse 플랫폼은 Docker(또는 Podman) 컨테이너 기반으로 설치하는 것을 권장합니다. Docker를 이용하면 복잡한 환경 설정 없이 간편하게 플랫폼을 설치하고 운영할 수 있습니다.

> **Docker란?** Docker는 애플리케이션을 "컨테이너"라는 격리된 환경에서 실행할 수 있게 해주는 도구입니다. 쉽게 말해, 플랜트펄스에 필요한 모든 프로그램과 설정이 하나의 패키지로 묶여 있어서, 복잡한 설치 과정 없이 한 번에 실행할 수 있습니다.

Docker 설치 방식과 바이너리 설치 방식의 차이는 다음과 같습니다:

| 항목          | Docker 설치         | 바이너리 설치                   |
| ----------- | ----------------- | ------------------------- |
| **설치 시간**   | 10\~15분           | 30분\~1시간                  |
| **환경 의존성**  | 없음 (컨테이너에 모두 포함)  | Java, OS 라이브러리 등 수동 설치 필요 |
| **업데이트**    | 이미지 교체로 간단 업데이트   | 수동 파일 교체 및 호환성 확인 필요      |
| **롤백**      | 이전 이미지로 즉시 복원     | 백업 파일에서 수동 복원             |
| **클러스터 확장** | 워커 컨테이너 추가로 간단 확장 | 서버별 개별 설치 필요              |
| **격리성**     | OS와 완전 분리         | OS 환경에 영향 받음              |

> **권장**: 특별한 사유가 없으시다면 Docker 설치 방식을 선택해 주세요. 바이너리 설치는 Docker를 사용할 수 없는 환경에서만 필요합니다.

## 지원 환경

아래 운영체제에서 Docker 설치가 가능합니다.

| OS           | 버전             | 컨테이너 런타임         |
| ------------ | -------------- | ---------------- |
| AWS Linux    | 2, 2023        | Docker           |
| RHEL         | 8.x, 9.x       | Docker 또는 Podman |
| Ubuntu       | 20.04+, 22.04+ | Docker           |
| Oracle Linux | 8.x+           | Docker 또는 Podman |

## 사전 준비

### 1단계: 설치 디렉토리 생성

플랫폼이 설치될 디렉토리를 먼저 만들어 주세요.

```bash
# 설치 루트 경로를 생성합니다
mkdir -p /home/kopens
cd /home/kopens
```

### 2단계: 설치 파일 다운로드

Git 저장소에서 Docker 설치 스크립트를 다운로드합니다. Git이 설치되어 있지 않다면 먼저 `dnf install git`으로 설치해 주세요.

```bash
git clone http://dev.kopens.io/plantpulse-platform/plantpulse-docker.git
chmod -R 755 ./plantpulse-docker
cd ./plantpulse-docker
```

다운로드가 완료되면 아래와 같은 디렉토리 구조가 생성됩니다:

```
plantpulse-docker/
├── bin/                    # 운영 스크립트 (플랫폼 실행/중지/업데이트 등)
│   ├── env.sh              # 공통 환경 변수 설정 (★ 반드시 수정 필요)
│   ├── platform-run.sh     # 플랫폼 실행
│   ├── platform-stop.sh    # 플랫폼 중지
│   ├── platform-update.sh  # 플랫폼 업데이트
│   ├── platform-remove.sh  # 플랫폼 제거
│   ├── platform-bash.sh    # 컨테이너 내부 쉘 접속
│   ├── platform-version.sh # 버전 확인
│   ├── worker-run.sh       # 워커 실행 (클러스터용)
│   ├── worker-stop.sh      # 워커 중지
│   ├── worker-update.sh    # 워커 업데이트
│   ├── worker-remove.sh    # 워커 제거
│   ├── worker-bash.sh      # 워커 컨테이너 접속
│   ├── status.sh           # 전체 서비스 상태 확인
│   ├── compose/            # Docker Compose 스크립트
│   │   ├── start.sh
│   │   └── stop.sh
│   └── util/               # 유틸리티 스크립트
│       ├── backup-volume.sh
│       ├── copy-log-to-local.sh
│       ├── remove-all-volumes.sh
│       ├── run-map-server.sh
│       ├── stats.sh
│       ├── system.sh
│       └── update-memory.sh
└── tools/                  # OS별 초기 셋업 스크립트
    ├── setup_awslinux.sh
    ├── setup_rhel8.sh
    ├── setup_rhel9.sh
    ├── setup_ubuntu.sh
    ├── file/               # 시스템 설정 파일
    └── firewall/           # 방화벽 스크립트
```

### 3단계: OS 초기 설정 및 Docker 설치

사용하시는 OS에 맞는 셋업 스크립트를 실행해 주세요. 이 스크립트가 Docker 설치와 시스템 설정을 자동으로 처리해 줍니다.

```bash
cd /home/kopens/plantpulse-docker/tools/

# 사용하시는 OS에 해당하는 스크립트를 하나만 실행해 주세요
./setup_rhel8.sh      # RHEL 8.x / Oracle Linux 8.x 사용 시
# 또는
./setup_rhel9.sh      # RHEL 9.x / Oracle Linux 9.x 사용 시
# 또는
./setup_ubuntu.sh     # Ubuntu 20.04+ 사용 시
# 또는
./setup_awslinux.sh   # AWS Linux 사용 시
```

셋업 스크립트가 자동으로 수행하는 작업은 다음과 같습니다:

* Docker (또는 Podman) 설치 및 서비스 등록
* 시스템 파일 제한 설정 (`limits.conf`) — 동시에 열 수 있는 파일 수 확장
* 커널 파라미터 설정 (`sysctl.conf`) — 메모리 맵 제한 등 확장
* NTP 시간 동기화 설정 (chrony) — 정확한 시간 기록을 위해 필요
* 임시 디렉토리 설정

### 4단계: 환경 변수 설정

`env.sh` 파일은 모든 스크립트의 공통 설정 파일입니다. 서버 환경에 맞게 수정해 주세요.

```bash
cd /home/kopens/plantpulse-docker/bin
vi env.sh
```

**반드시 수정해야 하는 항목** — 아래 4가지는 서버 환경에 맞게 꼭 변경해 주세요:

| 변수                         | 설명                                | 기본값               | 예시              |
| -------------------------- | --------------------------------- | ----------------- | --------------- |
| `DOCKER_PP_EXTERNAL_IP`    | 서버의 외부 접속 IP (브라우저에서 접속할 IP)      | `111.222.333.444` | `192.168.0.110` |
| `DOCKER_PP_CPUS`           | 플랫폼에 할당할 CPU 코어 수                 | `32`              | `16`            |
| `DOCKER_PP_MEMORY`         | 플랫폼 메모리 제한 (서버 전체 메모리의 80% 정도 권장) | `200G`            | `128G`          |
| `DOCKER_PP_DATA_DISK_NAME` | 데이터 디스크 이름 (`lsblk` 명령으로 확인 가능)   | `sda`             | `sda`           |

**선택적으로 수정할 수 있는 항목** — 특별한 경우가 아니면 기본값을 그대로 사용하셔도 됩니다:

| 변수                  | 설명                              | 기본값                                       |
| ------------------- | ------------------------------- | ----------------------------------------- |
| `DOCKER_CMD`        | 컨테이너 명령어 (`docker` 또는 `podman`) | `docker`                                  |
| `DOCKER_PP_IMAGE`   | 플랫폼 이미지 경로                      | `docker.kopens.io/pp/plantpulse-platform` |
| `DOCKER_PP_VERSION` | 이미지 버전 태그                       | `latest`                                  |
| `DOCKER_PP_NAME`    | 플랫폼 컨테이너 이름                     | `plantpulse-platform`                     |
| `DOCKER_PP_IP`      | 컨테이너 내부 IP                      | `10.99.0.100`                             |
| `DOCKER_PP_NETWORK` | Docker 네트워크 이름                  | `pp-net`                                  |
| `DOCKER_GATEWAY`    | 네트워크 게이트웨이                      | `10.99.0.1`                               |
| `DOCKER_SUBNET`     | 네트워크 서브넷                        | `10.99.0.0/24`                            |

> **Podman을 사용하시는 경우**: `DOCKER_CMD="docker"`를 `DOCKER_CMD="podman"`으로 변경해 주시면, 모든 스크립트가 Podman으로 동작합니다.

## 플랫폼 실행

### 플랫폼(마스터) 시작

환경 변수 설정이 완료되었다면, 아래 명령으로 플랫폼을 시작합니다.

```bash
cd /home/kopens/plantpulse-docker/bin
./platform-run.sh
```

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

1. Docker 네트워크 생성 (`pp-net`) — 컨테이너 간 통신을 위한 가상 네트워크
2. Docker 볼륨 생성 (`pp-data`, `pp-temp`, `pp-backup`, `pp-security`, `pp-template`) — 데이터 영구 저장 공간
3. 플랫폼 이미지 다운로드 (최초 실행 시에만)
4. 컨테이너 생성 및 시작
5. 로그 디렉토리 초기화

> **최초 실행 시 참고**: 이미지 다운로드에 네트워크 속도에 따라 5\~15분이 소요될 수 있습니다. 이후 실행부터는 이미 다운로드된 이미지를 사용하므로 빠르게 시작됩니다.

### 상태 확인

플랫폼이 정상적으로 실행되었는지 확인해 주세요.

```bash
cd /home/kopens/plantpulse-docker/bin
./status.sh
```

모든 서비스가 `RUNNING` 상태로 표시되면 정상입니다. 플랫폼 내부의 모든 컴포넌트가 완전히 시작되기까지 약 3\~5분 정도 소요되므로, 잠시 기다린 후 확인해 주세요.

### 웹 콘솔 접속

브라우저를 열고 아래 주소로 접속합니다.

```
http://[서버IP]:7500
```

* `[서버IP]` 부분을 `env.sh`에서 설정한 `DOCKER_PP_EXTERNAL_IP` 값으로 바꿔 주세요.
  * 예: `http://192.168.0.110:7500`
* 기본 관리자 계정: **admin** / **admin123!**
* 로그인 후 요약(Summary) 화면이 표시되면 설치가 성공적으로 완료된 것입니다.

> **보안 안내**: 로그인 후에는 보안을 위해 기본 비밀번호를 꼭 변경해 주세요. 상단 오른쪽의 사용자 아이콘 > 비밀번호 변경 메뉴를 이용하시면 됩니다.

## 플랫폼 운영

### 플랫폼 중지

```bash
cd /home/kopens/plantpulse-docker/bin
./platform-stop.sh
```

내부의 모든 서비스를 안전하게 종료한 후 컨테이너를 중지합니다. 데이터는 Docker 볼륨에 안전하게 보존되므로, 다시 시작하면 이전 데이터가 그대로 유지됩니다.

### 플랫폼 업데이트

새 버전이 릴리즈되면 아래 명령으로 업데이트할 수 있습니다.

```bash
cd /home/kopens/plantpulse-docker/bin
./platform-update.sh
```

업데이트 스크립트의 동작 순서:

1. 새 이미지 다운로드 (`docker pull`)
2. 기존 컨테이너 안전 종료
3. 기존 컨테이너 삭제
4. 새 이미지로 컨테이너 재생성 및 시작

> **데이터 안전**: 데이터는 Docker 볼륨에 별도로 저장되므로, 업데이트 시에도 데이터는 유지됩니다. 안심하고 업데이트하셔도 됩니다.

### 플랫폼 제거

```bash
cd /home/kopens/plantpulse-docker/bin
./platform-remove.sh
```

확인 프롬프트가 표시되며, 컨테이너와 이미지, 네트워크를 제거합니다.

> **데이터 보호**: 실수로 데이터가 삭제되는 것을 방지하기 위해 볼륨은 자동으로 삭제되지 않습니다. 볼륨까지 삭제하려면 별도로 `bin/util/remove-all-volumes.sh`를 실행해 주세요.

### 컨테이너 쉘 접속

문제 해결이나 설정 확인이 필요할 때 컨테이너 내부에 직접 접속할 수 있습니다.

```bash
cd /home/kopens/plantpulse-docker/bin
./platform-bash.sh
```

컨테이너 내부의 `/home/kopens` 경로에서 바이너리 설치와 동일한 디렉토리 구조를 확인할 수 있습니다. 접속을 종료하려면 `exit`를 입력해 주세요.

### 버전 확인

```bash
cd /home/kopens/plantpulse-docker/bin
./platform-version.sh
```

현재 사용 중인 이미지 버전과 컨테이너 생성일을 확인할 수 있습니다.

## 클러스터 구성 (워커 추가)

대규모 환경에서 데이터 처리 성능을 확장해야 할 때, 워커 컨테이너를 추가하여 분산 처리가 가능합니다. 소규모 환경에서는 이 과정을 건너뛰셔도 됩니다.

### 워커 IP 설정

`env.sh`에서 워커 IP 배열을 설정합니다. 워커를 추가할 개수만큼 IP를 지정해 주세요.

```bash
DOCKER_PW_IP_ARRAY=("10.99.0.101" "10.99.0.102" "10.99.0.103" "10.99.0.104" "10.99.0.105")
DOCKER_PW_MEMORY="100G"
```

### 워커 실행

```bash
cd /home/kopens/plantpulse-docker/bin
./worker-run.sh
```

프롬프트에서 시작할 워커 번호를 입력합니다:

```
워커 번호를 입력하세요 => 1
```

입력한 번호에 해당하는 워커 컨테이너(`plantpulse-worker-1`)가 생성되고 시작됩니다.

### 워커 중지 / 업데이트 / 제거

```bash
# 워커 중지
./worker-stop.sh

# 워커 업데이트 (새 이미지로 교체)
./worker-update.sh

# 워커 제거
./worker-remove.sh
```

각 명령을 실행하면 대상 워커 번호를 입력하는 프롬프트가 표시됩니다.

## Docker Compose 방식

Docker Compose를 사용하면 플랫폼과 워커를 한 번에 시작/중지할 수 있어 편리합니다.

```bash
# 전체 시작
cd /home/kopens/plantpulse-docker/bin/compose
./start.sh

# 전체 중지
./stop.sh
```

## 유틸리티 스크립트

운영에 필요한 유틸리티 스크립트가 `bin/util/` 디렉토리에 제공됩니다.

### 볼륨 백업

Docker 볼륨 데이터를 tar.gz 파일로 백업합니다. 정기적으로 백업해 두시면 데이터 손실을 방지할 수 있습니다.

```bash
cd /home/kopens/plantpulse-docker/bin/util
./backup-volume.sh pp-data 7 /data1/pp-backup/docker-volume
```

| 인자   | 설명                           | 기본값                              |
| ---- | ---------------------------- | -------------------------------- |
| 첫 번째 | 백업할 볼륨 이름 (필수)               | -                                |
| 두 번째 | 백업 보관 일수 (이보다 오래된 백업은 자동 삭제) | 7일                               |
| 세 번째 | 백업 저장 경로                     | `/data1/pp-backup/docker-volume` |

### 로그 수집

컨테이너 내부의 주요 로그를 로컬 서버로 복사합니다. 문제 발생 시 로그를 분석하거나 기술 지원 요청 시 유용합니다.

```bash
cd /home/kopens/plantpulse-docker/bin/util
./copy-log-to-local.sh
```

로그가 `/tmp/plantpulse-log` 경로에 복사됩니다:

* `plantpulse-messaging/` — 메시징 관련 로그 (Kafka, MQTT 등)
* `plantpulse-storage/` — 스토리지 관련 로그 (Cassandra, PostgreSQL 등)
* `plantpulse-server/` — 웹 서버 로그
* `plantpulse-batch/` — 배치 처리 서버 로그

### 리소스 모니터링

실행 중인 컨테이너의 CPU, 메모리 사용량을 실시간으로 확인합니다.

```bash
cd /home/kopens/plantpulse-docker/bin/util
./stats.sh
```

### 시스템 용량 조회

Docker 이미지, 레이어, 빌드 캐시의 디스크 사용량을 확인합니다.

```bash
cd /home/kopens/plantpulse-docker/bin/util
./system.sh
```

### 메모리 제한 변경

실행 중인 컨테이너의 메모리 제한을 `env.sh` 설정값으로 갱신합니다.

```bash
cd /home/kopens/plantpulse-docker/bin/util
./update-memory.sh
```

### 지도 서버 실행

요약 화면에서 공장 위치를 지도에 표시하기 위한 별도 지도 서버를 실행합니다.

```bash
cd /home/kopens/plantpulse-docker/bin/util
./run-map-server.sh
```

한국 지도 데이터(`kr.mbtiles`)를 자동으로 다운로드하고, 포트 3650에서 지도 타일 서버를 실행합니다.

### 전체 볼륨 제거

> **주의**: 이 명령은 모든 데이터를 영구적으로 삭제합니다. 실행 전에 반드시 백업이 완료되었는지 확인해 주세요. 삭제된 데이터는 복구할 수 없습니다.

```bash
cd /home/kopens/plantpulse-docker/bin/util
./remove-all-volumes.sh
```

확인 프롬프트에서 `YES`를 입력해야만 삭제가 진행됩니다.

## 문제 해결

설치 과정에서 문제가 발생하셨나요? 아래 내용을 확인해 주세요.

### 컨테이너가 시작되지 않는 경우

```bash
# 1. 컨테이너 로그를 확인하여 에러 원인을 파악합니다
docker logs plantpulse-platform

# 2. Docker 서비스 자체가 실행 중인지 확인합니다
systemctl status docker

# 3. 디스크 공간이 충분한지 확인합니다 (디스크가 가득 차면 시작이 실패합니다)
df -h
```

### 이미지 다운로드 실패

```bash
# 1. 이미지 레지스트리에 접속이 가능한지 확인합니다
docker login docker.kopens.io

# 2. 수동으로 이미지를 다운로드해 봅니다
docker pull docker.kopens.io/pp/plantpulse-platform:latest
```

네트워크 방화벽으로 인해 레지스트리 접속이 차단될 수 있습니다. 네트워크 관리자에게 `docker.kopens.io` 도메인의 접근 허용을 요청해 주세요.

### 포트 충돌

플랫폼은 여러 포트를 사용하므로, 다른 서비스와 포트가 겹칠 수 있습니다.

```bash
# 특정 포트를 사용 중인 프로세스를 확인합니다
ss -tlnp | grep :<포트번호>

# 충돌하는 프로세스를 확인한 후 중지해 주세요
```

상세 포트 목록은 [포트 및 서비스 관리](/plantpulse-platform/admin/ports.md) 페이지를 참고해 주세요.

## 기술 지원

설치 및 운영 과정에서 도움이 필요하시면 언제든 문의해 주세요: **<webmaster@kopens.com>**