docker-compose.agent.yml

# wgmesh agent sidecar template.
#
# Copy this into an app's compose project and replace "myservice" with
# the service container that should join the mesh. The agent shares that
# service's network namespace, so wg-int and the overlay IP appear inside
# the app container's networking.
#
# WGMESH_AGENT_IMAGE must point at the agent image/target, not the server
# image. With the included Gitea workflow that is:
#   gitea.mynetbird.uk/<owner>/wgmesh-agent:latest
# If building locally instead, build the Dockerfile with --target agent.
#
# Set WGMESH_HOSTNAME to the friendly machine name you want in the web UI.
# Docker sidecars do not inherit the app container hostname just because
# they use network_mode: "service:...".

services:
  myservice:
    image: replace-me
    restart: unless-stopped

  myservice-wgmesh:
    image: ${WGMESH_AGENT_IMAGE:?set WGMESH_AGENT_IMAGE to wgmesh-agent, not wgmesh-server}
    entrypoint: ["/usr/local/bin/agent"]
    restart: unless-stopped
    network_mode: "service:myservice"
    cap_add:
      - NET_ADMIN
      # NET_RAW lets the agent capture the overlay interface for flow logs
      # when conntrack byte accounting is unavailable (the container default,
      # e.g. on Unraid). Drop it if you don't need the Traffic tab.
      - NET_RAW
    devices:
      - /dev/net/tun:/dev/net/tun
    environment:
      WGMESH_SETUP_KEY: ${WGMESH_SETUP_KEY:?set WGMESH_SETUP_KEY}
      WGMESH_HOSTNAME: ${WGMESH_HOSTNAME:-myservice}
    command: >
      --server ${WGMESH_SERVER_URL:?set WGMESH_SERVER_URL}
      --setup-key ${WGMESH_SETUP_KEY}
      --hostname ${WGMESH_HOSTNAME:-myservice}
      --listen-port ${WGMESH_LISTEN_PORT:-51820}
      --key-file /data/wgkey.key
      --relay-transport ${WGMESH_RELAY_TRANSPORT:-auto}
      --direct-probe=${WGMESH_DIRECT_PROBE:-false}
      --manage-firewall=false
      # To act as the routing gateway for static/mobile WireGuard clients
      # (iPhone/Android), no extra flag is needed: pin the mobile peer to this
      # agent's public key via POST /api/mobile-peers and the agent enables IP
      # forwarding (no NAT) automatically. Keep NET_ADMIN; if the shared netns
      # exposes the forwarding sysctls read-only, set them on the app service:
      #   sysctls: ["net.ipv4.ip_forward=1", "net.ipv6.conf.all.forwarding=1"]
      # Legacy source-NAT mode (hides the phone's source IP) is still available:
      #   --gateway-nat-cidrs ${WGMESH_GATEWAY_NAT_CIDRS}
      # Exit nodes: add --advertise-exit-node to OFFER this node as full-tunnel
      # egress (assign per machine in the UI; needs the forwarding sysctls
      # above). To make THIS container's internet traffic leave via an exit
      # node, no flag is needed — assign one to this machine in the UI and the
      # agent installs the policy routing. Caveat: with Docker's embedded DNS,
      # name lookups happen on the host and bypass the tunnel unless mesh DNS
      # is pushed.
      # To surface Traefik access logs as Proxy Events, add the flag below
      # and mount Traefik's JSON access log into this sidecar (see volumes):
      #   --traefik-access-log /logs/access.log
    volumes:
      - myservice-wgmesh:/data
      # - traefik-logs:/logs:ro   # the volume Traefik writes its JSON access log to
    depends_on:
      - myservice

volumes:
  myservice-wgmesh: