What are we building?

Not a new service, but the networking model behind every Docker stack. By the end you’ll know why you should create your own networks instead of the default bridge, how containers reach each other by name instead of IP (the internal DNS), what an internal network without internet access is good for, and why the shared proxy network is the trick that lets Traefik reach every app. All output comes from a real Debian 13 server running Docker 29.

Prerequisites

• A server with Docker installed and basic knowledge of Docker Compose
• Root or docker group access (see Users & permissions)
• No extra package – Docker ships with everything

Step by step

Step 1: What’s already there

After installation Docker ships with three networks:

docker network ls

NETWORK ID     NAME      DRIVER    SCOPE
9d087537e327   bridge    bridge    local
b622109fef73   host      host      local
e12e562ad7f6   none      null      local

• bridge – the default network. Containers with no explicit network land here. It works, but has one crucial catch (step 3).
• host – the container shares the host’s network stack directly (no isolation layer, no port mapping). For special cases only.
• none – no network at all. For containers that should deliberately be offline.

For your own stacks you don’t use any of these directly – you create your own networks. Why is shown in step 3.

Step 2: Creating your own network

docker network create demo-net

Docker creates a bridge network and assigns a subnet automatically:

docker network inspect demo-net --format 'name={{.Name}} driver={{.Driver}} subnet={{range .IPAM.Config}}{{.Subnet}}{{end}}'

name=demo-net driver=bridge subnet=172.20.0.0/16

Every container in this network gets an IP from 172.20.0.0/16. But you don’t want to work with IPs at all – they change on every restart. The real win is something else.

Step 3: The internal DNS – finding containers by name

Start two containers in demo-net: a web server and a client.

docker run -d --name web --network demo-net nginx:1.29-alpine
docker run -d --name client --network demo-net alpine:3.20 sleep 600

Now the crucial test – the client reaches the web server by its name:

docker exec client ping -c 2 web

PING web (172.20.0.2): 56 data bytes
64 bytes from 172.20.0.2: seq=0 ttl=64 time=0.171 ms
64 bytes from 172.20.0.2: seq=1 ttl=64 time=0.095 ms

Docker automatically resolves the container name web to the right IP. The same works for HTTP:

docker exec client wget -qO- http://web/

<title>Welcome to nginx!</title>

This is exactly why Compose files say DB_HOST=db instead of an IP: db is the service name, and Docker turns it into the right address. Comparing with the default bridge shows why you avoid it – there’s no name resolution there:

docker run -d --name legacy1 nginx:1.29-alpine
docker run --rm alpine:3.20 ping -c 1 legacy1

ping: bad address 'legacy1'

Step 4: Segmenting – a database with no internet

Not every container needs to see every other one. A database should only be reachable by its app and needs no internet itself. That’s what internal networks are for:

docker network create --internal demo-intern

internal: true cuts the route to the outside. The proof:

docker run --rm --network demo-intern alpine:3.20 \
  sh -c "wget -qT4 -O- http://example.com >/dev/null 2>&1 && echo REACHED || echo BLOCKED"

BLOCKED

This is a strong security pattern: even if an attacker compromises the database, it can’t open a connection to the outside (no pulling in malware, no data exfiltration). A typical stack therefore uses two networks: an internal network between app and database, and the public proxy network only between app and Traefik.

Step 5: The proxy network – how Traefik reaches every app

Now the most-copied half-sentence of the catalog. Traefik runs in its own container and has to talk to every app to forward its requests. But containers only talk to each other when they’re on the same network. The solution: a shared, permanent network called proxy.

docker network inspect proxy --format 'name={{.Name}} driver={{.Driver}} subnet={{range .IPAM.Config}}{{.Subnet}}{{end}} internal={{.Internal}}'

name=proxy driver=bridge subnet=172.19.0.0/16 internal=false

Traefik stays permanently on this network. Every new app joins it – in Compose like this:

services:
  myapp:
    image: example/app:1.0
    networks:
      - proxy        # so Traefik can reach the app
      - intern       # private link to the database
    labels:
      - "traefik.enable=true"
      # ... the router/service labels

networks:
  proxy:
    external: true   # created by Traefik, do NOT recreate
  intern:
    internal: true

Two things are key here: external: true tells Docker “this network already exists, just attach to it” – if you accidentally recreate it, the app lands in a different proxy network than Traefik and can’t be reached via the domain (the classic 502 troubleshooting case). And through the second network intern the app reaches its database without that database ever sitting on the public network.

Step 6: Publishing ports – only where needed

In all steps so far, containers talk to each other without publishing a single port. A port only needs to go outside when the host or the internet should access it directly:

docker run -d --name pub -p 8099:80 nginx:1.29-alpine
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8099/

200

-p 8099:80 binds host port 8099 to container port 80. In Compose that’s ports: ["8099:80"]. The important difference to expose: expose only makes a port visible to other containers (network-internal), ports opens it to the host.

When things go wrong

Maintenance & backups

• Networks need no backup – they’re recreated from the Compose file at any time. What matters is that your compose.yaml and the networks: declarations are in your backup, not the network state itself.
• Clean up orphaned networks. After lots of testing, unused networks pile up. docker network ls shows them, docker network prune removes all without attached containers. The permanent proxy network survives this as long as Traefik is running.
• The proxy network is infrastructure. Treat it like Traefik itself: create it once, then leave it alone. Deleting it by accident (network prune with Traefik stopped) forces you to reconnect all apps. More on clean-up in Keeping your Docker stack updated.

What are we building?

A WireGuard VPN natively on the server (no container – WireGuard is in the Linux kernel, which is the leanest and most stable variant). Your devices – laptop, phone – get an encrypted tunnel to the server and, through it, a private IP in the 10.8.0.0/24 network. Two operating modes that you switch via a single client line:

• Split tunnel (default): Only the path to the server and its internal services runs through the VPN. This lets you reach things that shouldn’t be public (a dashboard, a database, later your own DNS filter), without publishing a port for it.
• Full tunnel (optional): All of your device’s internet traffic runs through the server – handy on open café Wi-Fi, because then everything goes out encrypted via your own IP.

Tested with wireguard-tools 1.0.20210914 on Debian 13 (kernel 6.12, WireGuard is built in there).

Why WireGuard and not OpenVPN or an open port? WireGuard runs in the kernel, is tiny with only a few thousand lines of code (easy to audit, small attack surface), needs only a single UDP port and gets by with a handful of config lines. The handshake is so lean that a mobile connection is practically back up immediately after waking. So instead of putting every internal service on the net with its own authentication, you lay one secure tunnel – and everything behind it stays private.

Prerequisites

• A server with an active UFW firewall and root or sudo access.
• If you also use the netcup firewall: open the WireGuard port there later (ready-made template in the firewall tutorial).
• A client device with the official WireGuard app (Windows, macOS, Linux, iOS, Android).

Step by step

Step 1: Install WireGuard

The kernel already ships WireGuard; you only need the userspace tools (and qrencode for the phone QR code):

sudo apt update
sudo apt install -y wireguard wireguard-tools qrencode

Check that the kernel module can be loaded:

sudo modprobe wireguard && lsmod | grep wireguard

wireguard             118784  0

Step 2: Generate key pairs

WireGuard authenticates purely via key pairs – no password, no certificates. Each side (server and every client) has a private and a public key. The private one must never leave the machine. First set a strict file mask so the keys aren’t readable by others:

umask 077
wg genkey | sudo tee /etc/wireguard/server.key | wg pubkey | sudo tee /etc/wireguard/server.pub

The first command generates the private key (server.key), pipes it through wg pubkey and stores the public one (server.pub). Generate a pair for your first client the same way:

wg genkey | tee client.key | wg pubkey > client.pub

