Install  /  Docker Compose

Install Veirox Connect via Docker Compose

Target: Any host running Docker Engine 24+ with Docker Compose v2.
Use this on hosts that have Docker but no systemd (Docker Desktop,
dev laptops, small VMs).

Prerequisites

  • Docker Engine 24+
  • Docker Compose v2 (docker compose, not legacy docker-compose)
  • Outbound TCP 443 to the Veirox backend
  • An Veirox enrollment token

Install

cd deploy/compose
cp .env.example .env
# Edit .env:
#   VEIROX_BACKEND_URL=https://veirox.customer.com
#   VEIROX_ENROLLMENT_TOKEN=veirox_enr_REPLACE_ME
docker compose up -d

Choosing an image tier

Edit .env and set VEIROX_CONNECTOR_TAG to one of:

  • 0.2.0-minimal (~25 MB) — alpine + binary. Good for shell-only.
  • 0.2.0-k8s (~90 MB) — adds kubectl + helm. Good for a host
    that needs to manage a kubeconfig-reachable cluster.
  • 0.2.0-cloud (~1.1 GB) — adds aws + gcloud + az. Good for
    cloud management hosts.

Corporate TLS proxy

# .env
VEIROX_CONNECTOR_EXTRA_CA_BUNDLE=/etc/corp-ca.pem
VEIROX_CONNECTOR_EXTRA_CA_BUNDLE_HOST=/etc/ssl/certs/corp-ca.pem

Then uncomment the bind-mount line in docker-compose.yml:

volumes:
  - ${VEIROX_CONNECTOR_EXTRA_CA_BUNDLE_HOST}:/etc/corp-ca.pem:ro

Forward proxy (HTTPS_PROXY)

# .env
HTTPS_PROXY=http://proxy.corp:3128
HTTP_PROXY=http://proxy.corp:3128
NO_PROXY=localhost,127.0.0.1

Verify

docker compose logs -f veirox-connector

Then run the verification checklist.

Upgrade

docker compose pull
docker compose up -d

The named volume veirox-connector-state persists the mTLS cert across
restarts, so no re-enrollment is needed.

See upgrade.md.

Uninstall

docker compose down
docker volume rm compose_veirox-connector-state

Then delete the connector in the Veirox UI.

Troubleshooting

Symptom Fix
backend URL is required .env is missing VEIROX_BACKEND_URL.
failed to load cert after upgrade The named volume may have been deleted. Re-run with a fresh enrollment token.
Container exits immediately with refusing to run as root You overrode user: in a compose override file. Remove it.
tls handshake failed in customer egress proxy Set VEIROX_CONNECTOR_EXTRA_CA_BUNDLE and bind-mount the CA file (see above).