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.
|
How-to guides
For step-by-step walkthroughs tested on a running Gluesync, see the how-to guides Install Gluesync on Linux and size the host and Upgrade Gluesync safely. |
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
From installer 2.0 (Gluesync Control 1.4.5), the offline install is part of gluesync install, the installer inside Gluesync Control for Linux. docker-installer-linux-offline.sh is only the way in: it finds your files and runs gluesync install --offline.
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 and running on the target system. The offline installer does not install Docker. It stops at once, before anything changes, when Docker is missing (
GS-RUN-102, exit code83). To run Gluesync on Podman instead, Podman 4.9 or later and Docker Compose v2 must be installed, and you add--runtime podman: see Offline install with Podman. To run Gluesync as a Docker Swarm stack, Docker Engine must be installed and running (Compose is not needed), and you add--runtime swarm: see Gluesync on Docker Swarm. The images are loaded on the server you run the installer on, so load them on the other nodes of a multi-node swarm too. -
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 12-character kit ID. -
Gluesync Control: the
gluesync-linux-<arch>file for the CPU of the server (amd64orarm64). Kits made from October 2026 contain it, and the offline script takes it from the kit. With an older kit, download it once fromhttps://molo17.com/gs-content/utils/gluesync-linux-<arch>and put it next to the script. -
System resources: Minimum 4 CPU cores, 8 GB RAM, 250 GB for the install folder and 50 GB for Docker (recommended). The installer blocks below 80 GB on the install folder and below 30 GB on Docker’s data-root and containerd’s root (added up when they share a disk, plus a 10 GB swap file on
/when the server has less than 10 GB of swap), and warns below the recommendation, see Low disk space on Linux. -
Root/sudo access: The installer requires elevated privileges to manage Docker and write to system directories.
-
Offline installer script: The
docker-installer-linux-offline.shscript downloaded from MOLO17.
The offline install needs no tools beyond what the server has: gluesync install reads the package and the kit itself. tar, unzip, gunzip, jq and python3 are not required.
| 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
Place docker-installer-linux-offline.sh in the same directory as your platform archive and kit file. The script looks for these files next to itself:
-
Platform archive:
gluesync-platform-linux-{arch}.tar.gz(the latest alias, for examplegluesync-platform-linux-amd64.tar.gz) or a versioned file (for examplegluesync-platform-linux-amd64-2.3.0.1.tar.gz). With several versioned files for the CPU, the newest name wins. -
Kit file: exactly one
*-trial-kit.zip. -
Gluesync Control:
gluesync-linux-{arch}, from the same directory or, failing that, from the kit.-
Navigate to the directory containing the installer and archives
-
Run the installer with elevated privileges:
sudo ./docker-installer-linux-offline.sh -
In a terminal, a guided screen opens:
-
Welcome: what is going to happen and the server it found
-
How do you want Gluesync to be installed?: choose Offline (meant for air-gapped environments). The next screen asks for the platform archive and the kit file, filled in with the files found next to the program. Tab walks through the candidates, each described as the Gluesync version of the package or the kit ID of the kit
-
Checks: the checks that need no network (CPU, RAM, disk space, ports 80 and 443, see GS-PRE-040) and Docker. A soft block can be accepted after a confirmation. A hard block, such as Docker missing, only offers Quit
-
Docker: the Docker that was found. It is left as it is
-
Ready to install: start Gluesync when done, and the daily automatic update of Gluesync Control
-
Installing Gluesync: the images are loaded and the kit is installed, with a progress bar and the output
-
Done: the address of the Control Plane and the install folder. A failed install shows the code, what to try and the log file
-
-
Without a terminal (a script, cloud-init, ssh without a tty), nothing is asked: the script gives the files it found to the installer, and Gluesync is not started unless you set
GLUESYNC_START=y:sudo GLUESYNC_START=y ./docker-installer-linux-offline.sh
-
You can also run the installer directly with explicit files, from any directory:
sudo gluesync install --offline --package gluesync-platform-linux-amd64-2.3.0.1.tar.gz --kit-file a1b2c3d4e5f6-trial-kit.zip
The options (--start, --accept, --folder, -y) and variables (GLUESYNC_START, GLUESYNC_ACCEPT, GLUESYNC_CONTROL_AUTO_UPDATE, GLUESYNC_NONINTERACTIVE) are described in Install Gluesync. When Gluesync is already installed in /opt/gluesync, the installer offers an update instead: from a package file in a terminal, or with --package unattended (see Offline updates).
What the offline installer does
The offline installer performs the following steps without requiring internet access:
-
Docker verification: Confirms that Docker and Docker Compose are installed and running, before anything changes
-
System validation: Checks CPU cores (minimum 4), RAM and disk space (blocks below 30 GB free on Docker’s data-root and containerd’s root and below 80 GB on the install folder, and warns below 50 GB and 250 GB) and ports 80 and 443
-
Docker configuration: Sets the Docker log settings for Gluesync in
/etc/docker/daemon.json(your other settings are kept, and the previous file is saved asdaemon.json.backup), makes sure Docker starts at boot, and adds the user who ransudoto thedockergroup -
Package and kit validation: Reads the whole platform archive once and checks it, and checks the kit
-
Image loading: Loads every Docker image of the platform archive into the local Docker registry. Nothing is unpacked to disk
-
Component installation: Copies the kit into
/opt/gluesyncand points its compose file to the loaded images. Nothing that is already in the folder is removed -
Gluesync Control: Installs it in
/opt/gluesyncand on thePATH(gluesync), and asks about its daily automatic update -
Startup option: Optionally starts Gluesync
An offline install sends no information to MOLO17.
|
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 and Docker Compose definitions are placed in this directory. gluesync is on the PATH, and manages the installation: gluesync start, gluesync stop, gluesync update and gluesync collect-logs.
Starting Gluesync after installation
If you chose not to start Gluesync during installation, you can start it manually:
sudo gluesync start
The Gluesync Control Plane will be available at https://<your-server-ip> with default credentials admin/admin.
An installation made with an earlier installer (1.3.6 or older) also has the scripts of its kit in /opt/gluesync (./run.sh, ./stop.sh, ./update.sh, ./collect-logs.sh), and they keep working.
|
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 update package for the CPU of the server from an internet-connected system at Get Gluesync – offline downloads.
-
The update package is named
gluesync-update-linux-<arch>-<version>.tar.gz -
Transfer the update package to the server with your approved transfer method
Running offline updates
Run gluesync update with the package:
sudo gluesync update --package /tmp/gluesync-update-linux-amd64-<version>.tar.gz
Add --dry-run to see the plan without changing anything, and -y to skip the questions. gluesync update then:
-
Reads the whole update package once, before anything changes, and refuses it when it is damaged, for another CPU or platform, or not newer than the installed version
-
Loads all Docker images from the update package with
docker load, one by one, and reports success or failure for each image -
Backs up
docker-compose.ymland.env, switches the compose file to the new images and restarts Gluesync -
Verifies that the services run the new version and, on failure, restores the previous version
The same update is available from the terminal screen (sudo gluesync, Update, Update from a package file), and from the installer: sudo gluesync install on a server where Gluesync is installed offers Update from a package file, and sudo gluesync install --package <file> --unattended runs the update without questions. See Update Gluesync for the options and the exit codes.
What the offline update process does
The offline update process performs the following:
-
Validation: Checks the package before anything changes, and the free space on the Docker data folder
-
Image loading: Loads all Docker images contained in the update package into the local Docker registry, without unpacking the package to disk
-
Restart: Backs up the configuration, restarts Gluesync with the new images and checks it. On failure it goes back to the previous version
-
Reporting: Provides a summary of the update and of any failure
Installations made with an earlier installer (1.3.6 or older) also have ./update.sh in /opt/gluesync, which detects an update-*.tar.gz or update-*.zip file next to it and loads its images. The restart then comes from ./run.sh.
|
Troubleshooting offline installation and updates
Platform archive or kit not found
-
Error: a warning from the script that the platform archive or the kit was not found, then the question of the screen (or, without a terminal, a stop)
-
Cause: The platform archive or the kit is not in the same directory as the script, or the filename does not match the public gs-content pattern
-
Solution: Place
gluesync-platform-linux-{arch}.tar.gz(latest alias, for examplegluesync-platform-linux-amd64.tar.gz) or the versioned form (for examplegluesync-platform-linux-amd64-2.3.0.1.tar.gz) and the<kit-id>-trial-kit.zipfile in the same directory asdocker-installer-linux-offline.sh, or choose the files on the screen, or give them with--packageand--kit-file
Gluesync Control file not found
-
Error: the script says to download the
gluesync-linux-{arch}file once -
Cause: The kit is older than October 2026 and has no Gluesync Control file, and none is next to the script
-
Solution: On a connected computer, download
https://molo17.com/gs-content/utils/gluesync-linux-{arch}for the CPU of the server and put it next to the script
Docker not installed
-
Error:
GS-RUN-102 OFFLINE_NO_DOCKER_ENGINE(exit code83) -
Cause: Docker Engine or Docker Compose is not installed on the target system, or Docker is Podman (
podman-docker). With--runtime podman, Podman or Docker Compose v2 is missing. With--runtime swarm, Docker is missing or not running. -
Solution: Install Docker and Docker Compose before running the offline installer. See Install Docker for guidance. For Podman, install Podman 4.9 or later and Docker Compose v2, then run the installer with
--runtime podman: see Offline install with Podman.
Kit ID validation failed
-
Error:
GS-PRE-030 KIT_ID_INVALID(exit code26), orGS-RUN-105 OFFLINE_KIT_INVALID(exit code86) -
Cause: The kit ID is not 12 hexadecimal characters, or the kit file is missing, is not a zip or has no
gluesync-dockerfolder -
Solution: Verify your kit ID from the download email and ensure the corresponding
<kit-id>-trial-kit.zipfile is present and complete
Ports in use
-
Error:
GS-PRE-040 PORTS_IN_USE -
Cause: Port 80 or 443 is used by something that is not an existing Gluesync install
-
Solution: Stop the program that uses the port, or accept the code as a warning (Accept and continue on the screen, or
GLUESYNC_ACCEPT=GS-PRE-040or--accept GS-PRE-040). See GS-PRE-040.
Docker image load failed
-
Error:
GS-RUN-104 OFFLINE_IMAGE_LOAD_FAILED(exit code85),GS-RUN-100 OFFLINE_PACKAGE_UNREADABLE(81) orGS-RUN-101 OFFLINE_PACKAGE_CORRUPT(82) -
Cause: Corrupted archive file, an archive that was cut short, or insufficient disk space
-
Solution: Re-download the platform archive and verify its integrity. Ensure enough free disk space (the installer blocks below 80 GB on the install folder and below 30 GB for Docker), and that the Docker daemon is running.
Offline update package not detected
-
Error:
gluesync update --packagerefuses the package before anything changes (GS-UPD-014, exit code214, for a package of another platform or CPU) -
Cause: The package is a Windows package, is for the other CPU, carries only Core Hub of another variant, or is not newer than the installed version
-
Solution: Download the
gluesync-update-linux-<arch>-<version>.tar.gzpackage for the CPU of the server, and a version newer than the installed one. See Installer error codes and troubleshooting.
Comparison: Online vs. 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 |
|
|
Installer |
|
|
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