atlas/docs/AIRGAP_INSTALLATION.md

Airgap Installation Guide for AtlasOS

Overview

AtlasOS installer supports airgap (offline) installation for data centers without internet access. All required packages and dependencies are bundled into a single directory that can be transferred to the airgap system.

Quick Start

Step 1: Download Bundle (On System with Internet)

On a system with internet access and Ubuntu 24.04:

# Clone the repository
git clone <repository-url>
cd atlas

# Run bundle downloader (requires root)
sudo ./installer/bundle-downloader.sh ./atlas-bundle

This will create a directory ./atlas-bundle containing:

• All required .deb packages (~100-200 packages)
• All dependencies
• Go binary (fallback)
• Manifest and README files

Estimated bundle size: 500MB - 1GB

Step 2: Transfer Bundle to Airgap System

Transfer the entire bundle directory to your airgap system using:

• USB drive
• Internal network (if available)
• Physical media

# Example: Copy to USB drive
cp -r ./atlas-bundle /media/usb/

# On airgap system: Copy from USB
cp -r /media/usb/atlas-bundle /tmp/

Step 3: Install on Airgap System

On the airgap system (Ubuntu 24.04):

# Navigate to bundle directory
cd /tmp/atlas-bundle

# Run installer with offline bundle
cd /path/to/atlas
sudo ./installer/install.sh --offline-bundle /tmp/atlas-bundle

Bundle Contents

The bundle includes:

Main Packages

• Build Tools: build-essential, git, curl, wget
• ZFS: zfsutils-linux, zfs-zed, zfs-initramfs
• Storage Services: samba, samba-common-bin, nfs-kernel-server, rpcbind
• iSCSI: targetcli-fb
• Database: sqlite3, libsqlite3-dev
• Go Compiler: golang-go
• Utilities: openssl, net-tools, iproute2

Dependencies

All transitive dependencies are automatically included.

Verification

Before transferring, verify the bundle:

# Count .deb files (should be 100-200)
find ./atlas-bundle -name "*.deb" | wc -l

# Check manifest
cat ./atlas-bundle/MANIFEST.txt

# Check total size
du -sh ./atlas-bundle

Troubleshooting

Missing Dependencies

If installation fails with dependency errors:

1. Ensure all .deb files are present in bundle
2. Check that bundle was created on Ubuntu 24.04
3. Verify system architecture matches (amd64/arm64)

Go Installation Issues

If Go is not found after installation:

1. Check if golang-go package is installed: dpkg -l | grep golang-go
2. If missing, the bundle includes go.tar.gz as fallback
3. Installer will automatically extract it if needed

Package Conflicts

If you encounter package conflicts:

# Fix broken packages
sudo apt-get install -f -y

# Or manually install specific packages
sudo dpkg -i /path/to/bundle/*.deb
sudo apt-get install -f -y

Bundle Maintenance

Updating Bundle

To update the bundle with newer packages:

1. Run ./installer/bundle-downloader.sh again on internet-connected system
2. This will download latest versions
3. Transfer new bundle to airgap system

Bundle Size Optimization

To reduce bundle size (optional):

# Remove unnecessary packages (be careful!)
# Only remove if you're certain they're not needed

Security Considerations

• Verify bundle integrity before transferring
• Use secure transfer methods (encrypted USB, secure network)
• Keep bundle in secure location on airgap system
• Verify package signatures if possible

Advanced Usage

Custom Bundle Location

# Download to custom location
sudo ./installer/bundle-downloader.sh /opt/atlas-bundles/ubuntu24.04

# Install from custom location
sudo ./installer/install.sh --offline-bundle /opt/atlas-bundles/ubuntu24.04

Partial Bundle (if some packages already installed)

If some packages are already installed on airgap system:

# Installer will skip already-installed packages
# Missing packages will be installed from bundle
sudo ./installer/install.sh --offline-bundle /path/to/bundle

Support

For issues with airgap installation:

1. Check installation logs
2. Verify bundle completeness
3. Ensure Ubuntu 24.04 compatibility
4. Review MANIFEST.txt for package list