Tweet
The standard automated scripts for Firezone often fail due to missing Docker dependencies, certificate mismatches, or firewall blockages. This comprehensive guide walks you through a bulletproof, manual deployment of Firezone using Docker Compose, secured with an automated Let's Encrypt SSL certificate.
Prerequisites
- A clean VPS running Ubuntu 22.04 LTS / 24.04 LTS
- A fully qualified domain name (FQDN) pointing to your server's IP (e.g., vpn.yourdomain.com)
- Ports 80/tcp, 443/tcp, and your WireGuard UDP port open in your hosting provider's firewall dashboard
Step 1: Install Docker and Docker Compose v2
Do not rely on the deployment script to handle Docker. Install the latest official packages beforehand to avoid version conflicts:
sudo apt update && sudo apt upgrade -y
sudo apt install curl iptables ufw -y
### Install Docker Engine
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
### Install Docker Compose Plugin
sudo apt install docker-compose-plugin -y
Step 2: Configure System Routing & UFW Firewall
Firezone needs Linux kernel IP forwarding enabled to route traffic from your clients to the internet. We also need to configure the UFW firewall properly.
1. Enable IP Forwarding:
echo "net.ipv4.ip_forward=1" | sudo tee -a /etc/sysctl.conf
echo "net.ipv6.conf.all.forwarding=1" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
2. Configure UFW Rules:
Open the required web ports and the default WireGuard UDP port:
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 51820/udp
sudo ufw enable
Step 3: Download the Firezone Bootstrap Script
Run the production bootstrap script from the official legacy branch. This will generate your container environment variables:
sudo -E bash -c "$(curl -fsSL https://github.com/firezone/firezone/raw/legacy/scripts/install.sh)"
Crucial Inputs During the Prompt:
- Admin Email: Enter your real email address.
- External URL: Enter your domain exactly like this: https://vpn.yourdomain.com
Note: The script will now generate random encryption keys, download the required database containers, and set up local SSL configurations.
Step 4: Customizing Ports & SSL (Optional but Recommended)
If you want to change the default WireGuard port (e.g., if port 51820 is restricted by your ISP) or tweak settings, open the environment configuration file:
nano $HOME/.firezone/.env
- To change the WireGuard port, locate WIREGUARD_PORT=51820 and change it to your desired port (e.g., 44332). Remember to open this new UDP port in UFW!
- Ensure TLS_OPTIONS or ACME configurations are set to automatically fetch certificates via Let's Encrypt using your provided admin email.
Save and exit (Ctrl+O, Enter, Ctrl+X).
Step 5: Launch Firezone & Generate Admin Password
Navigate to the directory, pull the validated Docker images, and start the stack in detached mode:
cd $HOME/.firezone
docker compose pull
docker compose up -d
Once all containers show Running, manually initialize or reset the admin credentials:
docker compose exec firezone firezone-ctl create-or-reset-admin
Copy the generated email and temporary password displayed in your terminal.
Step 6: Log In and Deploy Client Profiles
- Open your web browser and go to your domain: https://vpn.yourdomain.com (The SSL padlock icon should now show a secure Let's Encrypt certificate).
- Log in with the administrative credentials from Step 5.
- Go to Devices -> Add Device.
- Name the device, click save, and scan the generated QR Code with your phone or download the .conf file for your computer!
Your robust, automated, and secure Firezone server is now ready! Drop a comment below if you experience issues with the Let's Encrypt certificate challenge.
Prerequisites
- A clean VPS running Ubuntu 22.04 LTS / 24.04 LTS
- A fully qualified domain name (FQDN) pointing to your server's IP (e.g., vpn.yourdomain.com)
- Ports 80/tcp, 443/tcp, and your WireGuard UDP port open in your hosting provider's firewall dashboard
Step 1: Install Docker and Docker Compose v2
Do not rely on the deployment script to handle Docker. Install the latest official packages beforehand to avoid version conflicts:
sudo apt update && sudo apt upgrade -y
sudo apt install curl iptables ufw -y
### Install Docker Engine
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
### Install Docker Compose Plugin
sudo apt install docker-compose-plugin -y
Step 2: Configure System Routing & UFW Firewall
Firezone needs Linux kernel IP forwarding enabled to route traffic from your clients to the internet. We also need to configure the UFW firewall properly.
1. Enable IP Forwarding:
echo "net.ipv4.ip_forward=1" | sudo tee -a /etc/sysctl.conf
echo "net.ipv6.conf.all.forwarding=1" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
2. Configure UFW Rules:
Open the required web ports and the default WireGuard UDP port:
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 51820/udp
sudo ufw enable
Step 3: Download the Firezone Bootstrap Script
Run the production bootstrap script from the official legacy branch. This will generate your container environment variables:
sudo -E bash -c "$(curl -fsSL https://github.com/firezone/firezone/raw/legacy/scripts/install.sh)"
Crucial Inputs During the Prompt:
- Admin Email: Enter your real email address.
- External URL: Enter your domain exactly like this: https://vpn.yourdomain.com
Note: The script will now generate random encryption keys, download the required database containers, and set up local SSL configurations.
Step 4: Customizing Ports & SSL (Optional but Recommended)
If you want to change the default WireGuard port (e.g., if port 51820 is restricted by your ISP) or tweak settings, open the environment configuration file:
nano $HOME/.firezone/.env
- To change the WireGuard port, locate WIREGUARD_PORT=51820 and change it to your desired port (e.g., 44332). Remember to open this new UDP port in UFW!
- Ensure TLS_OPTIONS or ACME configurations are set to automatically fetch certificates via Let's Encrypt using your provided admin email.
Save and exit (Ctrl+O, Enter, Ctrl+X).
Step 5: Launch Firezone & Generate Admin Password
Navigate to the directory, pull the validated Docker images, and start the stack in detached mode:
cd $HOME/.firezone
docker compose pull
docker compose up -d
Once all containers show Running, manually initialize or reset the admin credentials:
docker compose exec firezone firezone-ctl create-or-reset-admin
Copy the generated email and temporary password displayed in your terminal.
Step 6: Log In and Deploy Client Profiles
- Open your web browser and go to your domain: https://vpn.yourdomain.com (The SSL padlock icon should now show a secure Let's Encrypt certificate).
- Log in with the administrative credentials from Step 5.
- Go to Devices -> Add Device.
- Name the device, click save, and scan the generated QR Code with your phone or download the .conf file for your computer!
Your robust, automated, and secure Firezone server is now ready! Drop a comment below if you experience issues with the Let's Encrypt certificate challenge.