Home VPN using Wireguard Docker on a Raspberry Pi 4 – Episode 28

31, Oct 2021 | Raspberry Pi 4 Series | 11 comments

Today we will be showing you how to install and set up a home/office VPN using a Wireguard Docker on a Raspberry Pi 4.


What is a VPN?.

VPN stands for a Virtual Private Network and it describes the technology used to create a secure tunnel from one network into another network. The tunnel that is created uses encryption technology so it secures any information that is sent between the client and the server.

In the above example, we have a Wireguard user who is outside of their home or office network and want to connect to their home or office network to view the MotionEyeOS camera that resides there.

Using a VPN is a perfect solution to securely access the local network without anyone else having access.

What is Wireguard and is it safe to use?.

Wireguard is a VPN software solution. It is written using 4000 lines of code which is very simplified compared with other VPN solutions like OpenVPN which has over 400,000 lines of code.

Wireguard is open source which means its source code is readable and has many developers who understand the code checking it for security flaws. In 2020 the developer of the Linux kernel Linus Torvalds was so impressed with Wireguard that his team of developers implemented Wireguard directly into the Linux Kernel.

WireGuard uses state-of-the-art cryptography, like the Noise protocol framework, Curve25519, ChaCha20, Poly1305, BLAKE2, SipHash24, HKDF, and secure trusted constructions. It makes conservative and reasonable choices and has been reviewed by cryptographers.

However, Wireguard is a new technology that has been in development since only 2016. It has not had as many years of security audits as other more established VPN technologies. But it has passed all security audits it has had to date.

Wireguard is simple to use. Fast and secure.

IPv4 – Dynamic IP vs Static IP Address.

In all networks to get access to the internet, you will need to use an Internet Service Provider (ISP). They issue each connection with a unique IP address.

The Internet has grown beyond the expectations of the creators of the IPV4 technology. With the growing number of devices and networks, the Internet infrastructure has outgrown the number of available addresses.

Allocating a fixed IP to all networks across the world is unachievable so IPV4 IP addresses are now leased to networks for a set period of time. Also known as a Dynamic IP.

The IPV4 address comes in two types.

What is a Dynamic IP Address:

A Dynamic IP address is a leased IP that has an expiry date. Once the lease period has lapsed your IPS may issue you with a new one. If you disconnect from your ISP for any reason you will normally be reissued with a brand new IP address. This causes problems in server environments when remote access is needed as the change in address means remote connections have no means of receiving the new IP and they will no longer be able to connect to the remote server.

What is a Static IP Address:

A static IP address does not change. Mostly issued to businesses who have phone or server requirements. No matter what. This IP stays the same and means remote connections can always find the Server’s destination.

Do you have a Dynamic IP address?.

We have a workaround for you.

As you can see the workaround is more complex and needs explaining.

Please watch Episode 28 on our YouTube channel to learn how to implement this and get Wireguard to work with a Dynamic IP address.


Installing the Wireguard Docker Container

The Wireguard Docker image we are going to be using today is maintained by Linuxserver.io. They frequently update their containers and they are widely used.

Step 1 – Create the folders needed for the Wireguard Docker container.

Open up a terminal or Putty application.

Connect to your Raspberry Pi via SSH (secure shell).


Navigate to your “Appdata” folder or the place where you store all your containers persistent configuration data.


Create a folder called “wireguard“.

mkdir wireguard

Navigate into the “wireguard” folder.

cd wireguard

Create the “config” folder where all the wireguard configuration data will reside.

mkdir config

Now navigate into the “config” folder.

cd config

From here you will need to get your “absolute path” for your “config” folder.


Copy the output of the pwd command and paste it into a text file. You will need this in Step 2.

Step 2 – Create the Wireguard Container Using Portainer and a Stack.

Navigate to your “Portainer dashboard” and “log in“.

From the “left-hand menu” click on “Stacks“.

Now in the Stacks dashboard click on “Add a stack“.

In the “Name” field enter “wireguard

Now Copy and paste the following docker-compose data into the “Web editor” field. Be sure to change “/path/to/appdata/config” to the absolute path you saved to a text file in the previous step.

You will also need to change the “TZ“, “PUID” and “PGID” fields to match your setup. You can find these by following our YouTube video guide above.

Wireguard Docker Compose Stack

version: "2.1"
    image: lscr.io/linuxserver/wireguard
    container_name: wireguard
      - NET_ADMIN
      - SYS_MODULE
      - PUID=1001
      - PGID=100
      - TZ=Europe/London
      - SERVERURL=auto
      - SERVERPORT=51820
      - PEERS=1 #change to match how many devies you want to use Wireguard on
      - PEERDNS=auto
      - INTERNAL_SUBNET= #optional
      - ALLOWEDIPS= #optional
      - /path/to/appdata/config:/config
      - /lib/modules:/lib/modules #do not change
      - 51820:51820/udp
    restart: unless-stopped

Once you have completed that you are ready to click “Deploy the stack“.

If you navigate to “Containers” in the left menu

You should now see your “wireguard” container in the list.

Forward port 51820 on your Router to your Raspberry Pi.

You will now need to port forward port 51820 from within your Router to your Raspberry Pi’s IP address.

There are so many different router models on the market so we recommend searching on Googlehow to port forward on ROUTER MODEL NAME” to get a detailed guide for your router.

You will also need to know your Routers IP address and login credentials to access the administrator interface.

Port Forward Settings:

You will need to give your forward a name. Call it “Wireguard“.

Set the Port Range as “51820“.

Set the Local IP as your Raspberry Pi’s IP address ““.

Set the Local Port as “51820“.

Finally set the Protocol to “UDP“.

Once all fields have been set click “Apply” to complete the Port forward.

We also show you how to do this in more detail in our YouTube tutorial for this episode.

How to view and use the configuration folders?.

To view the configuration folders and enter the configuration commands below you will need to be connected via SSH to your Raspberry Pi.

Once you have deployed the Wireguard stack. Depending on how many peers you set in the stack “docker-compose file” configuration, the deployment process will have automatically created user folders for each connecting peer. In our example, we have two peers. peer1 and peer2.

To view the Wireguard configuration files you need to navigate to your “appdata/wireguard/config” folder that you set in your stack “docker-compose file“.

cd /path/to/appdata/config

In the “peer” folder, it holds all the configuration settings needed to connect a client (also known as a peer) to the Wireguard Server.

This includes the “public and private keys” and a “QR code png” file that you can scan using a camera-enabled device” to auto-create the configuration settings on the connecting device.

To get the “QR code” for “peer1” so you can scan it with your “camera-enabled device” you will need to type the following into your “terminal window“:

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

Note: You need to change the peer number to match the peer you are trying to connect.

Press “enter” to execute the command in the terminal window.

You should see a “QR code” for “peer1“.

Connecting Peers.

How to connect a peer using the QR code?.

You will now need to “download” the “Wireguard application” for your “camera-enabled device“.

Once installed “open the application”.

Click on the “+plus button” to bring up the “menu“. Then click on “SCAN FROM QR CODE“.

You may get some prompts to allow the application access to your camera and folders just allow this access.

Now “use your camera” to “scan the QR code“. Make sure you capture the whole square in the camera view.

Once the QR has been read by the application it will set all the configuration settings for you automatically. All you need to do now is to “name the connection“. In this example, we named it “Wireguard“.

Then click “CREATE TUNNEL“.

How to import the peer configuration file?.

To import the configuration settings using a file you will need to copy the “peer1.conf” file to the “connecting device“. Once you have the file on that device you can click the “IMPORT FROM FILE OR ARCHIVE” button and select the “peer1.conf” file to “import the settings”.

How to manually connect a peer?.

To manually add a peer using the configuration settings you will need to click on “CREATE FROM SCRATCH” from within the Wireguard application.