You now have four keys. Remember the assignment: the server config gets the private server key and the public client key; the client config the other way around. This is the most common source of error – never enter the private key of the wrong side.

Step 3: Create the server configuration

Create /etc/wireguard/wg0.conf. Enter your private server key and the public client key:

[Interface]
Address = 10.8.0.1/24
ListenPort = 51820
PrivateKey = YOUR_SERVER_PRIVATE_KEY

[Peer]
PublicKey = YOUR_CLIENT_PUBLIC_KEY
AllowedIPs = 10.8.0.2/32

What the lines mean:

• Address – the VPN-internal IP of the server (10.8.0.1); the /24 spans the VPN subnet 10.8.0.0/24.
• ListenPort – the UDP port WireGuard listens on. 51820 is the default.
• [Peer] + AllowedIPs = 10.8.0.2/32 – this client may only appear under the VPN IP 10.8.0.2. Important: AllowedIPs has a different meaning on each side – on the server it’s the client’s fixed tunnel IP, on the client (step 5) it defines what is routed through the tunnel.

For every further client you later simply add another [Peer] block with the next IP (10.8.0.3/32 …).

Step 4: Open the firewall and start the tunnel

WireGuard speaks over UDP – open the port. In UFW:

sudo ufw allow 51820/udp

If the netcup firewall also sits in front, you need an inbound rule there UDP · destination port 51820 – the ready-made template is in the netcup firewall tutorial. Now start the tunnel and set up autostart:

sudo wg-quick up wg0
sudo systemctl enable wg-quick@wg0

Check that the interface is up:

sudo wg show wg0

interface: wg0
  public key: nZT4kozgZjtHVzGfPRL+niI4llEQCUqGpYG0ni+fAT4=
  private key: (hidden)
  listening port: 51820

peer: j5h2jl87JApAbWrJikrth3H/6fNuf6X2TgBgDSJVwwE=
  allowed ips: 10.8.0.2/32

The peer is registered, but there’s no latest handshake yet – logical, the client is still missing.

Step 5: Set up the client

The client config is the mirror image. Create a file client.conf (on the server to generate the QR code; you then transfer the content to the client device):

[Interface]
Address = 10.8.0.2/24
PrivateKey = YOUR_CLIENT_PRIVATE_KEY
# DNS = 10.8.0.1   # only enable if a DNS resolver really runs on 10.8.0.1 – otherwise e.g. 1.1.1.1

[Peer]
PublicKey = YOUR_SERVER_PUBLIC_KEY
Endpoint = YOUR_SERVER_IP:51820
AllowedIPs = 10.8.0.0/24
PersistentKeepalive = 25

The decisive lines:

• Endpoint – the public IP of your server plus port. The client builds the tunnel to here.
• AllowedIPs = 10.8.0.0/24 – this is the split tunnel: only traffic into the VPN subnet runs through the tunnel, your normal internet traffic stays direct. For the full tunnel (everything via the server) you set 0.0.0.0/0 here – see step 6.
• DNS = 10.8.0.1 – deliberately commented out. This line routes the entire system DNS of your device to 10.8.0.1 – but by default nothing listens there on port 53, so with the tunnel active, name resolution breaks. Only set it if a dedicated DNS resolver/filter really runs on the server; if you just need working DNS in the tunnel, enter a real resolver like 1.1.1.1 instead.
• PersistentKeepalive = 25 – keeps the connection open when the client sits behind a NAT/CGNAT (phone on the mobile network).

For the phone, generate a QR code from the file right in the terminal – in the WireGuard app “Add tunnel → Scan QR code”:

qrencode -t ansiutf8 < client.conf

On the desktop you simply import the client.conf in the WireGuard app. Afterwards delete the client.conf and client.key from the server (they belong on the end device, not on the server).

Step 6: Check the connection (and enable the full tunnel)

Activate the tunnel in the client app and check on the server:

