Wardengate

Install

Installation

Wardengate ships as a Linux package, an OCI container, and a Helm chart. Pick the install path that matches how you already run stateful platform services — there is no benefit to introducing a new operational model just for the gateway.

Requirements

The minimum viable deployment runs on two small VMs plus a managed Postgres. For production, plan for horizontal scaling of both the control plane and the gateway.

  • Linux kernel 5.10 or newer, x86_64 or arm64. Tested on Ubuntu 22.04+, Debian 12+, RHEL 9+, Rocky 9+, Amazon Linux 2023.
  • PostgreSQL 14 or newer for the control plane state store. RDS, Cloud SQL, and Crunchy Postgres Operator are all supported.
  • S3-compatible object storage for session recordings. Enable object-lock or bucket versioning for tamper evidence.
  • A Layer-4 load balancer in front of gateways that preserves client IP (PROXY protocol v2 or TCP pass-through).
  • A TLS certificate for the user-facing hostname, issued by a CA your operators trust.

Install on Linux (packages)

Add the Wardengate repository and install the wardengate-controlplane and wardengate-gateway packages on the nodes that will run each role. On a single-box trial it is fine to install both on the same host.

Debian / Ubuntu

curl -fsSL https://pkg.wardengate.example/apt/gpg.key \
  | sudo gpg --dearmor -o /usr/share/keyrings/wardengate.gpg

echo "deb [signed-by=/usr/share/keyrings/wardengate.gpg] \
  https://pkg.wardengate.example/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/wardengate.list

sudo apt update
sudo apt install -y wardengate-controlplane wardengate-gateway

RHEL / Rocky / Amazon Linux

sudo tee /etc/yum.repos.d/wardengate.repo <<'EOF'
[wardengate]
name=Wardengate
baseurl=https://pkg.wardengate.example/rpm/el9/
gpgcheck=1
gpgkey=https://pkg.wardengate.example/rpm/gpg.key
enabled=1
EOF

sudo yum install -y wardengate-controlplane wardengate-gateway

Install with Docker

The container images are suitable for small teams, lab deployments, and running a gateway inside a VPC where a Kubernetes install is overkill. Run the control plane with a persistent volume for config and point it at an external Postgres.

docker run -d --name wg-controlplane \
  --restart unless-stopped \
  -p 8443:8443 \
  -v /etc/wardengate:/etc/wardengate \
  -e WG_DATABASE_URL="postgres://wg:****@db.internal:5432/wardengate" \
  -e WG_STORAGE_BUCKET="s3://wg-recordings" \
  ghcr.io/wardengate/controlplane:1.6

docker run -d --name wg-gateway \
  --restart unless-stopped \
  -p 443:443 -p 2222:2222 \
  -e WG_CONTROLPLANE_URL="https://controlplane.internal:8443" \
  -e WG_BOOTSTRAP_TOKEN="$(cat /etc/wardengate/bootstrap.token)" \
  ghcr.io/wardengate/gateway:1.6

Install on Kubernetes (Helm)

The Helm chart is the recommended path for production. It installs both the control plane and a default gateway pool, wires Services of type LoadBalancer, and provisions a PodDisruptionBudget suitable for a three-replica control plane.

helm repo add wardengate https://charts.wardengate.example
helm repo update

helm upgrade --install wardengate wardengate/wardengate \
  --namespace wardengate --create-namespace \
  --values values.yaml

A minimal values.yaml:

controlPlane:
  replicas: 3
  hostname: wardengate.example.com
  database:
    urlSecret: wg-postgres-url
  storage:
    bucket: s3://wg-recordings
    region: us-east-1

gateway:
  replicas: 2
  service:
    type: LoadBalancer
    annotations:
      service.beta.kubernetes.io/aws-load-balancer-type: nlb
  protocols:
    ssh: { enabled: true, port: 2222 }
    rdp: { enabled: true, port: 3389 }
    https: { enabled: true, port: 443 }

Inspect what was deployed:

kubectl -n wardengate get pods,svc
kubectl -n wardengate logs deploy/wardengate-controlplane

Initial configuration

The first administrator is created by the installer and emailed a one-time link. Once logged in, finish the bootstrap:

  • Connect an identity provider (SAML, OIDC, or SCIM). Until an IdP is wired up, only the bootstrap admin can sign in.
  • Upload a TLS certificate and private key for the user-facing hostname, or point the control plane at your ACME directory.
  • Set the recording retention window and confirm the storage bucket is reachable and writable by the control plane identity.
  • Generate a gateway bootstrap token and register your first gateway pool. Rotate the token afterwards.

Verify with the CLI

Install wgctl on your workstation, then run a health check to confirm the control plane, the database, and storage are all reachable.

wgctl login --server https://wardengate.example.com
wgctl system health

# expected output
# controlplane    ok   1.6.2 (3 replicas)
# database        ok   postgres 15.4
# storage         ok   s3://wg-recordings (rw)
# gateways        ok   2 healthy / 2 registered

Upgrades

Upgrades are rolling. For Helm, bump the chart version and run helm upgrade; the control plane applies schema migrations as its first action and gateways pick up the new config on their next heartbeat. For packages, upgrade the control plane nodes first, then the gateways.

Uninstall

The installer never touches your database or bucket on removal — state outlives the binaries. Drop the database and the bucket by hand if you want a clean wipe.

helm -n wardengate uninstall wardengate
# or, for packages
sudo apt remove wardengate-gateway wardengate-controlplane