Install Docker
Install docker on Ubuntu/DebianInstall docker on Ubuntu/Debian
Why Wireguard
WireGuard VPN is a newer VPN protocol that is designed to be faster, more secure, and simpler than older VPN protocols such as OpenVPN. WireGuard uses modern cryptographic techniques to provide better security and performance compared to other VPN protocols. Here are some of the main advantages of using WireGuard VPN over OpenVPN:
-
Faster Speeds: WireGuard is designed to be faster than OpenVPN due to its streamlined code and more efficient encryption algorithms. This means that WireGuard VPN can offer faster connection speeds, lower latency, and a more responsive browsing experience.
-
Better Security: WireGuard VPN uses modern cryptographic techniques such as ChaCha20 for encryption and Poly1305 for message authentication, which are considered to be more secure than the encryption algorithms used by OpenVPN. WireGuard also uses a simpler and more secure key exchange process, which makes it less vulnerable to attacks.
-
Simpler Configuration: WireGuard VPN has a simpler and more intuitive configuration process compared to OpenVPN. This means that it is easier to set up and maintain WireGuard VPN servers and clients.
-
Improved Battery Life: WireGuard VPN is designed to be more battery-efficient than OpenVPN, which is important for mobile devices such as smartphones and tablets. This is because WireGuard uses fewer resources and does not require as much processing power as OpenVPN.
In summary, WireGuard VPN offers faster speeds, better security, simpler configuration, and improved battery life compared to OpenVPN. These advantages make WireGuard a great choice for users who want a faster and more secure VPN experience. However, it should be noted that WireGuard is still a relatively new protocol and may not be as widely supported as OpenVPN by VPN providers and clients.
Create docker-compose.yml
Create a new directory for your project and create a file named docker-compose.yml inside it. add the following to it.
---version: "2"services: wireguard: image: lscr.io/linuxserver/wireguard:latest container_name: wireguard cap_add: - NET_ADMIN - SYS_MODULE environment: - PUID=1000 - PGID=1000 - TZ=Etc/UTC # e.g. America/New_York - SERVERURL=wireguard.domain.com #External IP or domain name for docker host. can be auto, the container will determine the IP - SERVERPORT=51820 # server port - PEERS=desktop,tablet,phone,phone2,fridge,toaster,cat_collar #names of all devices you want to add to this vpn - PEERDNS=1.1.1.1 #dns server IP to use with wireguard (cloduflare shown) - INTERNAL_SUBNET=10.13.13.0 #your internal subnet for the VPN - ALLOWEDIPS=0.0.0.0/0 # what IPs can connect to your server? leave at 0.0.0.0 unless you have a specific reason. - PERSISTENTKEEPALIVE_PEERS= #optional - LOG_CONFS=true # Generated QR codes will be displayed in the docker log. volumes: - ./config:/config # - /lib/modules:/lib/modules # only enable if using custom wireguard modules. ports: - 51820:51820/udp sysctls: - net.ipv4.conf.all.src_valid_mark=1 restart: unless-stoppedthe ENV variables are explained in the comments but the rest of the commands are explained below :
-
image: Specifies the Docker image to use for the container, in this caselinuxserver/wireguard. -
container_name: Sets the name of the container to “wireguard”. -
cap_add: Grants the container theNET_ADMINcapability so it can run its own network. -
environment: Sets environment variables that configure the WireGuard server. Replace the placeholders with your desired values. -
volumes: Mounts the host directories/path/to/configand/lib/modulesas volumes inside the container. -
ports: Exposes port 51820/udp on the host so that WireGuard clients can connect to the server.
Operations
docker compose up -d : download images as needed and turn on the container. docker compose down : bring down the container and disable the network. leaves the volumes on disk.
More updated info can be found at : https://docs.linuxserver.io/images/docker-wireguard
When Peers Can’t Connect: Common Gotchas
You got the container running, generated your peer configs, scanned the QR code on your phone — and then nothing. Welcome to the club. Here are the usual suspects.
Port 51820/UDP isn’t actually open. WireGuard is UDP-only, and a lot of routers (and cloud providers) block or ignore UDP by default. Double-check your router’s port forwarding rule, and if you’re behind a cloud firewall (AWS security groups, GCP firewall rules, etc.), make sure UDP 51820 is explicitly allowed inbound. TCP rules don’t count.
SERVERURL is wrong. If you set it to your LAN IP (192.168.x.x), your phone will try to reach that address from outside your network and obviously fail. Set it to your public IP or a dynamic DNS hostname. If your ISP gives you a changing IP, something like ddns.net or Cloudflare DDNS is your friend.
The kernel module isn’t loaded on the host. The container needs wireguard in the host kernel. On most modern systems it’s built-in, but some minimal VPS images don’t include it. Check with:
lsmod | grep wireguardIf nothing comes back, install it:
sudo apt install wireguard-tools linux-modules-extra-$(uname -r)sudo modprobe wireguardLog your way to the answer. The linuxserver image outputs generated peer QR codes and connection info to the container logs. When something’s off, this is the first place to look:
docker compose logs -f wireguardLook for PEERS generated lines and any wg0.conf parsing errors. Nine times out of ten the problem is visible right there — a missing env var, a bad subnet definition, or a peer name with a space in it (don’t do that).
One more thing: if you’re testing from inside your home network, the VPN handshake will fail or behave weirdly because your router likely doesn’t support NAT loopback. Test from a mobile connection or a VPS, not from the same LAN the server lives on.
