> 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/one-line-install.md).

# 원라인 설치 (권장)

## 개요

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

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

## 지원 환경

| OS                 | 버전       |
| ------------------ | -------- |
| Oracle Linux       | 8.x      |
| RHEL / Rocky Linux | 8.x, 9.x |
| Ubuntu             | 22.04+   |
| Amazon Linux       | 2, 2023  |

## 사전 준비

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

> 폐쇄망(Airgap) 환경에서는 원라인 설치를 사용할 수 없습니다. [Docker 설치](/plantpulse-platform/installation/docker.md) 페이지의 폐쇄망 설치 절차를 참고해 주세요.

## 설치 실행

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

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

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

1. OS 자동 감지 (RHEL/Rocky/Oracle 8·9, Ubuntu 20+, Amazon Linux)
2. Docker Engine 설치 및 데몬 설정 (data-root, insecure-registries)
3. 커널 / 리소스 튜닝 (`limits.conf`, `sysctl.conf`, `chrony.conf`, `tmpfiles.d`)
4. SELinux permissive 전환 및 swap 비활성화
5. 방화벽 포트 50여 개 자동 오픈
6. 컨테이너 레지스트리(`docker.kopens.io`) 로그인
7. Docker 네트워크 / 볼륨 생성 후 플랫폼 컨테이너 기동

부팅 완료까지 약 **3 \~ 5분** (Cassandra 스키마 마이그레이션 및 JVM warm-up 포함) 소요됩니다.

### 설치 옵션

다음 환경 변수를 함께 지정하여 동작을 조정할 수 있습니다.

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

# 레지스트리 로그인이 이미 되어 있는 경우 생략
SKIP_LOGIN=1 curl -fsSL https://download.kopens.io/plantpulse-platform/install.sh | bash

# 방화벽 설정 생략 (외부 방화벽에서 관리하는 경우)
SKIP_FW=1 curl -fsSL https://download.kopens.io/plantpulse-platform/install.sh | bash
```

| 옵션                         | 효과                                               |
| -------------------------- | ------------------------------------------------ |
| `SKIP_OS=1` 또는 `--skip-os` | OS 셋업 및 Docker 설치 생략 (이미 Docker가 설치된 경우)         |
| `SKIP_LOGIN=1`             | `docker login` 단계 생략                             |
| `SKIP_FW=1`                | 호스트 방화벽 설정 생략                                    |
| `DOCKER_DATA_DIR=경로`       | Docker data-root 경로 변경 (기본 `/data1/docker-data`) |

## 설치 확인

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

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

curl -kfsS https://127.0.0.1:4950/api/health | jq
docker ps    # STATUS = (healthy) 표시 확인
```

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

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

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

## 설치 후 환경 변수 조정

원라인 설치는 기본값으로 컨테이너를 기동하므로, 운영 환경에 맞춰 자원 / 외부 IP 등을 조정해야 합니다.

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

자주 조정하는 항목:

| 변수                         | 설명                                 | 기본값               |
| -------------------------- | ---------------------------------- | ----------------- |
| `DOCKER_PP_EXTERNAL_IP`    | 외부 노출 IP (브라우저 접속 / NAT advertise) | `111.222.333.444` |
| `DOCKER_PP_CPUS`           | 컨테이너 vCPU 수 (호스트의 90% 이하 권장)       | `32`              |
| `DOCKER_PP_MEMORY`         | 컨테이너 메모리 상한                        | `200G`            |
| `DOCKER_PP_DATA_DISK_NAME` | 데이터 디스크 이름 (`lsblk`로 확인)           | `sda`             |
| `PP_LANG`                  | 플랫폼 로케일 (`ko` / `en`)              | `ko`              |
| `PP_TZ`                    | 플랫폼 타임존                            | `Asia/Seoul`      |

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

전체 환경 변수 목록은 [Docker 설치](/plantpulse-platform/installation/docker.md) 페이지를 참고해 주세요.

## 자주 쓰는 운영 명령

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

./preflight.sh           # 설치 전 비파괴 사전 점검
./start.sh               # 정지된 컨테이너 시작
./platform-stop.sh       # 정지 (state 보존)
./restart.sh             # graceful 재시작 (drain + health 대기)
./status.sh              # 컨테이너 / health / 볼륨 요약
./ops-check.sh           # 운영 health + 최근 critical log 점검
./doctor.sh              # 장애 진단 tarball 생성
./platform-bash.sh       # 컨테이너 bash 진입
./platform-update.sh     # 이미지 갱신 (pull + recreate + rollback)
./platform-remove.sh     # 컨테이너 제거 (DESTRUCTIVE, 볼륨은 보존)
```

## 문제 해결

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

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

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

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

```bash
docker logs plantpulse-platform --tail 200

cd /home/kopens/plantpulse-platform-docker/bin
./doctor.sh    # 진단 tarball 생성 후 기술 지원팀에 전달
```

Cassandra 스키마 마이그레이션 실패 또는 `/data1/pp-data` 권한 문제일 가능성이 높습니다.

### 추가 문의

기타 문제는 [Docker 설치](/plantpulse-platform/installation/docker.md) 페이지의 문제 해결 섹션을 먼저 확인해 주시고, 해결되지 않는 경우 **<webmaster@kopens.com>** 으로 연락해 주세요.