에어갭 설치
인터넷이 차단된 폐쇄망(에어갭) 서버에 설치하는 절차입니다. 흐름은 세 단계입니다.
① 인터넷 되는 PC ② USB 등 이동 매체 ③ 폐쇄망 서버
번들 내려받기 → 반출 → 로드 → 설정 → 기동
무결성·서명 검증 (검증 자동 재확인)
서버 사양·포트·방화벽 요구사항은 설치 문서의 "사전 요구사항"과 동일합니다. 먼저 그 절을 확인하세요.
0. 폐쇄망 서버 사전 준비
원라인 설치 스크립트는 도커가 없으면 인터넷에서 내려받아 설치합니다 — 폐쇄망에서는 이 경로가 동작하지 않습니다. 도커는 미리 설치해 두세요.
docker --version
docker compose version # v2.22 이상
배포판 오프라인 저장소나 RPM/DEB 패키지로 설치하면 됩니다. 서명 검증까지 하려면
cosign 바이너리도 함께 반입하세요(선택 — 없으면 검증만 생략됩니다).
1. 인터넷 되는 곳에서 내려받기
받을 파일은 네 개입니다.
| 파일 | 내용 |
|---|---|
plantpulse-studio-images-<버전>.tar.gz | 컨테이너 이미지 5종 묶음(약 2.8 GB) |
…tar.gz.sha256 | 무결성 검증용 체크섬 |
…tar.gz.sig | 출처(서명) 검증용 Cosign 서명 |
plantpulse-studio-docker.tar.gz | 운영 패키지 — bin/ 스크립트 · compose · .env.example · cosign.pub |
BASE=https://product.kopens.io/plantpulse-studio
VER=2026.08 # 또는: VER=$(curl -fsSL $BASE/latest.txt)
# 번들은 수 GB — 전송이 끊기면 -C - 가 이어받습니다
curl -fLO -C - --retry 5 $BASE/plantpulse-studio-images-$VER.tar.gz
curl -fLO $BASE/plantpulse-studio-images-$VER.tar.gz.sha256
curl -fLO $BASE/plantpulse-studio-images-$VER.tar.gz.sig
curl -fLO $BASE/plantpulse-studio-docker.tar.gz
latest.txtlatest.txt 는 최신 버전 이름만 담은 한 줄짜리 파일입니다(예: 2026.08). 번들 복사본이
아니라서 새 버전이 나와도 받던 파일이 바뀌지 않습니다.
한 번 게시된 버전본은 지우지 않습니다. 2026.09 가 나와도 plantpulse-studio-images-2026.08.tar.gz
는 그대로 남으니, 쓰던 버전을 다시 받거나 되돌릴 때 언제든 그 주소를 그대로 쓰시면 됩니다.
설치 절차를 스크립트로 고정해 두셨다면 latest.txt 대신 버전을 직접 적어두시는 편이 안전합니다.
스튜디오 서버 · 웹 · 세션 런타임 · 빌더 사이드카 · PostgreSQL 이미지 5종이 모두 들어 있습니다. 폐쇄망에서 추가로 받아야 할 이미지는 없습니다.
무결성·출처 검증(반출 전)
먼저 운영 패키지를 풀어 공개키(cosign.pub)를 꺼냅니다.
mkdir -p pkg && tar xzf plantpulse-studio-docker.tar.gz -C pkg --strip-components=1
# ① 무결성 — 전송 중 파일이 깨지지 않았는가
sha256sum -c plantpulse-studio-images-$VER.tar.gz.sha256
# ② 출처 — KOPENS 가 서명한 번들이 맞는가
cosign verify-blob --key pkg/cosign.pub --insecure-ignore-tlog=true \
--signature plantpulse-studio-images-$VER.tar.gz.sig \
plantpulse-studio-images-$VER.tar.gz
--insecure-ignore-tlog 가 붙는 이유사내 레지스트리 원칙상 공개 투명성 로그(Rekor)를 쓰지 않습니다. 이 옵션은 공개 로그 조회만 생략할 뿐, 서명 자체는 암호학적으로 그대로 검증됩니다.
CDN 캐시일 수 있습니다. URL 뒤에 ?v=$(date +%s) 를 붙여 다시 받으세요.
2. 이동 매체로 반출
USB 등에 아래 네 파일을 그대로 복사합니다. .sha256 과 .sig 를 빠뜨리지 마세요 —
반입 측 스크립트가 이 파일들로 자동 재검증합니다.
plantpulse-studio-images-2026.08.tar.gz
plantpulse-studio-images-2026.08.tar.gz.sha256
plantpulse-studio-images-2026.08.tar.gz.sig
plantpulse-studio-docker.tar.gz
3. 폐쇄망 서버에서 반입
3-1. 운영 패키지 배치
sudo mkdir -p /opt/kopens/plantpulse-studio-docker
sudo tar xzf /media/usb/plantpulse-studio-docker.tar.gz \
-C /opt/kopens/plantpulse-studio-docker --strip-components=1
cd /opt/kopens/plantpulse-studio-docker
mkdir -p dist
sudo cp /media/usb/plantpulse-studio-images-2026.08.tar.gz* dist/
3-2. 이미지 로드
sudo bash bin/load.sh dist/plantpulse-studio-images-2026.08.tar.gz
load.sh 는 같은 폴더에 .sha256 · .sig 가 있으면 자동으로 검증한 뒤, 불일치하면
반입을 중단합니다.
✅ 서명 검증 통과
▶ 로드 중: dist/plantpulse-studio-images-2026.08.tar.gz
✅ 로드 완료 — cp .env.example .env 설정 후 bin/start.sh
⚠ 서명 검증 생략(.sig/cosign.pub/cosign 중 부재) 이 보이면 셋 중 하나가 없다는
뜻입니다. 검증 없이 진행할지는 보안 정책에 따라 판단하세요 — 최소한 .sha256
무결성 검증만이라도 통과시키는 것을 권장합니다.
3-3. 설정 파일 작성
cp .env.example .env
vi .env
chmod 600 .env
에어갭에서 반드시 손봐야 할 항목입니다.
| 항목 | 값 | 이유 |
|---|---|---|
REGISTRY | 비워 둘 것 (REGISTRY=) | 값이 있으면 기동할 때마다 레지스트리 pull 을 시도하다 지연·경고가 발생합니다 |
TAG | 반입한 번들의 버전 (2026.07) | 로드된 이미지 태그와 일치해야 합니다 |
PG_PASSWORD | 충분히 긴 임의 문자열 | 번들 PostgreSQL 사용 시 |
PLATFORM_API_TARGET | 현장 플랫폼 주소 | 실데이터·인증 위임 대상 |
STUDIO_LOCAL_USERS | admin:<비밀번호> | 첫 로그인 계정 |
PP_LANG / PP_TZ | ko / Asia/Seoul | 한국어 현장 |
AI · 플랫폼 키는 비밀 관리를 참고해 .env 에 넣습니다.
외부 PostgreSQL 을 쓴다면 설치 문서의 "데이터베이스 선택"을 그대로 따르세요.
3-4. 기동
bash bin/start.sh
ℹ️ REGISTRY 비어있음(로컬/에어갭) — pull 생략, 로컬 이미지 사용
⏳ 헬스 대기...
✅ PlantPulse Studio 시작됨 → http://192.168.x.x/
4. 설치 확인
bash bin/status.sh
bash bin/smoke-install.sh
smoke-install.sh 는 헬스 · 웹 응답 · 실제 로그인 · 세션 런타임 이미지 · 컨테이너 상태를
한 번에 검사합니다. 모두 통과하면 실제로 사용 가능한 상태입니다.
브라우저에서 http://<서버IP>/ 로 접속해 STUDIO_LOCAL_USERS 계정으로 로그인하세요.
이후 절차는 설치 문서의 "첫 로그인"과 같습니다.
5. 에어갭 환경 업데이트
새 버전 번들을 같은 방법으로 반입해 로드한 뒤 재기동하면 됩니다.
cd /opt/kopens/plantpulse-studio-docker
bash bin/backup.sh # ① 먼저 백업
sudo cp /media/usb/plantpulse-studio-images-2026.08.tar.gz* dist/
sudo bash bin/load.sh dist/plantpulse-studio-images-2026.08.tar.gz # ② 새 이미지 로드
sed -i 's/^TAG=.*/TAG=2026.08/' .env # ③ 태그 변경
bash bin/restart.sh # ④ 재기동
운영 스크립트(bin/)까지 갱신하려면 새 plantpulse-studio-docker.tar.gz 를 임시 폴더에 풀고
.env 와 dist/ 를 제외한 파일만 덮어쓰세요.
.env 와 dist/ 는 절대 덮어쓰지 마세요.env 에는 플랫폼 주소·계정·API 키가, dist/ 에는 로컬 백업이 들어 있습니다.
통째로 덮어쓰면 스택이 뜨지 않거나 백업을 잃습니다.
6. 에어갭에서의 백업·복구
백업·복구 스크립트는 인터넷 없이 동작합니다 — 외부 PostgreSQL 을 쓸 때 필요한
postgres:18-alpine 이미지가 반입 번들에 포함돼 있기 때문입니다.
bash bin/backup.sh # 백업
DRYRUN=1 bash bin/restore.sh # 복구 리허설(비파괴)
자세한 내용은 백업과 복구를 보세요.
다음 단계
- 비밀 관리 — 키를
.env에만 두는 원칙 - 도메인과 리버스 프록시 — 사내 도메인·HTTPS 로 서비스하기
- 백업과 복구
- 트러블슈팅