Skip to main content

Docker

As of 0.6.0, Docker is now the preferred method for deploying Firezone. Docker offers a number of benefits over the old Omnibus method:

  • Simpler, more robust upgrades: In most cases, simply pull the latest firezone/firezone image and restart the container.
  • Simpler configuration: Most day-to-day configuration of Firezone can now be done in the web UI instead of the /etc/firezone/firezone.rb configuration file. All other configuration variables can be specified as ENV vars to the Firezone container.
  • Smaller footprint: The Firezone image weighs in at a couple dozen megabytes versus hundreds of megabytes for the Omnibus package.
  • Portability: Firezone now runs on any platform that supports Docker.
  • Security: Containerization providers better security isolation than simply running as an unprivileged local user.

Step 1: Prerequisites

  • Ensure you're on a supported platform with docker-compose version 2 or higher installed.
  • Ensure port forwarding is enabled on your firewall. The default Firezone configuration requires the following ports to be open:
    • 80/tcp (optional): For automatically issuing SSL certificates.
    • 443/tcp: To access the web UI.
    • 51820/udp: VPN traffic listen port.
caution

Before deploying Firezone in production, you'll need a valid DNS record pointing to this instance. See Prepare to Deploy if you haven't done this already.

Step 2: Install Server

After prerequisites are satisfied, you're ready to install the Firezone Server.

Option 1: Automatic Install

The easiest way to deploy Firezone with Docker is the automatic install script:

bash <(curl -fsSL https://github.com/firezone/firezone/raw/master/scripts/install.sh)

This will ask you a few questions regarding initial configuration, then proceed to download a sample docker-compose.yml file, configure it with your responses, and then print instructions for accessing the Web UI.

Firezone files will be installed in $HOME/.firezone by default.

Option 2: Manual Install

If the automatic install fails, or you'd just like more control over the installation process, follow the steps below to install manually.

  1. Download the docker compose template to a local working directory: For Linux:
    curl -fsSL https://raw.githubusercontent.com/firezone/firezone/master/docker-compose.prod.yml -o docker-compose.yml
    For macOS, Windows (non-production only):
    curl -fsSL https://raw.githubusercontent.com/firezone/firezone/master/docker-compose.desktop.yml -o docker-compose.yml
  2. Generate required secrets:
    docker run --rm firezone/firezone bin/gen-env > .env
  3. At a minimum, change the ADMIN_EMAIL and EXTERNAL_URL variables. Optionally modify other secrets as needed.
  4. Bring the services up: docker compose up -d
  5. Wait about a minute for the services to boot, then create the first admin:
    docker compose exec firezone bin/create-or-reset-admin

You should now be able to access the Firezone web portal at the EXTERNAL_URL variable you defined above.

Step 3: Enable on Boot (optional)

If you'd like Firezone to start automatically on boot, first ensure Docker is enabled at startup:

sudo systemctl enable docker

Then, make sure your Firezone services have the restart: always or restart: unless-stopped option specified in the docker-compose.yml file. This is the default used in the docker-compose.prod.yml production template file.

Step 4: Install Client Apps

Once successfully deployed, users and devices can be added to connect to the VPN server:

Troubleshooting

First, check our troubleshooting guide to see if your issue is covered there. If you are unable to resolve the issue:

Post Setup

Congrats! You have completed the setup, but there's a lot more you can do with Firezone: