> 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/requirements.md).

# 시스템 요구사항

PlantPulse 플랫폼을 안정적으로 운영하기 위한 하드웨어 / OS / 네트워크 요건을 안내합니다. 검증된 표준 환경을 기준으로 작성되었습니다.

## 한눈에 보는 요건

| 구분          | 최소 (개발 / 테스트)         | 표준 (운영)               | 대규모              |
| ----------- | --------------------- | --------------------- | ---------------- |
| **CPU**     | 16 vCPU               | **32 vCPU**           | 48+ vCPU         |
| **메모리**     | 64 GB                 | **128 GB**            | 200 GB+          |
| **OS 디스크**  | 200 GB                | 256 GB                | 512 GB           |
| **데이터 디스크** | 200 GB (SSD)          | **1 TB (NVMe SSD)**   | 4 TB+ (NVMe SSD) |
| **네트워크**    | 1 Gbps                | 1 Gbps                | 10 Gbps          |
| **OS**      | RHEL/Rocky/Oracle 8.x | RHEL/Rocky/Oracle 9.x | 동일               |
| **JDK**     | OpenJDK 21 LTS        | OpenJDK 21 LTS        | OpenJDK 21 LTS   |

> **검증 환경**: 운영 검증 환경(reference dev server)은 **48 vCPU / 188 GB RAM / 4.8 TB NVMe SSD / RHEL 9 / Temurin OpenJDK 21.0.11 LTS** 로 운영 중입니다.

## 하드웨어

```mermaid
graph LR
  CPU[CPU<br/>32 vCPU+] --> JVM[JVM 워크로드<br/>Server · CEP · Spark · Cassandra]
  RAM[RAM<br/>128 GB+] --> CACHE[페이지 캐시<br/>+ JVM Heap]
  NVME[NVMe SSD<br/>1 TB+] --> DATA[Cassandra commitlog · SSTable<br/>Kafka log · MinIO 오브젝트]
  NET[네트워크<br/>1 Gbps+] --> EDGE[Edge 디바이스 · 외부 시스템]
```

### CPU

* **권장: 32 vCPU 이상** (Intel Xeon, AMD EPYC, ARM Graviton 등)
* IIoT 엔진은 36 스레드 파이프라인을 사용 (`engine.pipeline.threads`)
* Spark 분산 분석은 `PP_CLUSTER_CORES` 만큼 추가 사용
* 코어가 많을수록 동시 메시지 처리량 ↑

### 메모리

* **권장: 128 GB 이상**
* 메모리는 페이지 캐시로 Cassandra / Kafka 성능에 직접 영향
* Cassandra 힙: 호스트 메모리의 1/4 (최대 32 GB)
* 컨테이너 메모리 한계: `DOCKER_PP_MEMORY` 로 호스트 메모리의 90% 까지 가능

### 디스크

> **OS / 데이터 디스크 분리 권장**: OS 디스크 (`/`) 와 데이터 디스크 (`/data1`) 를 분리해야 백업 / 확장 / 장애 격리가 쉬워집니다.

```
/                       # OS 디스크 (256 GB)
└── opt/kopens/         # PlantPulse 바이너리 설치

/data1/                 # 데이터 디스크 (1 TB+ NVMe SSD)
├── pp-data/            # Cassandra · PostgreSQL · MinIO · Valkey
├── pp-temp/            # Spark / 처리 임시
└── pp-backup/          # 백업 산출물
```

| 마운트                  | 용량     | 디스크 종류          | 용도                                |
| -------------------- | ------ | --------------- | --------------------------------- |
| `/`                  | 256 GB | SSD             | OS, 바이너리                          |
| `/data1`             | 1 TB+  | **NVMe SSD 필수** | 메인 데이터                            |
| `/data2` \~ `/dataN` | 1 TB+  | NVMe SSD        | (옵션) Cassandra 데이터 / commitlog 분리 |

### Cassandra 디스크 최적화 (고급)

대규모 환경에서 commitlog 와 data 를 별도 디스크에 두면 쓰기 처리량이 크게 향상됩니다.

```
/data1/pp-data/cassandra/data/          # SSTable (대용량 NVMe)
/data2/pp-data/cassandra/commitlog/      # commitlog (별도 NVMe, sync I/O)
```

## 운영체제

### 지원 OS

| OS           | 버전       | 검증 | 권장 |
| ------------ | -------- | -- | -- |
| Oracle Linux | 8.x, 9.x | ✓  | 권장 |
| RHEL         | 8.x, 9.x | ✓  | 권장 |
| Rocky Linux  | 8.x, 9.x | ✓  | 권장 |
| AlmaLinux    | 8.x, 9.x | ✓  |    |
| Ubuntu       | 22.04+   | ✓  |    |
| Amazon Linux | 2, 2023  | ✓  |    |

> **이후 모든 안내는 RHEL/Rocky/Oracle 9.x 기준**입니다. Ubuntu / Amazon Linux 사용 시 패키지 명령(`apt` / `yum`) 만 환경에 맞게 바꿔 주세요.

### Java (JDK)

PlantPulse 는 **Java 21 LTS** 기반입니다. `setup.sh` / `tools/java/` 가 자동 설치합니다.

```bash
$ java -version
openjdk version "21.0.11" 2026-04-21 LTS
OpenJDK Runtime Environment Temurin-21.0.11+10 (build 21.0.11+10-LTS)
```

수동 설치가 필요한 경우:

```bash
# RHEL/Rocky/Oracle
dnf install -y java-21-openjdk java-21-openjdk-devel

# Ubuntu
apt-get install -y openjdk-21-jdk
```

`JAVA_HOME` 환경 변수가 자동 등록되며, 모든 모듈은 `JAVA_TOOL_OPTIONS="-Duser.language=${PP_LANG} -Duser.timezone=${PP_TZ}"` 로 통합 적용됩니다.

## 네트워크 / 호스트명

### 호스트명

```bash
hostnamectl set-hostname plantpulse-prod-01

# /etc/hosts
vi /etc/hosts
# 첫 행 직후에 추가:
# 192.168.0.41   plantpulse-prod-01 plantpulse-prod-01.local
```

### 고정 IP

서버 IP 가 변경되면 클러스터 / 클라이언트 연결이 끊어지므로 반드시 고정 IP 를 사용합니다.

```bash
# NetworkManager (RHEL 9+)
nmcli con mod ens33 ipv4.method manual \
  ipv4.addresses 192.168.0.41/24 \
  ipv4.gateway 192.168.0.1 \
  ipv4.dns "168.126.0.1 8.8.8.8"
nmcli con up ens33
```

### 시간 동기화 (필수)

분산 컴포넌트 (Cassandra, Kafka 등) 는 노드 간 시간 정확도에 매우 민감합니다.

```bash
dnf install -y chrony
systemctl enable --now chronyd
chronyc tracking         # 동기화 상태 확인
chronyc -a makestep      # 즉시 동기화
```

## OS 튜닝 (필수)

`tools/setup.sh` 가 자동으로 적용하지만, 수동 환경에서는 다음을 직접 설정해 주세요.

### 파일 디스크립터 / 프로세스 한계

```bash
# /etc/security/limits.conf
* - memlock unlimited
* - nofile 500000
* - nproc 32768
* - as unlimited
```

### 커널 파라미터

```bash
# /etc/sysctl.d/99-plantpulse.conf
vm.max_map_count = 1048575
vm.swappiness = 1
fs.file-max = 1000000
net.core.somaxconn = 65535
net.ipv4.tcp_tw_reuse = 1
net.ipv4.tcp_fin_timeout = 30

sysctl --system
```

### Swap 비활성화

데이터베이스 / Java 프로세스는 swap 을 피해야 합니다.

```bash
swapoff --all
# /etc/fstab 의 swap 라인 주석 처리
sed -i '/swap/s/^/#/' /etc/fstab
```

### SELinux

`setup.sh` 가 자동으로 `permissive` 로 전환합니다. 수동 변경:

```bash
setenforce 0
sed -i 's/^SELINUX=enforcing/SELINUX=permissive/' /etc/selinux/config
```

### Native 라이브러리

Cassandra 성능 향상을 위한 라이브러리.

```bash
dnf install -y jna jemalloc jemalloc-devel zstd libpq
```

## 디스크 I/O 튜닝

### NVMe SSD

```bash
# /etc/udev/rules.d/60-ioscheduler.rules
ACTION=="add|change", KERNEL=="nvme[0-9]*", ATTR{queue/scheduler}="none"
ACTION=="add|change", KERNEL=="sd*", ATTR{queue/rotational}=="0", ATTR{queue/scheduler}="mq-deadline"

# 즉시 적용
udevadm trigger
```

