メインコンテンツまでスキップ

エアギャップ環境へのインストール

インターネットが遮断された閉域網（エアギャップ）サーバーへインストールする手順です。 流れは3ステップです。

① 인터넷 되는 PC          ② USB 등 이동 매체         ③ 폐쇄망 서버
   번들 내려받기      →      반출              →      로드 → 설정 → 기동
   무결성·서명 검증                                    (검증 자동 재확인)

サーバー仕様・ポート・ファイアウォール要件は インストール の「事前要件」と同じです。 まずそちらの節を確認してください。

0. 閉域網サーバーの事前準備​

ワンラインインストールスクリプトは、Dockerが無い場合にインターネットからダウンロードしてインストールします — 閉域網ではこの経路は機能しません。Dockerは事前にインストールしておいてください。

docker --version
docker compose version      # v2.22 이상

ディストリビューションのオフラインリポジトリ、またはRPM/DEBパッケージでインストールしてください。署名検証まで行う場合は cosign バイナリも併せて持ち込んでください（任意 — 無い場合は検証のみスキップされます）。

1. インターネット接続環境でのダウンロード​

取得するファイルは4つです。

ファイル内容
plantpulse-studio-images-<version>.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.txt

latest.txt は最新バージョンの名前のみを記載した1行のファイルです（例：2026.08）。バンドルのコピーではないため、新バージョンが出てもダウンロード対象のファイルは変わりません。

一度公開されたバージョンのファイルは削除されません。 2026.09 が出ても plantpulse-studio-images-2026.08.tar.gz はそのまま残るので、使用中のバージョンを再取得したりロールバックする際に、いつでもそのアドレスをそのまま利用できます。 インストール手順をスクリプト化している場合は、latest.txt ではなくバージョンを直接明記する方が安全です。

イメージバンドルに含まれるもの

Studioサーバー・Web・セッションランタイム・ビルダーサイドカー・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などに以下の4ファイルをそのままコピーします。.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 중 부재) が表示される場合は、3つのうちいずれかが存在しないという意味です。検証なしで続行するかはセキュリティポリシーに従って判断してください — 最低限 .sha256 の整合性検証だけでも通すことを推奨します。

3-3. 設定ファイルの作成​

cp .env.example .env
vi .env
chmod 600 .env

エアギャップ環境で必ず調整が必要な項目です。

項目値理由
REGISTRY空にすること（REGISTRY=）値があると起動ごとにレジストリへのpullを試み、遅延や警告が発生します
TAG搬入したバンドルのバージョン（2026.07）ロードされたイメージタグと一致する必要があります
PG_PASSWORD十分に長いランダム文字列バンドルのPostgreSQLを使用する場合
PLATFORM_API_TARGET現場のPlatformアドレス実データ・認証委任の対象
STUDIO_LOCAL_USERSadmin:<password>初回ログインアカウント
PP_LANG / PP_TZko / Asia/Seoul韓国語の現場

AI・Platformのキーは シークレット管理 を参照して .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 はヘルス・Web応答・実際のログイン・セッションランタイムイメージ・コンテナ状態を一括で検査します。すべて通過すれば実際に利用可能な状態です。

ブラウザで http://<server-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 にはPlatformアドレス・アカウント・APIキーが、dist/ にはローカルバックアップが格納されています。 まとめて上書きするとスタックが起動しない、またはバックアップを失います。

6. エアギャップ環境でのバックアップ・リストア​

バックアップ・リストアのスクリプトはインターネットなしで動作します — 外部PostgreSQLを使用する際に必要な postgres:18-alpine イメージが搬入バンドルに含まれているためです。

bash bin/backup.sh                 # 백업
DRYRUN=1 bash bin/restore.sh       # 복구 리허설(비파괴)

詳細は バックアップとリストア をご覧ください。

次のステップ​