Air-Gapped Installs

If the network you run your vendor's software on can't reach the internet, you can still install and update it. You bundle a release of the software on a machine that has internet access, carry the one file across, and load it into your own registry or Docker on the other side.

This works with releases: the versions your vendor has published. Each one lists the exact images and files that ship together. Find them on your license page, under Releases. The release page shows the notes, a pull command for every image (by digest, so you get exactly what was released), the files to download, and an Install without internet access panel.

The Install without internet access panel, and bundling with the CLI, are part of your vendor's Growth, Scale and Enterprise plans. If your vendor is on another plan the release page has no panel; the digest-pinned docker pull commands under Images still work for copying the images across by hand (see With Docker only).

The Breakwater CLI

The breakwater command line tool builds and loads bundles. It's open source at github.com/stympy/breakwater-cli.

The CLI is coming soon. The first release isn't out yet, so the commands below describe what it will do and aren't available to install today. Until then, use the Docker commands below. The release page starts offering the CLI download once it exists.

It's designed to sign in with a pull token (the same credentials as docker login), so you need a token from the Tokens page and an active license for the product.

Create a bundle

On a machine with internet access:

breakwater bundle create <product> <version>

For example, breakwater bundle create acme-server 2.4.1. The CLI fetches the release from Breakwater, pulls the release's images, keeping the platforms you choose of multi-platform ones, downloads the release's files, and writes one archive, <product>-<version>.bwbundle.tar. Images from your vendor come from the Breakwater registry; outside images, such as a public Postgres, come from their own registry.

Each time you bundle, Breakwater notes it for your vendor: the release, platforms, CLI version and size. That's how they know which versions offline customers have. It never includes the contents of the bundle.

Verify it

breakwater bundle verify <product>-<version>.bwbundle.tar

Run this after you carry the file across. It checks every image and file against the digests and checksums recorded in the release, so a damaged or tampered transfer is caught before you load anything.

Load it

On the air-gapped machine, either into Docker:

breakwater bundle load <product>-<version>.bwbundle.tar --docker

or into a registry you run:

breakwater bundle load <product>-<version>.bwbundle.tar --registry registry.internal.example.com/acme

--registry takes a host with an optional path prefix, and pushes every image there with all its platforms. The bundle's files, such as a Compose file or a Helm values file, still point at the original image names. Add --rewrite-files <dir> to write copies into <dir> with the image names changed to your registry's.

With Docker only

You don't need the CLI. On a machine with internet access, log in and run the commands from the release page's Install without internet access panel (shown on Growth, Scale and Enterprise plans). They look like this:

On other plans, run docker pull for each image from the Images section of the release page instead, then docker save them together yourself. The commands in the panel are:

docker login registry.breakwaterapp.com -u your_username
docker pull registry.breakwaterapp.com/acme/server@sha256:...
docker tag registry.breakwaterapp.com/acme/server@sha256:... registry.breakwaterapp.com/acme/server:2.4.1
docker pull docker.io/library/postgres:16.4@sha256:...
docker tag docker.io/library/postgres:16.4@sha256:... docker.io/library/postgres:16.4
docker save -o acme-server-2.4.1.tar registry.breakwaterapp.com/acme/server:2.4.1 docker.io/library/postgres:16.4

Carry acme-server-2.4.1.tar across and run docker load -i acme-server-2.4.1.tar. Download the release's files from the release page and carry them too.

The commands pull by digest, so you get the released images even if a tag has since moved. The fallback is simpler but has limits:

It keeps one architecture, the one of the machine that pulls. Pull on a machine of the same architecture as the one you'll run on.
It doesn't verify the transfer. Compare checksums yourself, for the files against the SHA-256 shown on the release page.
It loads into Docker, not into a registry, and doesn't change image names in the release's files.

Updating

Bundle each new release the same way and load it next to the old one. Your vendor sees each bundle you make, so they know which version you're moving to.