Firezone

intermediate

Self-hosted WireGuard VPN with web UI.

Overview

Firezone is a modern, self-hosted WireGuard VPN server that transforms the traditionally command-line-only WireGuard experience into a user-friendly web application. Built with Elixir and Phoenix, Firezone emerged as an open-source solution to simplify WireGuard deployment while adding enterprise features like user management, device provisioning, and SSO integration. Unlike traditional VPN solutions that require complex certificate management or proprietary clients, Firezone leverages WireGuard's superior performance and security while providing an intuitive administrative interface. This stack combines Firezone with PostgreSQL to create a complete VPN management platform. PostgreSQL serves as the persistence layer for user accounts, device configurations, connection logs, and administrative settings, while Firezone handles the WireGuard tunnel management and web interface. The integration allows for robust user authentication, device tracking, and audit logging that would be impossible with standalone WireGuard configurations. PostgreSQL's ACID compliance ensures that VPN configurations and user permissions remain consistent even during high-traffic periods or system failures. This configuration is ideal for organizations wanting to replace commercial VPN solutions with an open-source alternative, or home users seeking a more manageable WireGuard deployment. Small to medium businesses benefit from the reduced licensing costs compared to enterprise VPN solutions, while maintaining professional features like SSO integration and centralized user management. The web-based configuration eliminates the need for IT staff to manually generate and distribute WireGuard configurations, making VPN management accessible to non-technical administrators.

Key Features

WireGuard protocol integration with automatic key generation and peer management
Web-based administrative dashboard for user and device provisioning
OIDC/SAML single sign-on support for Google Workspace, Okta, and Azure AD
Real-time connection monitoring with bandwidth usage statistics
Rule-based traffic routing with split-tunneling configuration options
PostgreSQL-backed audit logging for compliance and security monitoring
Multi-tenant support with role-based access controls and user groups
REST API for programmatic device and user management automation

Common Use Cases

1Small business replacing expensive commercial VPN solutions like NordLayer or Perimeter 81
2Remote development teams needing secure access to internal development environments
3Home lab enthusiasts wanting secure external access to self-hosted services
4Organizations requiring VPN audit trails for compliance with SOX or HIPAA regulations
5IT departments managing contractor access with temporary VPN configurations
6Companies implementing zero-trust network architecture with centralized access control
7Educational institutions providing secure network access for remote students and faculty

Prerequisites

Minimum 1GB RAM for PostgreSQL database operations and connection handling
UDP port 51820 forwarded through firewall/router for WireGuard connections
Valid domain name or static IP address for EXTERNAL_URL configuration
Basic understanding of WireGuard concepts and VPN networking principles
OpenSSL installed on host system for SECRET_KEY_BASE generation
Knowledge of your network's subnet ranges to avoid IP conflicts with VPN clients

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  firezone: 
3    image: firezone/firezone:latest
4    container_name: firezone
5    restart: unless-stopped
6    cap_add: 
7      - NET_ADMIN
8      - SYS_MODULE
9    environment: 
10      EXTERNAL_URL: http://localhost:13000
11      DEFAULT_ADMIN_EMAIL: ${ADMIN_EMAIL}
12      DEFAULT_ADMIN_PASSWORD: ${ADMIN_PASSWORD}
13      DATABASE_URL: postgres://firezone:${DB_PASSWORD}@postgres:5432/firezone
14      SECRET_KEY_BASE: ${SECRET_KEY}
15    volumes: 
16      - firezone_data:/var/firezone
17    ports: 
18      - "13000:13000"
19      - "51820:51820/udp"
20    depends_on: 
21      - postgres
22
23  postgres: 
24    image: postgres:15-alpine
25    container_name: firezone-db
26    environment: 
27      POSTGRES_USER: firezone
28      POSTGRES_PASSWORD: ${DB_PASSWORD}
29      POSTGRES_DB: firezone
30    volumes: 
31      - firezone_db:/var/lib/postgresql/data
32
33volumes: 
34  firezone_data: 
35  firezone_db:

.env Template

.env

