Skip to main content

Air-Gapped Network Installation

This procedure is used when installing a gateway at sites where internet access is blocked (military facilities, high-security facilities, or certain factories). The standard One-Line Installation requires access to product.kopens.io; since this is not possible in an air-gapped network, you must obtain the deliverables from an external source, transfer them via USB or NAS, and then perform the installation.

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

Preparation PC (Internet Available)​

Do not create the export bundle manually; bake it using airgap-bundle.sh. This bundles the repository files and container images together, preventing version mismatches. In GitLab, you can also run the airgap:export manual job and download it as an artifact.

# 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)

Verify in container mode after installation:

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

Post-installation upgrades are also performed without internet—import the new image file and run pe upgrade --bundle (Air-Gapped Upgrade).

The completion criteria for air-gapped installations are the same. Before moving to production, record the delivery of backup files, acceptance logs, image tags, and credentials according to the Production Readiness Criteria.

Common Pitfalls​

SymptomCause / Resolution
tar: Error opening archiveThe image on the USB was only partially copied. Compare the sha256 on the preparation PC and copy again.
docker load shows «no space left»Insufficient space in /var/lib/docker. Ensure more than twice the image size is available.
Service stops at activatingOne module is lagging. Check journalctl -u plantpulse-edge -f and bin/logs.sh to identify the module.
Incorrect time (Year 1970)No NTP access in the air-gapped network. Add the internal NTP server IP to /etc/chrony.conf.
install.sh calls an external URLThe offline argument was omitted. Use the commands from the air-gapped procedure above exactly.
SymptomCause / Resolution
dnf install stops due to missing internet--disablerepo=* option omitted. Use the options from section 3.1 above.
tar: Error opening archiveDeliverables on the USB were only partially copied. Compare sha256 on the preparation PC and copy again.
systemctl status plantpulse → activatingStuck at a stage in bin/start.sh. Check live status via journalctl -u plantpulse -f.
Incorrect time (Year 1970)No NTP access in the air-gapped network. Add the internal NTP server IP to /etc/chrony.conf.
install.sh calls download URLMissing modification of sed—change all URLs within install.sh to file:///mnt/usb/....

Learn More​