Install without internet access

A normal install builds its images on the server, which needs internet access. On an air-gapped network, use the offline bundle instead. It is the normal bundle plus prebuilt container images, so the server pulls and builds nothing.

What is in the offline bundle#

The file is named gardience-X.Y.Z-offline-ARCH.tar.gz, where ARCH is amd64 or arm64. It comes with a .sha256 checksum file and, for a signed release, a .sha256.sig signature file.

It unpacks to a folder named gardience that holds everything in the normal bundle, plus:

The bundle's architecture must match the server. The installer checks this and stops if, for example, you use an arm64 bundle on an amd64 server.

Install from the offline bundle#

You still need Docker Engine 24 or newer with Docker Compose v2, openssl and curl on the server. Install them from your own internal sources first.

To install:

1. Copy the offline bundle and its .sha256 file to the server, and check it:

   Copy

   sha256sum -c gardience-X.Y.Z-offline-amd64.tar.gz.sha256

2. Extract it in a folder where it can stay:

   Copy

   sudo mkdir -p /opt/gardience-release
   sudo tar xzf gardience-X.Y.Z-offline-amd64.tar.gz -C /opt/gardience-release
   cd /opt/gardience-release/gardience

3. Run the installer with the same options as a normal install. For example:

   Copy

   sudo ./install/install.sh \
     --hostname gardience.example.internal \
     --fleet-size 1000 \
     --license /path/to/gardience-license.json \
     --backup-passphrase-file /root/.gardience-backup-pass

   The installer finds the images folder and prints loading prebuilt images (offline bundle) instead of building. Every option on Install on one server works the same way, including --attach for attach mode.

4. Sign in and check the install as described in Install on one server.

What the installer changes for an offline install#

So that an offline install can never reach for the internet by accident, the installer changes the generated compose.yml:

• It removes every build: line, so nothing is built.
• It points the web front end at the loaded gardience/nginx:offline image.
• It adds pull_policy: never to every service, so Docker Compose fails loudly instead of trying to pull an image.

Backups and restores also work offline: the gardience command runs them in the Gardience image that is already on the server.

Agents on an air-gapped network#

The agent installers in the console and the enrollment playbook download Salt from the internet:

• Linux: the Salt bootstrap script from github.com, which then installs the Salt packages.
• Windows: the Salt installer (Salt-Minion-3008.3-Py3-AMD64.msi) from packages.broadcom.com.

On an air-gapped network, copy those files to an internal web server and change the download URLs in the commands or in the downloaded playbook to point at it. The checksum checks still pass because the files are the same. Linux machines also need the Salt 3008.3 packages from an internal mirror of the Salt package repository, or installed by your own software distribution tools.

Upgrade an offline install#

Use the offline bundle of the new release with the normal upgrade command. Put its .sha256 and .sha256.sig files next to it, and give the full path:

sudo /opt/gardience/gardience upgrade /root/gardience-X.Y.Z-offline-amd64.tar.gz --check
sudo /opt/gardience/gardience upgrade /root/gardience-X.Y.Z-offline-amd64.tar.gz

The upgrade loads the new images instead of building them, after checking the architecture. See Upgrade for the full process.

Build an offline bundle#

Gardience publishes offline bundles for amd64 and arm64. If you build from the Gardience source tree, tools/make-offline.sh makes one on a machine that has internet access and Docker with buildx:

tools/make-offline.sh 1.2.1 amd64

The version is required. The architecture is amd64 (the default) or arm64. The script writes build/gardience-VERSION-offline-ARCH.tar.gz and its .sha256 file, plus a copy of the bill of materials in build/sbom-VERSION/. It signs the checksum (the .sha256.sig file) only when the RELEASE_SIGNING_KEY environment variable names a signing key file. gardience upgrade refuses a bundle without a valid signature, so an unsigned bundle can be used for a first install but not for an upgrade.

Related#

• Install on one server
• Requirements
• Upgrade
• Enroll Linux machines