yeke.io · docs

Air-gap installation

Choose how to access YEKE images: pull from Docker Hub, use an internal registry, or install from an offline bundle.

Three paths, at a glance

Two are mechanisms that already exist; the third needs a separate package.

Path	When
1. Regular install	For most organizations with internet access during setup (through a proxy/allowlist if needed). Image tags are pulled directly from Docker Hub.
2. Internal registry mirror	For organizations running their own internal Docker registry. No package needed, it works with two environment variables.
3. Fully offline package	Rare. For installs with a fully closed network, hand-delivered: a single signed archive.

Path 1: Regular install

The path this site's own installation page already covers.

If the installation can reach the internet, pull images from Docker Hub. Use your corporate proxy or allowlist if needed. No additional registry configuration is required for Docker Compose or the Kubernetes manifests.

Path 2: Internal registry mirror

If you run your own internal Docker registry, two environment variables.

Push the agent and toolbox images to your internal registry, then set YEKE_AGENT_IMAGE and YEKE_TOOLBOX_IMAGE to their addresses. YEKE uses these images in agent manifests and Shell sessions. Empty values use Docker Hub; no separate bundle is needed.

# from the nairotech/yeke-agent repo
docker buildx build --platform linux/amd64,linux/arm64 \
  -t registry.internal.example.com/yeke-agent:0.51.2 --push .

# from apps/toolbox
docker buildx build --platform linux/amd64,linux/arm64 \
  -t registry.internal.example.com/yeke-toolbox:v3 --push .

In docker-compose, add these to the core service's environment: block; the file doesn't carry these two lines by default, they're optional and added by hand:

    environment:
      YEKE_AGENT_IMAGE: registry.internal.example.com/yeke-agent:0.51.2
      YEKE_TOOLBOX_IMAGE: registry.internal.example.com/yeke-toolbox:v3

On Kubernetes, add the same two variables to the env: list in deploy/kubernetes/02-core-deployment.yaml; same mechanism, just a different file format. Core's own image is unaffected by this path; it's still pulled with a normal docker pull/imagePullPolicy: Always — only where agent/toolbox are pulled from changes.

The most commonly missed step

Core's own location gets confused with agent/toolbox's location.

Even if core runs on one machine, the agent and toolbox images still need to live in a registry the cluster can reach

The target cluster’s nodes pull agent and toolbox images, not the YEKE server. Even when core runs on one machine, those nodes need access to the registry. Missing images or incorrect image addresses can cause agent installation or Shell startup to fail with ImagePullBackOff.

Path 3: Fully offline package

Rare. For organizations with a completely closed network and a hand-delivered (physical file) install; most organizations reach either the internet directly or their own internal mirror, so path 1 or path 2 is enough.

yeke-airgap-<version>.tar is a single archive derived from published images — not a local rebuild, so the byte the package carries is the byte the release verified.

Part	What
`images/`	core+agent+toolbox, a multi-arch OCI archive for the Kubernetes path; core's single-arch `docker load` format for the compose path (default is `amd64` only).
`cli/`	The single-file `yeke` CLI and the `yeke-migrate` bundle.
`deploy/`	compose + Kubernetes manifests, image fields pinned to this version, registry name templated.
`docs/INSTALL.md`, `UPGRADE.md`	Install and upgrade steps: in English, since the reader is the customer's operator.
`SHA256SUMS` + `.sig`	An Ed25519 signature, separate from the license key, signed with the vendor's own release key.

Verify before installing anything

The package signature verifies the publisher of the archive and is separate from the license key. Compare the bundled public key with the key published through an independent channel. Do not rely only on a key supplied inside the archive.

sha256sum -c SHA256SUMS
openssl pkeyutl -verify -pubin -inkey release-public.pem \
  -rawin -in SHA256SUMS -sigfile SHA256SUMS.sig

Installing — single machine (compose)

The core image is loaded straight into the local Docker daemon; no internal registry or skopeo needed:

docker load < images/yeke-<version>-amd64.docker.tar   # or …-arm64.docker.tar

Even after this load, the warning above still applies: you still need to push the agent and toolbox images to your internal registry with skopeo copy (the commands in the Kubernetes section below).

Installing — Kubernetes (persistent cluster)

Kubernetes nodes pull from a registry, not from a tar file — you load the images into your internal registry first:

REGISTRY=registry.internal.example.com

# only if core itself will also run on Kubernetes (not needed for compose):
skopeo copy --multi-arch all \
  oci-archive:images/yeke-<version>.oci.tar \
  docker://$REGISTRY/yeke:<version>

# needed for every install:
skopeo copy --multi-arch all \
  oci-archive:images/yeke-agent-<version>.oci.tar \
  docker://$REGISTRY/yeke-agent:<version>

skopeo copy --multi-arch all \
  oci-archive:images/yeke-toolbox-<tag>.oci.tar \
  docker://$REGISTRY/yeke-toolbox:<tag>

Architecture selection

The package is a hand-delivered process prepared at sale time — the customer's machine architecture is usually already known when the package is built. That's why the default package carries only amd64; if arm64 or both are needed, the package is rebuilt with --arch arm64 / --arch both. The Kubernetes path's multi-arch OCI archive is unaffected by this choice — since cluster nodes can be mixed-architecture, that archive always carries both.

Limits

No step reaches an outside network.

License verification is fully offline. The product contacts no external address for licensing.
The package is rarely needed. An acceptance run (an end-to-end install on a real air-gapped machine) is done when the packaging mechanism changes, not on every release.
Rebuilding the toolbox inside the package is not supported. The package carries a ready-made image; customers don't build it on their own.
Upgrading also requires a new version of the same package. Manually building an image or partial updates are not supported.
If core's certificate is signed by your organization's own CA, the agent, Shell and CLI trusting it is a separate step — see Internal CA.

Outgrown the database after installing?

An air-gapped install can also move to PostgreSQL; the path is the same yeke-migrate tool.

Installation Database migration