# Firezone

> Self-hosted WireGuard VPN with web UI.

- Category: Security & Networking
- Difficulty: intermediate
- Components: firezone, postgres
- Tags: firezone, wireguard, vpn, web-ui
- Source: https://docker.recipes/security/firezone

## 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.

## 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

## Use cases

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

## docker-compose.yml

```yaml
services:
  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:
    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

volumes:
  firezone_data:
  firezone_db:
```

## .env

```bash
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=changeme
DB_PASSWORD=changeme
SECRET_KEY=generate-64-char-secret
```

## Usage notes

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

## 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

