Search docs.molo17.com

    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.

    1. Download gluesync-platform-windows-amd64.tar.gz and your <kit ID>-trial-kit.zip kit file from Get Gluesync – offline downloads, and gluesync-windows-setup-wizard.msi from the Windows setup wizard page. Copy them to the server.

    2. Run the MSI as administrator and choose From files on this server.

    3. 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.ps1 script 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 tar) are available on the target host before running the offline installer. The installer will exit if it cannot extract the required archives.

    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.gz latest alias (for example gluesync-platform-windows-amd64.tar.gz) or the matching versioned file (for example gluesync-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.

      1. Open PowerShell as Administrator and navigate to the directory containing the installer and archives.

      2. Run the installer:

        .\docker-installer-windows-offline.ps1
      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 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.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 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.

    1. The update package is named gluesync-update-windows-amd64-<version>.tar.gz.

    2. 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:

    1. Checks every file of the package against its manifest before it changes anything.

    2. Backs up docker-compose.yml and .env to %ProgramData%\MOLO17\Gluesync\backups.

    3. Loads the Docker images of the package into the local Docker registry.

    4. Updates the image tags in docker-compose.yml and restarts Gluesync.

    5. 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 example gluesync-platform-windows-amd64.tar.gz) or the versioned form (for example gluesync-platform-windows-amd64-2.2.11.tar.gz) in the same directory as docker-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.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 refused

    • Error: gluesync update --package stops with a GS-UPD code, for example GS-UPD-012, GS-UPD-013 or GS-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 pattern update-*.tar.gz or update-*.zip and is located in C:\Program Files\Gluesync.

    Docker daemon not running

    • Error: "Docker daemon is not running".

    • Cause: Docker service is not started.

    • Solution: Start Docker service via PowerShell:

      Start-Service docker

    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

    gluesync-windows-setup-wizard.msi (or docker-installer-windows.ps1)

    gluesync-windows-setup-wizard.msi with From files on this server (or docker-installer-windows-offline.ps1)

    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