# Netmaker Mesh VPN

> Create and manage WireGuard mesh networks with a beautiful web interface.

- Category: Security & Networking
- Difficulty: advanced
- Components: netmaker, netmaker-ui, coredns, caddy, mosquitto
- Tags: vpn, wireguard, mesh, netmaker, networking
- Source: https://docker.recipes/security/netmaker-mesh

## Overview

Netmaker is an open-source network automation platform that creates and manages WireGuard-based mesh networks through a centralized control plane. Developed by Gravitl, it emerged as a solution to simplify enterprise-grade mesh networking, allowing organizations to connect distributed infrastructure, remote workers, and IoT devices through encrypted tunnels without the complexity of traditional VPN solutions. Unlike hub-and-spoke VPN architectures, Netmaker enables direct peer-to-peer connections between nodes, reducing latency and eliminating single points of failure.

This stack combines Netmaker's core server with a React-based web interface (netmaker-ui), CoreDNS for mesh network name resolution, Eclipse Mosquitto for MQTT-based node communication, and Caddy for automatic HTTPS termination. The architecture creates a complete mesh VPN management platform where Netmaker handles WireGuard configuration and network topology, Mosquitto facilitates real-time communication between the server and mesh nodes, CoreDNS provides internal DNS resolution for mesh participants, and Caddy serves both the web interface and API endpoints with automatic SSL certificates.

This configuration suits organizations requiring secure site-to-site connectivity, DevOps teams managing distributed infrastructure, and network administrators deploying zero-trust architectures. The combination provides enterprise-grade mesh networking capabilities with the operational simplicity of a web-managed platform, making advanced WireGuard deployments accessible without deep networking expertise.

## Features

- WireGuard mesh network creation with automatic peer configuration and key management
- Real-time node communication and configuration updates via MQTT messaging through Mosquitto
- Integrated DNS resolution for mesh network participants using CoreDNS with dynamic host records
- Web-based network topology visualization and node management through React interface
- Egress and ingress gateway functionality for connecting external networks to the mesh
- Automatic HTTPS certificate provisioning for both dashboard and API endpoints via Caddy
- SQLite-based configuration storage with support for multiple database backends
- UDP hole punching and NAT traversal for direct peer-to-peer connections

## Use cases

- Site-to-site VPN replacement for connecting multiple office locations with direct inter-site communication
- Secure remote access for distributed development teams requiring access to internal services and databases
- IoT device connectivity for managing sensors and edge devices across multiple geographic locations
- Multi-cloud infrastructure networking to create secure connections between AWS, Azure, and Google Cloud resources
- Kubernetes cluster networking for connecting workloads across different cloud providers and on-premises infrastructure
- Zero-trust network architecture implementation with granular access controls and encrypted communications
- Branch office connectivity for retail or service organizations with multiple small locations

## Prerequisites

- Minimum 2GB RAM and 1GB disk space for the complete stack with moderate network size
- Domain name with DNS control for automatic SSL certificate generation and API/dashboard access
- UDP ports 51821-51830 accessible from the internet for WireGuard connections
- Basic understanding of network subnets and routing for mesh network planning
- Linux server with kernel support for WireGuard (kernel 5.6+ or WireGuard kernel module)
- Firewall configuration allowing inbound connections on ports 80, 443, 53, and 1883

## docker-compose.yml

```yaml
services:
  netmaker:
    image: gravitl/netmaker:latest
    container_name: netmaker
    cap_add:
      - NET_ADMIN
      - NET_RAW
      - SYS_MODULE
    sysctls:
      - net.ipv4.ip_forward=1
      - net.ipv4.conf.all.src_valid_mark=1
    environment:
      - SERVER_NAME=${SERVER_NAME}
      - SERVER_HOST=${SERVER_HOST}
      - SERVER_API_CONN_STRING=api.${SERVER_NAME}:443
      - COREDNS_ADDR=${SERVER_HOST}
      - DNS_MODE=on
      - API_PORT=8081
      - MASTER_KEY=${MASTER_KEY}
      - DATABASE=sqlite
      - MQ_HOST=mq
      - MQ_PORT=1883
      - MQ_SERVER_PORT=1883
    volumes:
      - netmaker-data:/root/data
      - netmaker-dnsconfig:/root/config/dnsconfig
    ports:
      - "51821-51830:51821-51830/udp"
    networks:
      - netmaker-network
    restart: unless-stopped

  netmaker-ui:
    image: gravitl/netmaker-ui:latest
    container_name: netmaker-ui
    environment:
      - BACKEND_URL=https://api.${SERVER_NAME}
    depends_on:
      - netmaker
    networks:
      - netmaker-network
    restart: unless-stopped

  coredns:
    image: coredns/coredns:latest
    container_name: netmaker-coredns
    command: -conf /root/dnsconfig/Corefile
    volumes:
      - netmaker-dnsconfig:/root/dnsconfig
    ports:
      - "53:53/udp"
      - "53:53/tcp"
    networks:
      - netmaker-network
    restart: unless-stopped

  mq:
    image: eclipse-mosquitto:2
    container_name: netmaker-mq
    volumes:
      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf:ro
      - mq-data:/mosquitto/data
      - mq-logs:/mosquitto/log
    ports:
      - "1883:1883"
    networks:
      - netmaker-network
    restart: unless-stopped

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

volumes:
  netmaker-data:
  netmaker-dnsconfig:
  mq-data:
  mq-logs:
  caddy-data:

networks:
  netmaker-network:
    driver: bridge
```

## .env

```bash
# Netmaker Mesh VPN
SERVER_NAME=netmaker.example.com
SERVER_HOST=your_server_ip

# Generate with: tr -dc A-Za-z0-9 </dev/urandom | head -c 32
MASTER_KEY=your_master_key_here
```

## Usage notes

- Dashboard at https://dashboard.netmaker.example.com
- API at https://api.netmaker.example.com
- Create networks and enroll nodes
- Supports egress, ingress gateways
- DNS resolution for mesh nodes

## Troubleshooting

- Nodes fail to connect after enrollment: Check that UDP ports 51821-51830 are properly forwarded and accessible from client networks
- CoreDNS fails to start with 'bind: address already in use': Stop systemd-resolved or change host DNS port binding to avoid port 53 conflicts
- Caddy SSL certificate generation fails: Verify domain DNS records point to server IP and ports 80/443 are accessible for Let's Encrypt challenges
- MQTT connection errors in Netmaker logs: Ensure Mosquitto container is healthy and port 1883 is accessible within the Docker network
- Netmaker API returns 'database locked' errors: Check that only one Netmaker instance is running and SQLite database file permissions are correct
- Mesh nodes lose connectivity intermittently: Verify NAT traversal settings and consider configuring relay servers for nodes behind strict firewalls

