How to Install Wireguard in Docker


Using a VPN is a great way to secure your personal data from getting sniffed out on public networks. You can install a VPN server on your home network and use a VPN client on your laptop or phone. The VPN client will encrypt and secure your web traffic and send it to your home network to be processed. If you have Pi-hole running on your home network as well, your VPN clients will benefit from it’s filtering capabilities no matter where you are.

For this tutorial, we will be installing Wireguard in a Docker container on a Raspberry Pi 4 running Ubuntu 18.04.4 Bionic.

What is Wireguard?

Wireguard is an free and open-source virtual private networking software package that serves as a VPN server or client on your host system. Wireguard is a faster, lighter and more efficient version of the popular OpenVPN software. Wireguard offers apps for all major desktop and mobile operating systems allowing you to install and utilize your VPN across all of your devices.

Running Wireguard in Docker

Thanks to the folks over at, running a Wireguard server in a Docker container is relatively painless. There are a few things you’ll need to change in the below docker run code before you get started.

First off, make sure you replace [YOURTZ] with your timezone from the list of TZ database time zones.

Next, you will want to change [YOURIP] with the IP address or URL that you will use to connect to your VPN.

Then, you need to replace [PEERS] with the number of clients that you intend to connect to the VPN. Each device needs to be registered in Wireguard separately. So, for example, if you want your phone, your laptop, and your tablet to connect to the Wireguard VPN, then you will need to change [PEERS] to 3.

Finally, make sure you either create a volume or bind the /config folder within the container to a folder on your host machine. You can use this folder to access your peer configurations. Replace [VOLUME] with the Docker volume name or system path that you choose.

docker run \
  --name=wireguard \
  --cap-add=NET_ADMIN \
  --cap-add=SYS_MODULE \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=[YOURTZ] \
  -e SERVERPORT=51820 \
  -e PEERS=[PEERS] \
  -e PEERDNS=auto \
  -p 51820:51820/udp \
  -v [VOLUME]:/config \
  -v /lib/modules:/lib/modules \
  --restart unless-stopped \


--name=wireguardNames the container “wireguard”.
--cap-add=NET_ADMINAllows the container to perform various network operations.
--cap-add=SYS_MODULEAllows the container to install the Wireguard kernal modules for your host operating system.
-e PUID=1000Sets Process User ID to 1000 to help avoid permission issues.
-e PGID=1000Sets Process Group ID to 1000 to help avoid permission issues.
-e TZ=[YOURTZ]Change your time zone with the correct time zone from the TZ Database.
-e SERVERURL=[YOURIP]The IP address or URL that you will use to connect to your server.
-e SERVERPORT=51820The port that you want the Wireguard application to listen on. The default port is 51820.
-e PEERS=[PEERS]Set [PEERS] to the number of client devices that you plan to connect to your VPN server.
-e PEERDNS=autoYou can change auto if you want to to specify a different DNS server for the VPN clients to use.
-e INTERNAL_SUBNET= containers internal subnet. You don’t have to change this unless there are conflicts.
-p 51820:51820/udpExposes port 51820 on the host and maps it to port 51820 on the container to connect to Wireguard.
-v [VOLUME]:/configThe /config folder is where your Wireguard peer configuration files are stored. Change [volume] to your created docker volume, or bind the /config folder to a folder on your host machine.
-v /lib/modules:/lib/modulesBind the /lib/modules folder on your system to the /lib/modules folder within the container.
--restart unless-stoppedWill ensure that the container will always run.
linuxserver/wireguardThe image that is used for this container from the Docker Hub.


How to Install Wireguard in Docker 1

After you execute the docker run command, the container will install the required kernel headers for your operating system to be able to effectively run Wireguard. Depending on your system this process could take a few minutes.

After the container setup process is completed, the terminal will display QR codes. Do not close your window, you will need to scan these QR codes later. You can scan these QR codes with the mobile applications to instantly create the Wireguard profile on your mobile devices. The QR codes are the easiest and quickest way to get Wireguard up and running on your mobile devices.

Using the Wireguard Mobile App

IOS Client - Wireguard in Docker

Download the Wireguard app from your devices respective app store. Once you have the application running on your device you can click the “+” in the top right hand corner of the application to create a new Wireguard Tunnel.

If you select the “Create from QR code” option, then you will be taken to your camera app where you can scan the QR code that is displayed on the output after you run the Wireguard docker run command.

Once you get the mobile app setup on an iOS device, you will see the VPN indicator on the top left hand corner of your screen. It will look similar to the image below.

ios VPN Indicator

Router Configuration

Just a quick reminder to adjust the port forwarding settings in your router to forward port 51820 to your Docker host. If you don’t forward this port, your routers firewall will not allow your VPN connection to connect successfully.


Your VPN should be up and running! Now your personal information is more protected when you are using public wifi.

If you have any questions or suggestions regarding this post, you can leave a comment below.

The post, Installing Wireguard in Docker, first appeared on Codeopolis.


  1. Have you ever considered about including a little bit more than just your articles?

    I mean, what you say is valuable and all. Nevertheless imagine if you added some great photos
    or videos to give your posts more, “pop”! Your content is excellent but with images
    and video clips, this blog could certainly be one of the most beneficial
    in its niche. Excellent blog!

    • I totally agree! I’ve started to include more photos in some of my more in-depth articles and will eventually go back and add additional photos to my older articles. I’m glad you appreciate the content. If you have any more suggestions, please don’t hesitate to contact me!

  2. Well done & written.
    I started writing just recently and noticed that many bloggers simply rework
    old content but add very little of value.

    It is actually going on my list of things I need
    to emulate being a new blogger. Reader engagement and content quality
    are king. Many terrific ideas; you have definitely made it on my list
    of sites to watch!

    Keep up the excellent work!

  3. Hello Patrick,
    I successfully installed Wireguard using your very useful tutorial. I also installed the app on Android phone and everything works fine. But iPad app allows to set up new Wireguard tunnel using only configuration file. Please advise where I can find all tree configuration files. Thanks

  4. Unfortunately I’m getting “No kernel headers found in the Ubuntu or Debian repos!!”


    “**** Kernel headers don’t seem to be available, can’t compile the module. Sleeping now. . . ****”

    I’m lost 🙁

1 Trackback / Pingback

  1. How to Install WireGuard in Docker – Full-Stack Feed

Comments are closed.