Offline installation and updates

Gluesync supports offline installation and updates for air-gapped environments where internet access is restricted or unavailable. This guide covers both the initial offline setup and subsequent offline update procedures.

When to use offline installation

Choose the offline installation path if:

Your environment has no internet access or strict outbound firewall policies
Your organization requires all artifacts to be staged internally before deployment
You need to deploy Gluesync in a secure, isolated network segment
You must follow change-control processes that mandate manual artifact validation

Offline installation process

Prerequisites for offline installation

Before proceeding with offline installation, ensure you have:

Container runtime pre-installed: Docker Engine and Docker Compose must already be installed on the target system. The offline installer does not install Docker.
Platform archive: A public gs-content Linux platform archive containing all required Docker images and Gluesync components. Download it from Get Gluesync – offline downloads.
Kit file: Your Gluesync kit file (<kit-id>-trial-kit.zip) matching your 32-character kit ID.
System resources: Minimum 4 CPU cores, 8 GB RAM, and 100 GB free disk space (200 GB recommended).
Root/sudo access: The installer requires elevated privileges to manage Docker and write to system directories.
Offline installer script: The docker-installer-linux-offline.sh script downloaded from MOLO17.

Ensure the following CLI tools are installed on the target host before running the offline installer: tar, unzip, gunzip, jq, and python3. The installer will exit if any of these commands are missing.

Unlike the default online installer, the offline installer assumes Docker is already present and operational. If you need Docker installation instructions for offline environments, refer to Install Docker.

Obtaining offline installation files

Download the Linux platform archive, kit file, and docker-installer-linux-offline.sh from an internet-connected system at Get Gluesync – offline downloads.

After you download the installer script, make it executable, then transfer all files to the target air-gapped system using your approved transfer method (USB drive, secure file transfer, etc.).

chmod +x docker-installer-linux-offline.sh

Running the offline Linux installer

The offline installer script is docker-installer-linux-offline.sh. Place it in the same directory as your platform archive and kit file.

Requirements for offline installation:

Docker and Docker Compose pre-installed: The offline installer does not install Docker. You must have Docker Engine and Docker Compose already installed and operational.
Platform archive: A gluesync-platform-linux-{arch}.tar.gz latest alias (for example gluesync-platform-linux-amd64.tar.gz) or the matching versioned file (for example gluesync-platform-linux-amd64-2.2.11.tar.gz).
Kit file: Your Gluesync kit file (<kit-id>-trial-kit.zip) matching your 32-character kit ID.
System resources: Minimum 4 CPU cores, 8 GB RAM, and 100 GB free disk space (200 GB recommended).
Root/sudo access: The installer requires elevated privileges to manage Docker and write to system directories.
1. Navigate to the directory containing the installer and archives
2. Run the installer with elevated privileges:
  sudo ./docker-installer-linux-offline.sh
3. Follow the on-screen prompts:
  - The installer displays a welcome banner and requirements summary
  - It performs local system checks (CPU, RAM, disk space) without internet access
  - It verifies Docker installation and daemon status
  - It validates the presence of the platform archive
  - It prompts for your 32-character kit ID
  - It validates the kit ID against local kit files
  - It extracts the platform archive and loads all Docker images
  - It copies Gluesync components to /opt/gluesync
  - It offers to start Gluesync immediately

What the offline installer does

The offline installer performs the following steps without requiring internet access:

System validation: Checks CPU cores (minimum 4 recommended), RAM (minimum 8 GB), and disk space (minimum 50 GB free)
Docker verification: Confirms Docker command availability, daemon status, and Docker Compose installation
Archive validation: Locates and validates the platform archive (.tar.gz latest alias or versioned filename)
Kit validation: Validates the provided kit ID format and matches it against local kit files
Image loading: Extracts the platform archive and loads all Docker images into the local Docker registry
Component installation: Copies Gluesync configuration files, scripts, and compose files to /opt/gluesync
Permission setup: Sets appropriate ownership and permissions for the installation directory
Startup option: Optionally starts Gluesync using the installed run.sh script

The offline installer does not install Docker or Docker Compose. You must ensure these are pre-installed and operational before running the offline installer. For Docker installation guidance, see Install Docker.

Installation location

The offline installer installs Gluesync to:

Linux: /opt/gluesync

All configuration files, Docker Compose definitions, and helper scripts (run.sh, stop.sh, update.sh) are placed in this directory.

Starting Gluesync after installation

If you chose not to start Gluesync during installation, you can start it manually:

cd /opt/gluesync
./run.sh

The Gluesync Control Plane will be available at https://<your-server-ip>; with default credentials admin/admin.

Offline updates

Gluesync supports offline updates to keep your air-gapped environment current without requiring internet access during the update process.