1ADMIN_EMAIL=admin@example.com
2ADMIN_PASSWORD=changeme
3DB_PASSWORD=changeme
4SECRET_KEY=generate-64-char-secret

Usage Notes

1Docs: https://docs.firezone.dev/
2Web UI at http://localhost:13000 - login with ADMIN_EMAIL/PASSWORD
3Generate SECRET_KEY: openssl rand -base64 48
4Download WireGuard configs from web UI for each device
5Forward UDP 51820 on router for external VPN access
6Supports SSO via OIDC providers (Google, Okta, etc.)

Individual Services(2 services)

Copy individual services to mix and match with your existing compose files.

firezone

firezone:
  image: firezone/firezone:latest
  container_name: firezone
  restart: unless-stopped
  cap_add:
    - NET_ADMIN
    - SYS_MODULE
  environment:
    EXTERNAL_URL: http://localhost:13000
    DEFAULT_ADMIN_EMAIL: ${ADMIN_EMAIL}
    DEFAULT_ADMIN_PASSWORD: ${ADMIN_PASSWORD}
    DATABASE_URL: postgres://firezone:${DB_PASSWORD}@postgres:5432/firezone
    SECRET_KEY_BASE: ${SECRET_KEY}
  volumes:
    - firezone_data:/var/firezone
  ports:
    - "13000:13000"
    - 51820:51820/udp
  depends_on:
    - postgres

postgres

postgres:
  image: postgres:15-alpine
  container_name: firezone-db
  environment:
    POSTGRES_USER: firezone
    POSTGRES_PASSWORD: ${DB_PASSWORD}
    POSTGRES_DB: firezone
  volumes:
    - firezone_db:/var/lib/postgresql/data

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  firezone:
5    image: firezone/firezone:latest
6    container_name: firezone
7    restart: unless-stopped
8    cap_add:
9      - NET_ADMIN
10      - SYS_MODULE
11    environment:
12      EXTERNAL_URL: http://localhost:13000
13      DEFAULT_ADMIN_EMAIL: ${ADMIN_EMAIL}
14      DEFAULT_ADMIN_PASSWORD: ${ADMIN_PASSWORD}
15      DATABASE_URL: postgres://firezone:${DB_PASSWORD}@postgres:5432/firezone
16      SECRET_KEY_BASE: ${SECRET_KEY}
17    volumes:
18      - firezone_data:/var/firezone
19    ports:
20      - "13000:13000"
21      - "51820:51820/udp"
22    depends_on:
23      - postgres
24
25  postgres:
26    image: postgres:15-alpine
27    container_name: firezone-db
28    environment:
29      POSTGRES_USER: firezone
30      POSTGRES_PASSWORD: ${DB_PASSWORD}
31      POSTGRES_DB: firezone
32    volumes:
33      - firezone_db:/var/lib/postgresql/data
34
35volumes:
36  firezone_data:
37  firezone_db:
38EOF
39
40# 2. Create the .env file
41cat > .env << 'EOF'
42ADMIN_EMAIL=admin@example.com
43ADMIN_PASSWORD=changeme
44DB_PASSWORD=changeme
45SECRET_KEY=generate-64-char-secret
46EOF
47
48# 3. Start the services
49docker compose up -d
50
51# 4. View logs
52docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/firezone/run | bash

Troubleshooting

WireGuard clients can't connect: Verify UDP port 51820 is properly forwarded and EXTERNAL_URL matches your actual external IP or domain
Database connection errors on startup: Ensure DB_PASSWORD environment variable matches between firezone and postgres services
Web UI shows 'Internal Server Error': Check that SECRET_KEY_BASE is exactly 48 characters long and generated with proper base64 encoding
VPN clients lose internet access: Configure split-tunneling rules in Firezone web UI to allow local internet traffic
SSO authentication fails: Verify OIDC provider callback URLs include your EXTERNAL_URL and proper redirect URIs are configured
High memory usage in postgres container: Increase shared_buffers and effective_cache_size in PostgreSQL configuration for better performance with many concurrent VPN connections

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

firezonepostgres

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download