christianmaier/base-wireguard repository overview

⁠base-wireguard

The VPN of the base platform: WireGuard⁠ with its own DNS, so that the platform's administration interface is reachable from a few devices and from nowhere else.

⁠Tags

One tag per release, X.Y.Z, the same version as the other base-* images of that release (first: 2.3.0). There is no latest: deployments reference a version and its digest.

Platforms: linux/amd64, linux/arm64.

⁠What is inside

• linuxserver/wireguard, pinned by digest: WireGuard, iptables and CoreDNS. On the first start it creates the server key and, for each device, a config with key and QR code.
• A DNS configuration for the devices: the name of the administration interface resolves to the reverse proxy, a service named caddy in the admin network. Every other name is forwarded.
• A template for the device configs without a fixed ListenPort, so a device picks a free port itself.
• A script that runs at every start, before the tunnel comes up. It limits forwarding from the tunnel to the admin network, so a device cannot reach the internet, other networks or other devices through it. If ADMIN_SUBNET is empty, nothing is forwarded at all.

⁠Running

Port: 51820/udp. The host needs the wireguard kernel module.

services:
  wireguard:
    image: christianmaier/base-wireguard:2.3.0
    environment:
      PEERS: laptop,phone
      SERVERURL: vpn.example.com
      SERVERPORT: 51820
      INTERNAL_SUBNET: 10.10.65.0
      PEERDNS: auto
      ALLOWEDIPS: 10.10.64.0/24, 10.10.65.0/24
      ADMIN_SUBNET: 10.10.64.0/24
      LOG_CONFS: "false"
    ports: ["51820:51820/udp"]
    volumes: ["wireguard-config:/config"]
    networks: [vpn, admin]
    read_only: true
    tmpfs: ["/run:exec", "/tmp"]   # the init system starts from /run
    cap_drop: ["ALL"]
    cap_add: ["NET_ADMIN"]
    security_opt: ["no-new-privileges:true"]
    sysctls:
      net.ipv4.ip_forward: 1
      net.ipv4.conf.all.src_valid_mark: 1
    healthcheck:
      test: ["CMD", "wg", "show", "wg0"]
networks:
  vpn: {}
  admin:
    internal: true
    ipam:
      config: [{ subnet: 10.10.64.0/24 }]
volumes:
  wireguard-config: {}

A device's config, and its QR code in the terminal:

docker exec <container> cat /config/peer_laptop/peer_laptop.conf
docker exec -it <container> /app/show-peer phone

Both contain the device's private key.

⁠Security

• Runs as root, because the init system and wg-quick need it, but with NET_ADMIN as the only capability, a read-only root filesystem and no-new-privileges
• Keys are created in the volume on the first start; none are in the image
• Before every release and weekly: scanned for vulnerabilities with a fix (Trivy), for Dockerfile misconfigurations and for secrets (gitleaks). The finding "runs as root" is accepted only with a written reason and a review date.
• SBOM (SPDX) and build provenance attached to every release