### HDD (운영 비권장)

```bash
echo mq-deadline > /sys/block/sdb/queue/scheduler
blockdev --setra 128 /dev/sdb
```

## 방화벽

설치 중에는 비활성화하고, 운영 시 필요한 포트만 개방합니다.

```bash
# 설치 중
systemctl stop firewalld

# 운영 (firewalld)
systemctl start firewalld
firewall-cmd --permanent --add-port=80/tcp
firewall-cmd --permanent --add-port=443/tcp
firewall-cmd --permanent --add-port=7443/tcp
firewall-cmd --permanent --add-port=4949/tcp
firewall-cmd --permanent --add-port=1883/tcp
firewall-cmd --permanent --add-port=1884/tcp
firewall-cmd --permanent --add-port=9092/tcp
firewall-cmd --permanent --add-port=9094/tcp
firewall-cmd --reload
```

전체 포트 목록은 [포트 구성 정보](/plantpulse-platform/installation/ports.md) 참고.

> **상위 방화벽 / 클라우드 보안 그룹**: 회사 / 클라우드 방화벽은 별도이므로 함께 허용해 주세요. 사설망 대역 (RFC 1918, Tailscale CGN) 은 신뢰 가능한 IP 로 source 제한을 추천합니다.

## 외부 접속 / 노출 권장

```mermaid
graph TB
  USER[운영자 / 외부 시스템] --> LB[리버스 프록시<br/>nginx · HAProxy]
  EDGE[IoT 디바이스] --> LB
  LB --> WEB[plantpulse-server<br/>:80 · :443]
  LB --> MQTT_TLS[MQTT TLS<br/>:1884 / :18884]
  LB --> KAFKA_TLS[Kafka TLS<br/>:9094]

  subgraph PRIV["사설망 only"]
    CASS[Cassandra :9042]
    PG[PostgreSQL :5432]
    SPARK[Spark :7077]
    JMX[JMX :6199-7899]
  end
```

| 외부 노출          | 포트                | 권장                  |
| -------------- | ----------------- | ------------------- |
| 웹 콘솔           | 80, 443, 7443     | nginx/HAProxy 경유 권장 |
| 헬스체크           | 4949              | 모니터링 시스템 only       |
| MQTT (외부 디바이스) | 1884 (TLS), 18884 | TLS 권장              |
| Kafka 외부 클라이언트 | 9094 (TLS)        | TLS 필수              |
| 데이터 게이트웨이      | 5500              | API Key + TLS       |

DB / 메시징 PLAINTEXT 포트 / JMX 는 **사설망 only** 로 제한해 주세요.

## 지원 브라우저

웹 콘솔은 최신 표준 브라우저를 지원합니다.

| 브라우저           | 최소 버전 | 권장     |
| -------------- | ----- | ------ |
| Google Chrome  | 100+  | **권장** |
| Microsoft Edge | 100+  | ✓      |
| Firefox        | 100+  | ✓      |
| Safari         | 15+   | ✓      |

## 사전 점검 체크리스트

설치 전 다음을 확인해 주세요.

* [ ] CPU 16+ vCPU, 메모리 64+ GB, 데이터 디스크 200+ GB
* [ ] 데이터 디스크가 별도 `/data1` 에 마운트
* [ ] OS RHEL/Rocky/Oracle 8+ 또는 Ubuntu 22.04+
* [ ] 고정 IP 설정
* [ ] `chronyd` 활성화 (시간 동기화)
* [ ] 호스트명 + `/etc/hosts` 등록
* [ ] swap 비활성화
* [ ] `nofile 500000` 등 limits 적용
* [ ] `vm.max_map_count` 등 sysctl 적용
* [ ] 방화벽 정책 (외부 노출 포트 명확)
* [ ] DNS 정상 작동 (`getent hosts <hostname>`)
* [ ] 인터넷 접근 또는 폐쇄망 번들 준비

## 다음 단계

* 빠르게 설치 → [원라인 설치 (권장)](/plantpulse-platform/installation/one-line-install.md)
* 컨테이너 기반 설치 → [Docker 설치](/plantpulse-platform/installation/docker.md)
* 호스트 직접 설치 → [바이너리 설치](/plantpulse-platform/installation/java-tomcat.md)
* 포트 충돌 확인 → [포트 구성 정보](/plantpulse-platform/installation/ports.md)