🔐 WireGuard VPN in Docker

English · Українська

Set up your own self-hosted WireGuard VPN server in minutes using Docker, and connect clients on Linux, Raspberry Pi, smartphones and routers.

---

📑 Table of Contents

• Requirements
• 1. Connect to the server
• 2. Install Docker
• 3. Prepare the configuration
• 4. Launch the container
• 5. Generate client configs
• Client setup — GNU/Linux
• Client setup — Raspberry Pi
• Autostart on Raspberry Pi
• Monitoring connected clients

---

✅ Requirements

• A VPS / server with root SSH access (Ubuntu/Debian recommended)
• A public IP address
• UDP port 51820 open in the firewall

---

1. Connect to the server

ssh root@your-server-ip

Update the package cache and the system first:

apt update && apt upgrade -y

---

2. Install Docker

You can follow the official documentation, but the version bundled in the standard Ubuntu repositories works fine:

apt install docker.io
apt install docker-compose

---

3. Prepare the configuration

Create a directory to store the configuration files (for example, in your home folder), along with a config directory that will be mounted inside the container:

mkdir -p ~/wireguard/config

Create the Compose file:

nano ~/wireguard/docker-compose.yml

Adjust the following before saving:

• SERVERURL — set it to auto or to your server's public IP address.
• PEERS — the number of clients you plan to use. For a laptop, 2 phones and a router (4 devices) set PEERS=4.
• volumes — make sure the mounted path points to the ~/wireguard/config directory you created above.

The final file should look like this:

---
version: "2.1"
services:
  wireguard:
    image: lscr.io/linuxserver/wireguard
    container_name: wireguard
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/London
      - SERVERURL=auto          # optional
      - SERVERPORT=51820        # optional
      - PEERS=4                 # optional
      - PEERDNS=auto            # optional
      - INTERNAL_SUBNET=10.13.13.0  # optional
      - ALLOWEDIPS=0.0.0.0/0    # optional
    volumes:
      - ~/wireguard/config:/config
      - /lib/modules:/lib/modules
    ports:
      - 51820:51820/udp
    sysctls:
      - net.ipv4.conf.all.src_valid_mark=1
    restart: unless-stopped

---

4. Launch the container

cd ~/wireguard
docker-compose up -d

Wait for the image to download and the container to start, then verify it is running:

docker ps

On success you should see something like:

CONTAINER ID   IMAGE                   COMMAND   CREATED         STATUS         PORTS                      NAMES
97d91a1ffa87   linuxserver/wireguard   "/init"   5 minutes ago   Up 2 minutes   0.0.0.0:51820->51820/udp   wireguard

The server is now configured and ready for clients.

---

5. Generate client configs

To print a QR code for adding a tunnel, run on the server:

docker exec -it wireguard /app/show-peer 1

Where 1 is the peer number (PEERS) you defined earlier.

💡 Tip: connect each client under a separate peer.

Each generated peer lives in its own directory inside ~/wireguard/config:

ls -la ~/wireguard/config

Inside every peerN directory you'll find files generated at container start:

• privatekey-peer1, publickey-peer1 — the key pair
• peer1.png — a QR code for quick mobile setup
• peer1.conf — the configuration file you import on the client

---

🐧 Client setup — GNU/Linux

Install the WireGuard tools for your distribution:

# Arch Linux
sudo pacman -S wireguard-tools

# Debian / Ubuntu
sudo apt install wireguard

# Fedora
sudo dnf install wireguard-tools

Create the client config /etc/wireguard/wg0.conf using the contents of peer1.conf from the server. The easiest way is to copy it directly with scp:

sudo scp root@your-server-ip:~/wireguard/config/peer1/peer1.conf /etc/wireguard/wg0.conf

Bring the tunnel up:

wg-quick up wg0

Verify it works — the output should show your server's IP:

curl ifconfig.me

Stop the client when you're done:

wg-quick down wg0

---

🍓 Client setup — Raspberry Pi

Install WireGuard:

sudo apt update
sudo apt install wireguard

Generate the client keys:

umask 077
wg genkey | tee privatekey | wg pubkey > publickey

Create wg0.conf and add the configuration:

[Interface]
PrivateKey = <your client private key>
Address = 10.0.0.2/24

[Peer]
PublicKey = <server public key>
Endpoint = <server IP>:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 21

ℹ️ Note: Address = 10.0.0.2/24 is the SSH connection address. PersistentKeepalive keeps the connection alive even when idle.

Start WireGuard:

sudo wg-quick up wg0

---

🔁 Autostart on Raspberry Pi

To start WireGuard automatically on boot, edit rc.local:

sudo nano /etc/rc.local

Add the following line before exit 0:

sudo wg-quick up wg0

Save (Ctrl+O) and exit (Ctrl+X), then reboot. WireGuard will now connect automatically on every boot.

---

📊 Monitoring connected clients

Find the container ID:

docker ps

Open a shell inside the container (replace <container_name_or_id>):

docker exec -it <container_name_or_id> /bin/bash

Show the connected peers, their IPs, public keys and traffic:

wg show

Exit the container with Ctrl+D or exit.