Obtaining offline update packages

Download the latest update package from an internet-connected system at Get Gluesync – offline downloads.

The update package is named update-<version>.tar.gz or update-<version>.zip
Transfer the update package to your Gluesync installation directory (/opt/gluesync)
Ensure the update file is placed in the same directory as update.sh

Running offline updates

The update.sh script automatically detects offline update packages:

Navigate to your Gluesync installation directory:
```
cd /opt/gluesync
```
Run the update script:
```
./update.sh
```
The script will:
- Detect the presence of update-.tar.gz or update-.zip files
- Display an "Offline Update File Detected" banner
- Prompt you to confirm loading the offline update
- Extract the update package to a temporary directory
- Load all Docker images from the update package
- Report success or failure for each image
- Clean up temporary files
- Prompt you to restart Gluesync to apply updates
After successful offline update, restart Gluesync:
```
./run.sh
```

What the offline update process does

The offline update process performs the following:

Detection: Automatically scans for update package files matching the pattern update-.tar.gz or update-.zip
Extraction: Extracts the update package to a temporary directory
Image loading: Loads all Docker images contained in the update package into the local Docker registry
Validation: Verifies each image loaded successfully
Cleanup: Removes temporary extraction files
Reporting: Provides a summary of loaded images and any failures

Offline updates only load new Docker images into your local registry. You must restart Gluesync to use the updated images. The update.sh script will prompt you to run ./run.sh after successful update.

Skipping offline updates

If you have an offline update file present but want to use the online update process instead (if internet access becomes available), you can decline the offline update prompt when running ./update.sh. The script will then attempt the standard online update via the MOLO17 API.

Troubleshooting offline installation and updates

Platform archive not found

Error: "Platform archive not found"
Cause: The platform archive is not in the same directory as the installer, or the filename does not match the public gs-content pattern
Solution: Place gluesync-platform-linux-{arch}.tar.gz (latest alias, for example gluesync-platform-linux-amd64.tar.gz) or the versioned form (for example gluesync-platform-linux-amd64-2.2.11.tar.gz) in the same directory as docker-installer-linux-offline.sh

Docker not installed

Error: "Docker is not installed or not in PATH"
Cause: Docker Engine is not installed on the target system
Solution: Install Docker and Docker Compose before running the offline installer. See Install Docker for guidance.

Kit ID validation failed

Error: "Invalid kit ID format" or "Kit ID does not match any local kit files"
Cause: The provided kit ID is not 32 hexadecimal characters, or the kit file is missing
Solution: Verify your kit ID from the download email and ensure the corresponding <kit-id>-trial-kit.zip file is present

Docker image load failed

Error: "Failed to load" for one or more Docker images
Cause: Corrupted archive file or insufficient disk space
Solution: Re-download the platform archive and verify its integrity. Ensure at least 50 GB free disk space.

Offline update package not detected

Error: Update script does not detect the offline update file
Cause: The update file is not named correctly or not in the Gluesync directory
Solution: Ensure the update file follows the naming pattern update-.tar.gz or update-.zip and is located in /opt/gluesync

Docker daemon not running

Error: "Docker daemon is not running"
Cause: Docker service is not started

Solution: Start Docker service:

sudo systemctl start docker

sudo service docker start

Comparison: Online vs. offline installation

Aspect Online installation Offline installation

Aspect	Online installation	Offline installation
Internet access	Required	Not required
Docker installation	Automatic	Manual (pre-installed required)
Platform artifacts	Downloaded during installation	Pre-downloaded and staged locally
System checks	Includes network connectivity tests	Local checks only
Use case	Standard deployments, trials, demos	Air-gapped environments, secure networks
Installer script	`docker-installer.sh`	`docker-installer-linux-offline.sh`

Internet access

Required

Not required

Docker installation

Automatic

Manual (pre-installed required)

Platform artifacts

Downloaded during installation

Pre-downloaded and staged locally

System checks

Includes network connectivity tests

Local checks only

Use case

Standard deployments, trials, demos

Air-gapped environments, secure networks

Installer script

docker-installer.sh

docker-installer-linux-offline.sh

Security considerations for offline environments

When deploying Gluesync in air-gapped environments:

Artifact integrity: Verify checksums of all downloaded files before transfer
Secure transfer: Use approved secure transfer methods for moving files to air-gapped systems
Access control: Restrict access to the Gluesync installation directory and Docker daemon
Audit trails: Maintain records of all file transfers and installation activities
Update management: Establish a process for regularly obtaining and transferring update packages

Additional resources

DIY deployment guides – Manual deployment references for advanced scenarios
Install Docker – Docker installation guidance for offline environments
Default installers – Recommended online installation method
System Requirements – Hardware and environment specifications