sudo wg show wg0

peer: j5h2jl87JApAbWrJikrth3H/6fNuf6X2TgBgDSJVwwE=
  endpoint: 203.0.113.24:34582
  allowed ips: 10.8.0.2/32
  latest handshake: 45 seconds ago
  transfer: 1.58 KiB received, 1.39 KiB sent

A latest handshake plus a growing transfer means the tunnel is up. From the client you can now reach the server at its VPN IP:

ping 10.8.0.1

If you want the full tunnel (all traffic via the VPN), two changes are needed. On the client, set AllowedIPs = 0.0.0.0/0. Also set a DNS = line on the client now (e.g. DNS = 1.1.1.1 or your own resolver): once all traffic runs through the tunnel, the DNS leak past the tunnel is in fact the normal case, not the exception – without this line your device keeps querying the DNS servers of your local network (details in the DNS leak entry in the troubleshooting part). On the server, enable routing plus NAT – first turn on IP forwarding permanently:

echo "net.ipv4.ip_forward=1" | sudo tee /etc/sysctl.d/99-wireguard.conf
sudo sysctl -p /etc/sysctl.d/99-wireguard.conf

Then add the forwarding and NAT rules to the [Interface] section of wg0.conf (replace eth0 with your real external interface, see ip route get 1.1.1.1):

PostUp = iptables -I FORWARD 1 -i wg0 -j ACCEPT; iptables -I FORWARD 1 -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostDown = iptables -D FORWARD -i wg0 -j ACCEPT; iptables -D FORWARD -m conntrack --ctstate RELATED,ESTABLISHED -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

After sudo wg-quick down wg0 && sudo wg-quick up wg0 you check the full tunnel by querying your public IP on the client – it should now be the server IP:

curl -s ifconfig.me

Step 7: Make a service reachable only via the VPN

Now the real payoff. A service only you need doesn’t have to sit publicly behind Traefik – you bind it to the VPN IP of the server (10.8.0.1), then it’s reachable exclusively through the tunnel, without a single port on the internet.

For a Docker service that means: publish the port not to 0.0.0.0, but specifically to the VPN IP. So instead of - "8080:80":

    ports:
      - "10.8.0.1:8080:80"

The service thus listens only on the WireGuard interface – it’s invisible from the internet, and via the VPN you reach it at http://10.8.0.1:8080. (Important: wg0 must already be up when the container starts – the systemctl enable from step 4 ensures that.)

By the same principle you can also allow SSH only via the VPN: in UFW, remove the public SSH access and instead allow it only from the VPN subnet –

sudo ufw allow from 10.8.0.0/24 to any port 22 proto tcp

– then delete the public SSH rule. Be sure to test a second connection via the VPN beforehand, or you’ll lock yourself out (in an emergency the VNC console in the netcup SCP helps).

When things go wrong

Maintenance & backups

• Add more devices. One key pair per device and another [Peer] block in wg0.conf with the next free IP (10.8.0.3/32 …). Never use the same key on two devices. So that existing tunnels don’t drop in the process, reload the changed config live instead of doing down/up:

  Terminal

  sudo wg syncconf wg0 <(wg-quick strip wg0)

• Back up the keys – they are the heart of the VPN. Include /etc/wireguard/ in your encrypted Restic backup. Whoever has the private keys gets into the VPN – treat them like passwords.

• Keep it current. wireguard-tools gets its updates via automatic security updates; the kernel module comes with the kernel updates.

• Bind internal services to the VPN. The real payoff: services no one from the internet should reach, you let listen only on 10.8.0.1 (instead of 0.0.0.0) – then they’re reachable exclusively through the tunnel, without any public port.

• On a server migration, carry the new public IP over into the Endpoint of every client – otherwise the client no longer finds the server.

• Honest about the effort: once set up, WireGuard runs practically maintenance-free. The only recurring task is creating a peer per new device.