Docker (manual)¶

This page covers the manual Docker install path — downloading the bundle, loading the image, hand-editing .env, and bringing the stack up with docker compose. It is meant for operators integrating EnforceGate vX with existing automation (Ansible, Terraform, Kubernetes-side tooling, custom CI pipelines) where the guided installer cannot be run.

Consider the appliance first

The container payload here is identical to the virtual appliance, but the appliance ships on a host OS that Exosys delivers, hardens, and patches; on the Docker path the host OS is yours to harden and maintain. For most environments — especially production deployments without a mature Linux-hardening baseline — the appliance is the recommended and supported path. Use the Docker bundle when you have an established CIS / STIG (or equivalent) baseline on the host and the operational discipline to keep it patched.

Use the installer if you can

For an interactive first-time install, the Docker installer is faster and harder to get wrong — it walks you through EULA acceptance, license credentials, network configuration and SSL inspection mode, then deploys the stack. The manual flow on this page is appropriate only when the wizard is impractical (no TTY, scripted provisioning, fleet management).

Prerequisites¶

Docker Engine 27 or newer
Docker Compose v2.x
Linux kernel 6.x or newer
Outbound HTTPS for license activation (specific endpoint provided with your license credentials — contact support for firewall coordination)

Downloading the bundle¶

Go to the Software Downloads Portal, select EnforceGate, then EnforceGate vX for Docker. Follow the link to download the standalone bundle archive.

Verify the cosign signature of the bundle against the Exosys release public key (the bundle ships the .pub and the signed docker-compose.yml together):

tar -xf enforcegate-vx-<version>-standalone.tar.gz
cd standalone-<version>

# Verify the compose manifest's signature
cosign verify-blob \
    --key exosys-release.pub \
    --signature docker-compose.yml.sig \
    --insecure-ignore-tlog \
    docker-compose.yml

The bundle directory contains:

standalone-<version>/
├── docker-compose.yml          # 3-service compose, image digests pinned (@sha256:...)
├── docker-compose.yml.sig      # cosign bundle (verify with exosys-release.pub)
├── .env.example                # operator-tunable knobs (copy to .env)
├── exosys-release.pub          # cosign pubkey for customer-side verification
├── VERSION                     # build metadata (version, build host, signer, timestamp)
├── image.tar.zst               # docker save | zstd of the standalone image
├── image.tar.zst.sig           # cosign bundle for the image tarball
├── installer/
│   └── bin/
│       └── enforcegate-host    # host-side operator CLI (the `eghost` binary)
└── README.md                   # customer-facing verify + deploy instructions

Loading the image¶

zstd -d image.tar.zst -o image.tar
docker load --input image.tar
docker images enforcegate/standalone

Installing the operator CLI¶

The eghost operator CLI is shipped in the bundle. Install it system-wide so any administrator on the host can drive the deployment:

sudo install -m 0755 installer/bin/enforcegate-host /usr/local/bin/enforcegate-host
sudo ln -sf /usr/local/bin/enforcegate-host /usr/local/bin/eghost
eghost --help

eghost is the recommended interface for every day-to-day operation (compose lifecycle, status, policy management, version, support bundle). Raw docker compose and docker exec still work for advanced use.

Configuring the bundle¶

cp .env.example .env
$EDITOR .env

Required values in .env for a production deployment:

Variable	Purpose
`ENGINE_LICENSE_SERIAL`	Per-deployment activation serial issued by Exosys.
`ENGINE_LICENSE_USERNAME`	Control-server account name authorised to bind this serial.
`ENGINE_LICENSE_PASSWORD`	Control-server account password.
`ENFORCEGATE_ADMIN_USERNAME`	First-boot admin user for the Control API (replaces the build-time default `admin`).
`ENFORCEGATE_ADMIN_PASSWORD`	First-boot admin password.
`ENFORCEGATE_ORG_NAME`	Legal entity name embedded in the bump CA `O=` field.
`ENFORCEGATE_CAPTIVE_HOSTNAME`	FQDN clients reach the portal at — drives the portal TLS leaf CN/SAN.
`ENFORCEGATE_CAPTIVE_SECRET_KEY`	Random 32+ char string for portal session-cookie signing.

Optional knobs include ENFORCEGATE_SSL_INSPECT (off / peek / bump), ENFORCEGATE_CAPTIVE_BASE_URL, ENFORCEGATE_CPUS, ENFORCEGATE_MEMORY, and the splice list ENFORCEGATE_SSL_INSPECT_SPLICE_DOMAINS. See the inline comments in .env.example for the complete set.

Starting the bundle¶

eghost up
eghost logs

(eghost up invokes docker compose up -d under the hood from the bundle directory; eghost logs follows the compose log stream.)

The first boot can take 60–120 seconds — the engine generates first-boot certificates and compiles the default policy. The container reports healthy once the engine and Squid are both listening.

Smoke-test¶

# One-screen deployment dashboard
eghost

# Detailed engine + sidecar health
eghost status

# Version of the CLI and every running container
eghost version

# A real request through the proxy
curl -x http://localhost:3128 https://www.exosys.ch -o /dev/null -w "%{http_code}\n"

If the curl returns 200, the default policy is permitting the request end-to-end. To explore the captive portal pathway, define a block or warn policy (policies) for a test domain and observe the redirect.

Upgrading¶

docker compose pull           # pull the new image tags
eghost up                     # roll the stack onto the new images

Operator state (configuration, license activation, policy history, audit log) is preserved across image upgrades because all four named volumes survive container removal. See persistence for the full upgrade model.