# Firezone WireGuard VPN

> Self-hosted WireGuard VPN server with web UI for managing users and devices.

- Category: Security & Networking
- Difficulty: intermediate
- Components: firezone, postgresql, caddy
- Tags: vpn, wireguard, firezone, security, self-hosted
- Source: https://docker.recipes/security/firezone-vpn

## Overview

Firezone is a modern, open-source WireGuard VPN server that provides enterprise-grade remote access capabilities through an intuitive web interface. Built on the WireGuard protocol, Firezone offers superior performance and security compared to traditional VPN solutions like OpenVPN, while maintaining the simplicity and reliability that makes WireGuard the gold standard for modern VPN implementations. The platform focuses on zero-trust network access principles, allowing organizations to provide secure remote connectivity without the complexity of traditional VPN infrastructure.

This deployment creates a complete VPN infrastructure using three specialized services: the Firezone application server handles user management and WireGuard configuration generation, a dedicated PostgreSQL database stores user accounts and device configurations, and Caddy provides automatic HTTPS termination with Let's Encrypt certificates. The Firezone container runs with elevated network privileges (NET_ADMIN and SYS_MODULE capabilities) to manage WireGuard tunnels and IP forwarding, while the entire stack operates on an isolated Docker network for enhanced security.

This configuration is ideal for organizations seeking a self-hosted VPN solution that combines the performance benefits of WireGuard with enterprise management features. Unlike simple WireGuard deployments that require manual key management, this stack provides automated user provisioning, device management, and centralized policy control through a modern web interface, making it suitable for teams that need scalable remote access without vendor lock-in.

## Features

- WireGuard protocol implementation with automatic key generation and distribution for optimal VPN performance
- Web-based administration interface for managing users, devices, and network policies without command-line complexity
- OIDC/SAML single sign-on integration for enterprise authentication systems and identity providers
- Automatic HTTPS certificate provisioning through Caddy with Let's Encrypt integration
- PostgreSQL-backed user and device management with full ACID compliance for data integrity
- Network policy enforcement with subnet routing and DNS configuration per user or group
- Real-time connection monitoring and logging with detailed client status and bandwidth usage
- Multi-platform client support with automatic configuration file generation for Windows, macOS, iOS, and Android

## Use cases

- Remote workforce enablement for companies transitioning to hybrid work models requiring secure corporate network access
- Homelab enthusiasts seeking professional-grade VPN capabilities with web management for family device access
- Development teams needing secure access to staging environments and internal services across distributed locations
- Small to medium businesses replacing expensive commercial VPN solutions with self-hosted infrastructure
- Educational institutions providing secure network access for students and faculty across campus and remote locations
- Consultants and contractors requiring isolated client network access with professional management capabilities
- Organizations with compliance requirements needing full control over VPN infrastructure and audit logs

## Prerequisites

- Docker host with minimum 1GB RAM for PostgreSQL and Firezone application components
- Public IP address or dynamic DNS configuration for external client connectivity
- Domain name with DNS control for automatic HTTPS certificate generation via Let's Encrypt
- UDP port 51820 accessible from the internet for WireGuard protocol traffic
- Basic understanding of network routing and firewall configuration for subnet management
- Administrative access to configure ip_forward and network sysctls on the Docker host

## docker-compose.yml

```yaml
services:
  firezone:
    image: firezone/firezone:latest
    container_name: firezone
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    environment:
      - DEFAULT_ADMIN_EMAIL=${ADMIN_EMAIL}
      - DEFAULT_ADMIN_PASSWORD=${ADMIN_PASSWORD}
      - EXTERNAL_URL=${EXTERNAL_URL}
      - DATABASE_HOST=db
      - DATABASE_NAME=firezone
      - DATABASE_USER=firezone
      - DATABASE_PASSWORD=${DB_PASSWORD}
      - SECRET_KEY_BASE=${SECRET_KEY}
      - LIVE_VIEW_SIGNING_SALT=${SIGNING_SALT}
      - COOKIE_SIGNING_SALT=${COOKIE_SALT}
      - COOKIE_ENCRYPTION_SALT=${ENCRYPTION_SALT}
      - WIREGUARD_IPV4_ENABLED=true
      - WIREGUARD_IPV4_NETWORK=10.3.2.0/24
      - WIREGUARD_IPV4_ADDRESS=10.3.2.1
    volumes:
      - firezone-data:/var/firezone
    ports:
      - "51820:51820/udp"
    sysctls:
      - net.ipv4.ip_forward=1
      - net.ipv4.conf.all.src_valid_mark=1
    depends_on:
      - db
    networks:
      - firezone-network
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    container_name: firezone-db
    environment:
      - POSTGRES_USER=firezone
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=firezone
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - firezone-network
    restart: unless-stopped

  caddy:
    image: caddy:alpine
    container_name: firezone-caddy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
      - caddy-config:/config
    depends_on:
      - firezone
    networks:
      - firezone-network
    restart: unless-stopped

volumes:
  firezone-data:
  postgres-data:
  caddy-data:
  caddy-config:

networks:
  firezone-network:
    driver: bridge
```

## .env

```bash
# Firezone VPN
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=secure_admin_password
EXTERNAL_URL=https://vpn.example.com
DB_PASSWORD=secure_db_password

# Generate these with: openssl rand -base64 32
SECRET_KEY=your_64_char_secret_key
SIGNING_SALT=your_signing_salt
COOKIE_SALT=your_cookie_salt
ENCRYPTION_SALT=your_encryption_salt
```

## Usage notes

- Web UI at https://localhost
- WireGuard on UDP port 51820
- Add users and devices via web UI
- Download WireGuard configs for clients
- Supports SSO with OIDC providers

## Troubleshooting

- Clients cannot connect to VPN: Verify UDP port 51820 is open in firewall and router port forwarding is configured correctly
- Web UI shows database connection errors: Check that db container is healthy and DB_PASSWORD environment variable matches between firezone and db services
- HTTPS certificate generation fails: Ensure domain DNS points to server IP and ports 80/443 are accessible for Let's Encrypt validation
- WireGuard tunnel establishes but no internet access: Verify net.ipv4.ip_forward=1 sysctl is applied and Docker host IP forwarding is enabled
- firezone container fails to start with capability errors: Ensure Docker daemon has privileges to grant NET_ADMIN and SYS_MODULE capabilities to containers
- Configuration changes not persisting: Check that firezone-data volume is properly mounted and has correct permissions for the container user