To get the configuration settings needed you will need to manually copy the contents of the “peer1.conf” file into the “Create WireGuard Tunnel” interface.

You will need to copy the two sections “interface” and “peer” exactly as they appear.

Note: if you are using another peer the name of the .conf file will increase incrementally. for example peer2.conf etc.

Interface Section
Peer Section

Testing the connection to make sure it is working.

The configuration file on the peer’s device should look similar to this:

Note: When the connection is working under “Transfer” the “rx:” field value will start to increase. If it only shows “0 KiB” then there must be an error with your configuration.

Another way to test the connection is working correctly is to view what “peers” are currently connected. While in the “terminal” run this “command” to see the connecting peer’s.

docker exec -it wireguard wg

You should see something similar to this returned:

You should see a “list of peers” and when the “latest handshake” event happened. Also how much data has been transferred and the “endpoint” used on the LAN. If none of this extra data is under the “peer” field then that peer is not connected.

Congratulations you have now successfully set up a VPN connection on your Raspberry Pi.

This brings us to the end of this tutorial. Remember if your IP address is Dynamic then you can still use Wireguard with your Raspberry Pi you will just need to follow our workaround which you can find on this episodes YouTube tutorial.

We need your support.

We hope you enjoyed this episode and that it was helpful and you got benefit out of it.

If you did, please consider supporting our channel by Subscribing to our YouTube channel, and liking and sharing our content.

You can also make a donation via Paypal or become a Patreon if you wish to do so.

You can also follow us on Facebook or Twitter.

If you have any questions or any requests please ask in the comments below or on YouTube.


  1. Zimny

    Quick question: should we change in the end A record in cloudflare.com back to proxied?

    • Addicted2Tech

      No because the VPN uses its own encryption so it doesn’t need tls or a Cloudflare proxy. In fact in my tests enabling the cloudflare proxy broke the connection. So leave it as DNS only.

  2. sth

    Your cloudflare A record with * did not show which is the IP address of your raspberry pi. Please help to explain the purpose of having this wildcard A record. Thanks.

    • Addicted2Tech

      No, it showed the public IP of my network.

  3. JP

    Hey I am having an issue finding the appdata folder to create the wireguard directory. The only directories in my srv folder are ftp, pillar, salt.

    • Addicted2Tech

      You can create it yourself and then you can use it as described :).

  4. Yevhen

    Hi. In your video, you have two cloudflare-ddns containers: cloudflarea2t and cloudflareVPN. Why do we need a separate Cloudflare-ddns container for wireguard service?

    • Yevhen

      I found an answer in the comments under the video on youtube – “New domain = new cloudflare docker :)”

  5. Ian

    Thanks for the tutorial!

  6. marc

    How to upgrade a working installation?

    • marc

      Nevermind, found out:
      – docker pull lscr.io/linuxserver/wireguard
      – docker rm -f wireguard
      – docker-compose up -d (if you have a compose file)


Submit a Comment

Your email address will not be published. Required fields are marked *

<a href="https://addictedtotech.net/author/attadmin/" target="_self">Addicted2Tech</a>


We love technology and enjoy sharing helpful FREE content for others to enjoy. We believe in community. If you like what we do please support us by sharing and liking our tutorials & Subscribing to our YouTube channel. You can also follow us on social media.

Support Our Work!

Donate Via Patreon

Raspberry Pi 4 Model B 8GB

Last update on 2024-06-20 / Affiliate links / Images from Amazon Product Advertising API

CanaKit Raspberry Pi 4 Extreme Kit – 128GB Edition (4GB RAM)

Last update on 2024-06-20 / Affiliate links / Images from Amazon Product Advertising API

We Are An Affiliate!

Just so you know, we may collect a share of sales or other compensation from the links on this page. As an Amazon Associate, I earn from qualifying purchases.

The affiliate link recommendations come at no extra cost to you.

We hope you love the products we recommend!

Thank you if you use our links; we really appreciate it!

Related Posts