Firezone

intermediate

Self-hosted WireGuard VPN with web UI.

[i]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

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

[!]

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

[$]docker-compose.yml

[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

[i]Usage Notes

[1]Docs: https://docs.firezone.dev/
[2]Web UI at http://localhost:13000 - login with ADMIN_EMAIL/PASSWORD
[3]Generate SECRET_KEY: openssl rand -base64 48
[4]Download WireGuard configs from web UI for each device
[5]Forward UDP 51820 on router for external VPN access
[6]Supports 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

## Tags

#firezone#wireguard#vpn#web-ui

## Category

Security & Networking

## Related

Shortcuts: C CopyF FavoriteD Download