Skip to main content

Offline / Air-gapped Installation (Air-gap)

This procedure applies when you deploy a gateway at a site with no internet access (military facilities, security-graded facilities, some plants). The standard Quick Install requires reaching product.kopens.io, which is impossible on an air-gapped network, so you must fetch the artifacts externally, move them in on USB / NAS, and then install.

Move two items: the install package and the container image tar.zst. When install.sh detects a sibling image/*.tar.zst, it imports it automatically via docker load (bypassing the registry pull).

Staging PC (internet available)​

Do not build the export bundle by hand — burn it with airgap-bundle.sh. It bundles the repository files and the container image into a single unit, so versions can never drift. On GitLab, you can also run the airgap:export manual job and download the result as artifacts.

# 1) 저장소 받기
curl -fsSLO https://product.kopens.io/plantpulse-edge/plantpulse-edge-docker.tar.gz
mkdir -p plantpulse-edge-docker
tar xzf plantpulse-edge-docker.tar.gz -C plantpulse-edge-docker --strip-components=1

# 2) 반출 번들 굽기 — 저장소 + 이미지가 함께 들어간다
sudo bash plantpulse-edge-docker/bin/airgap-bundle.sh

# 3) USB / NAS 로 옮김 (파일명 예: plantpulse-edge-images-2026.07.tar.gz)
cp plantpulse-edge-images-*.tar.gz /media/usb/

Air-gapped box (no internet)​

sudo -i
mkdir -p /opt/kopens/plantpulse-edge-docker
tar xzf /media/usb/plantpulse-edge-images-*.tar.gz \
    -C /opt/kopens/plantpulse-edge-docker --strip-components=1
cd /opt/kopens/plantpulse-edge-docker/repo/bin
# 필요하면 env.sh 에서 EDGE_ID / SITE_ID 를 박스별로 조정한 뒤 실행
sudo bash airgap-load.sh
# airgap-load.sh: 오프라인 Docker 설치 → 이미지 docker load → install.sh(SKIP_PULL=1)

After installation, verify in container mode:

sudo bash /opt/kopens/install/bin/status.sh
sudo bash /opt/kopens/install/bin/health.sh
curl -ks https://127.0.0.1/api/v1/system/version | python3 -m json.tool
curl -ks https://127.0.0.1/api/v1/system/health  | python3 -m json.tool

The completion criteria are the same on an air-gapped network. Before going into operation, follow the Production Readiness Criteria and record the backup files, acceptance log, image tag, and whether credentials were handed over.

(legacy) Native-mode air-gap procedure​

The procedure below applies only to native boxes older than 2026.05. Use the container mode above for new deployments.

1. What you need​

ItemNotes
A staging PC with internet accessFor downloading artifacts (an office PC is fine)
USB disk (32GB+ recommended)Carries the artifacts + dependency RPMs
PlantPulse artifactsKOPENS_EDGE_V<version>.tar.zstd (~1GB)
Copy of install.shRequires some edits to work on an air-gapped network (URL → local path)
OS RPM packagesDownloaded in advance so dnf can install without internet

2. On the staging PC (internet available)​

2.1 Download the artifacts + install.sh​

# USB 마운트 위치
USB=/mnt/usb

# 산출물 (가장 최신 버전 — 약 1GB)
curl --proto =https --tlsv1.2 --fail \
  -o $USB/KOPENS_EDGE_V2026.tar.zstd \
  https://product.kopens.io/plantpulse-edge/KOPENS_EDGE_V2026.tar.zstd

# install.sh 도 같이 (참고용 — 폐쇄망에선 수정 후 사용)
curl --proto =https --tlsv1.2 --fail \
  -o $USB/install.sh \
  https://product.kopens.io/plantpulse-edge/install.sh

# (옵션) sha256 검증 파일
curl --proto =https --tlsv1.2 --fail \
  -o $USB/install.sh.sha256 \
  https://product.kopens.io/plantpulse-edge/install.sh.sha256 || true

2.2 Download the OS dependency RPMs (Fedora 38)​

Download only — no install — the packages that setup.sh installs via dnf, and put them on the USB:

# 빈 디렉토리
mkdir -p $USB/rpms
cd $USB/rpms

# setup.sh 의 dnf install 라인의 패키지 목록
PKGS="tar htop fping pv firefox java-17-openjdk-devel jna jemalloc \
      jemalloc-devel zstd curl-devel expat-devel uuid wget sysstat \
      chrony tuned net-tools numactl nodejs npm python3 fail2ban \
      gcc glibc-devel zlib-devel libstdc++-static NetworkManager-tui \
      docker-ce docker-ce-cli containerd.io \
      java-17-amazon-corretto-devel"

# 의존성 포함 다운로드 (--downloadonly + --resolve)
sudo dnf install --downloadonly --resolve --downloaddir=$USB/rpms $PKGS

2.3 Edit install.sh (URL → local path)​

# install.sh 의 다운로드 부분을 USB 경로로
sed -i 's|https://download\.kopens\.[a-z]*\.com|file:///mnt/usb|g' $USB/install.sh
sed -i 's|https://download\.kopens\.[a-z]*\.io|file:///mnt/usb|g'  $USB/install.sh
# (혹은 install.sh 내부의 `curl ... KOPENS_EDGE_*.tar.zstd` 라인을 직접 편집해 USB 경로 사용)

Safely eject the USB.

3. On the air-gapped gateway​

3.1 Mount the USB + bulk-install the RPMs​

# USB 인식
sudo mount /dev/sdb1 /mnt/usb       # 디바이스 명은 환경마다 다름

# RPM 일괄 설치 (의존성 자동 해결)
sudo rpm -Uvh --force --replacepkgs /mnt/usb/rpms/*.rpm

# (옵션) tar 보관소가 있으면 dnf 로도 가능:
#   sudo dnf install --disablerepo=* --nogpgcheck /mnt/usb/rpms/*.rpm

3.2 Extract the artifacts​

sudo mkdir -p /opt
cd /opt
sudo tar -I 'zstd -d' -xvf /mnt/usb/KOPENS_EDGE_V2026.tar.zstd
# /opt/kopens 에 풀림

3.3 H/W initialization (optional) — skip the dependency step in tools/setup.sh​

The dnf install step is already handled by the RPMs, so run only certain setup.sh steps manually:

sudo -i
cd /opt/kopens/tools

# 호스트명
hostnamectl set-hostname EDGE_<number>

# env.sh 생성
cat > /opt/kopens/plantpulse-edge/conf/env.sh << EOF
export KOPENS_HOME=/opt/kopens
export PE_HOME=/opt/kopens/plantpulse-edge
export PE_DATA_DIR=/data1
export JAVA_HOME=/usr/lib/jvm/java-17-amazon-corretto
export CLEAN_ON_STARTUP=true
EOF
mkdir -p /data1

# 네트워크 (대화형)
./net/set-1.sh
./net/set-2.sh
systemctl restart NetworkManager.service

# 로케일 + 타임존
localectl set-locale LANG=ko_KR.utf8
timedatectl set-timezone Asia/Seoul

# tuned + 방화벽 + sysctl + chrony + ssl + vpn
systemctl enable --now tuned
tuned-adm profile throughput-performance
./firewall/open.sh
./file/run.sh
./ssl/gen.sh
# ./vpn/setup.sh   # 폐쇄망에선 보통 미사용

# CPU governor + hugepages
for f in /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor; do echo performance > $f; done
echo 9216 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages

# systemd 서비스 등록
cp /opt/kopens/tools/service/plantpulse.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable plantpulse

3.4 Start​

sudo systemctl start plantpulse
sleep 60          # 풀스택 부팅 대기
/opt/kopens/plantpulse-edge/bin/ps.sh
curl -s http://127.0.0.1/api/v1/system/health | jq

4. Upgrading (air-gapped)​

The automatic download in upgrade.sh requires internet and cannot be used. Manual procedure:

# 1. 준비 PC 에서 새 산출물 USB 로 옮김 (위 2.1 동일)
# 2. 폐쇄망 게이트웨이에서:
sudo /opt/kopens/plantpulse-edge/bin/backup.sh

sudo /opt/kopens/plantpulse-edge/bin/stop.sh
cd /opt
sudo mv kopens kopens.old.$(date +%Y%m%d-%H%M%S)
sudo tar -I 'zstd -d' -xvf /mnt/usb/KOPENS_EDGE_V<new-version>.tar.zstd
sudo /opt/kopens/plantpulse-edge/bin/start.sh

After verification, keep the kopens.old.* directory (or delete it if disk space is short).

5. Common pitfalls​

SymptomCause / Fix
dnf install hangs looking for internetThe --disablerepo=* option was omitted. Use the options in 3.1 exactly as shown
tar: Error opening archiveOnly part of the artifact files were copied to the USB. Compare sha256 against the staging PC and re-copy
systemctl status plantpulse → activatingSomething is stuck in one of the bin/start.sh steps. Watch live with journalctl -u plantpulse -f
Clock is wrong (year 1970)No NTP reachable on the air-gapped network. Add the in-house NTP server IP to /etc/chrony.conf
docker does not installdocker-ce was missing from the RPM download. Add the Fedora docker repo and download again
install.sh calls the download URLsed edit was missed — change every URL in install.sh to file:///mnt/usb/...

6. Learn more​