Deploy a Gateway with Docker

Run the Firezone Gateway as a Docker container on any host with Docker Engine for Linux. Docker Desktop can be used for testing but is not supported for production.

Before you start, open Sites → <your Site> → Deploy a Gateway in the admin portal, select the Docker tab, and copy the FIREZONE_TOKEN value. Review the sizing guidelines first.

Run the container

Substitute your token and a unique ID, then run:

docker run -d \
  --restart=unless-stopped \
  --pull=always \
  --health-cmd="ip link | grep tun-firezone" \
  --name=firezone-gateway \
  --cap-add=NET_ADMIN \
  --sysctl net.ipv4.ip_forward=1 \
  --sysctl net.ipv4.conf.all.src_valid_mark=1 \
  --sysctl net.ipv6.conf.all.disable_ipv6=0 \
  --sysctl net.ipv6.conf.all.forwarding=1 \
  --sysctl net.ipv6.conf.default.forwarding=1 \
  --device="/dev/net/tun:/dev/net/tun" \
  --volume /var/lib/firezone:/var/lib/firezone \
  --env FIREZONE_TOKEN="<your-token>" \
  --env FIREZONE_ID="<unique-id>" \
  --env RUST_LOG=info \
  ghcr.io/firezone/gateway:1

FIREZONE_TOKEN is a single-owner token that authenticates exactly one Gateway. To deploy multiple Gateways in a Site, run the Deploy a gateway flow once per host to mint a separate token for each. Only legacy multi-owner tokens may be reused across hosts, with a unique FIREZONE_ID on each. See the Gateway CLI reference for all environment variables.

The Gateway can't raise the host's UDP buffer sizes from inside Docker (it mounts /proc/sys read-only), which can limit throughput. See performance tuning.

Mount /var/lib/firezone. Without it, the Gateway's flow log spool lives in the container's writable layer, so flows not yet uploaded are lost whenever the container is recreated.

Docker Compose reference

To manage the Gateway declaratively, use the following docker-compose.yml. It uses the same options as the docker run command above:

services:
  firezone-gateway:
    image: "ghcr.io/firezone/gateway:1"
    environment:
      # Use a unique ID for each Gateway in your Firezone account. If left blank,
      # the Gateway will generate a random ID saved in /var/lib/firezone
      # FIREZONE_ID: <id>

      # REQUIRED. The token shown when deploying a Gateway in the admin portal.
      FIREZONE_TOKEN: <token>

      # Configure log output. Other options are "trace", "debug", "info", "warn", "error", and "off".
      # See https://docs.rs/env_logger/latest/env_logger/ for more information.
      RUST_LOG: info
    volumes:
      # Persists the flow log spool, and the FIREZONE_ID when not set above.
      - /var/lib/firezone:/var/lib/firezone
    cap_add:
      - NET_ADMIN
    # Needed to properly handle signals for restarting
    init: true
    sysctls:
      # Enable IP forwarding
      - net.ipv4.ip_forward=1
      - net.ipv4.conf.all.src_valid_mark=1
      - net.ipv6.conf.all.disable_ipv6=0
      - net.ipv6.conf.all.forwarding=1
      - net.ipv6.conf.default.forwarding=1
    healthcheck:
      test: ["CMD-SHELL", "ip link | grep tun-firezone"]
      interval: 5s
      timeout: 10s
      retries: 3
      start_period: 1m
    devices:
      - /dev/net/tun:/dev/net/tun
# If you want to access services within the same compose file, they must share a network.
#    networks:
#      fz-net:
#
#   # Heads-up for Linux users.
#   # Due to limitations of `systemd-resolved` on Linux, a "two-label" domain is necessary if you want to define this as a DNS resource.
#   # i.e. just using `yourservice` won't work.
#   yourservice.docker:
#     image: "..."
#     networks:
#       fz-net:
#
# networks:
#   fz-net:

Need help? See all support options.