Offline installation and updates (Windows)
Gluesync supports offline installation and updates for air-gapped environments where internet access is restricted or unavailable.
This guide covers the initial offline setup and subsequent offline update procedures specifically for Windows Server systems. To install offline, use the Windows setup wizard. The PowerShell offline script (docker-installer-windows-offline.ps1) is the alternative.
|
How-to guide
For a step-by-step walkthrough tested on a running Gluesync, see the how-to guide Install and run Gluesync on Windows Server. |
| Offline install and offline update need Windows Server 2022 or later. The offline packages carry Windows Server 2022 images only, so an offline install on Windows Server 2019 stops with GS-RUN-106 and an offline update with GS-UPD-024. On Windows Server 2019, use the online install and the online update. |
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 with the setup wizard
The Windows setup wizard installs Gluesync from the offline platform package and your kit zip, with no download and no Docker installation beforehand. The package carries the Docker engine, Docker Compose and the platform images.
-
Download
gluesync-platform-windows-amd64.tar.gzand your<kit ID>-trial-kit.zipkit file from Get Gluesync – offline downloads, andgluesync-windows-setup-wizard.msifrom the Windows setup wizard page. Copy them to the server. -
Run the MSI as administrator and choose From files on this server.
-
After Finish (and the restart, if Windows needs one), the Gluesync window opens. Choose the package and the kit file, then click Install.
For the details, the unattended install (GLUESYNC_SOURCE=offline) and the error codes, see Install without internet access.
When the install is complete, use Gluesync Control to manage Gluesync: the Gluesync Control desktop shortcut opens the window, and the install folder is on the system PATH, so gluesync status, gluesync stop, gluesync run and gluesync update work from an elevated terminal.
Offline installation with the PowerShell script
Use the script when you prefer a console install or Docker is already installed and managed by your team.
Prerequisites for offline installation
Before proceeding with offline installation, ensure you have:
-
Container runtime pre-installed: Docker Engine for Windows Containers and Docker Compose must already be installed on the target system. The offline installer does not install Docker.
-
Platform archive: A public gs-content Windows 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. -
System resources: Minimum 4 CPU cores, 8 GB RAM, and 100 GB free disk space (200 GB recommended).
-
Administrator access: The installer requires an elevated PowerShell session (Run as Administrator) to manage Docker and write to system directories.
-
Offline installer script: The
docker-installer-windows-offline.ps1script downloaded from MOLO17. -
Security software exclusions: If the host runs antivirus or EDR software, such as Microsoft Defender or Elastic Defend, the exclusions described in Prepare antivirus and EDR software are in place.
|
Ensure the necessary extraction tools (like native Windows extraction features or |
| 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 Windows platform archive, kit file, and docker-installer-windows-offline.ps1 from an internet-connected system at Get Gluesync – offline downloads. Then transfer all files to the target air-gapped system using your approved transfer method (USB drive, secure file transfer, etc.).
Running the offline Windows installer
The offline installer script is docker-installer-windows-offline.ps1.
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-windows-{arch}.tar.gzlatest alias (for examplegluesync-platform-windows-amd64.tar.gz) or the matching versioned file (for examplegluesync-platform-windows-amd64-2.2.11.tar.gz). -
Kit file: Your Gluesync kit file (
<kit-id>-trial-kit.zip) matching your 12-character kit ID. -
System resources: Minimum 4 CPU cores, 8 GB RAM, and 100 GB free disk space (200 GB recommended).
-
Administrator access: The installer requires elevated privileges to manage Docker and write to system directories.
-
Open PowerShell as Administrator and navigate to the directory containing the installer and archives.
-
Run the installer:
.\docker-installer-windows-offline.ps1 -
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 12-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
C:\Program Files\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.gzlatest 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
C:\Program Files\Gluesync. -
Permission setup: Sets appropriate ownership and permissions for the installation directory.
-
Startup option: Optionally starts Gluesync with the start helper of the kit.
|
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:
-
Windows:
C:\Program Files\Gluesync
All configuration files, Docker Compose definitions, and helper tools of the kit are placed in this directory.
Starting Gluesync after installation
If you chose not to start Gluesync during installation, you can start it manually. With Gluesync Control (setup wizard 1.4.0 or later), from an elevated terminal:
gluesync run
If the server has no Gluesync Control (an install made before setup wizard 1.4.0), use the script of the kit:
cd "C:\Program Files\Gluesync"
.\run.ps1
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. Offline updates are done with Gluesync Control, the gluesync command line of Windows setup wizard 1.4.0 and later.
Offline install and offline update need Windows Server 2022 or later. The offline packages carry Windows Server 2022 images only. On Windows Server 2019, gluesync update --package stops with GS-UPD-024. Use the online update on Windows Server 2019.
|
Obtaining offline update packages
Download the latest update package from an internet-connected system at Get Gluesync – offline downloads.
-
The update package is named
gluesync-update-windows-amd64-<version>.tar.gz. -
Transfer the update package to the server, to any folder (for example
C:\Temp).
Running offline updates
Run the update from an elevated terminal on the server:
gluesync update --package C:\Temp\gluesync-update-windows-amd64-<version>.tar.gz
To see the plan without changing anything, add --dry-run. To skip the confirmation, add -y. In the Gluesync Control window, use Update from file… on the Update tab.
Gluesync Control then:
-
Checks every file of the package against its manifest before it changes anything.
-
Backs up
docker-compose.ymland.envto%ProgramData%\MOLO17\Gluesync\backups. -
Loads the Docker images of the package into the local Docker registry.
-
Updates the image tags in
docker-compose.ymland restarts Gluesync. -
Checks that every service is running and that Core Hub runs the new version.
If a step fails after the compose file was changed, or you stop the update, the backed up files are restored and the previous version starts again. Core Hub migrates its database when it starts with a newer version, and that migration is one-way: a rollback restores the images and the configuration files, not the database. A package for an older version, or for the installed version, is refused, and so is a package that has no image for an agent you have installed.
The offline update restarts Gluesync as part of the update. You do not run gluesync run afterwards.
|
Offline updates on installs made before setup wizard 1.4.0
Installs made with an earlier setup wizard keep their update.ps1 script. If you have not installed setup wizard 1.4.0 or later on the server, put the update-<version>.tar.gz (or .zip) package in the Gluesync installation directory (C:\Program Files\Gluesync), run .\update.ps1 from an elevated PowerShell, confirm the offline update when the script detects the file, then restart Gluesync with .\run.ps1. To use the online update instead, decline the offline update prompt.
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-windows-{arch}.tar.gz(latest alias, for examplegluesync-platform-windows-amd64.tar.gz) or the versioned form (for examplegluesync-platform-windows-amd64-2.2.11.tar.gz) in the same directory asdocker-installer-windows-offline.ps1.
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.zipfile 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 refused
-
Error:
gluesync update --packagestops with aGS-UPDcode, for exampleGS-UPD-012,GS-UPD-013orGS-UPD-024. -
Cause: The package is damaged or cut short, is for another Windows version, is older than the installed version, or the server is Windows Server 2019.
-
Solution: Use the package exactly as downloaded, copy it again if its size differs from the download page, and see Update codes (GS-UPD) for the code. On installs made before setup wizard 1.4.0 that update with
update.ps1, ensure the update file follows the naming patternupdate-*.tar.gzorupdate-*.zipand is located inC:\Program Files\Gluesync.
Comparison: Online vs. offline installation
| Aspect | Online installation | Offline installation |
|---|---|---|
Internet access |
Required |
Not required |
Docker installation |
Automatic |
Manual (pre-installed required) with the script; carried by the package with the setup wizard |
Windows Server version |
2019, 2022 and 2025 |
2022 or later |
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 |
|
|
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.