Wireguard Container

I see Wireguard is available as an official add-on for hassio, but haven’t seen any guides on how to set it up if you are running Home Assistant Core/container/unsupervised. If you are running a supervised version of Home Assistant and can use the official addon, I would definitely recomend that route and follow the guide here - Home Assistant Community Add-on: WireGuard . If you are running a Home Assistant version without add-ons, this guide can help you still get Wireguard running along with Home Assistant.

In case you are unfamiliar with Wireguard, the program is a VPN that allows a secure VPN tunnel to your local network. More information is available here - https://www.wireguard.com/

I recently installed this program in a docker container using the image provided by Docker Hub . I also generally followed a nice video guide setup from The Digital Life - Create your own VPN server with WireGuard in Docker - YouTube

The program can easily be started by using a Docker Compose. More information on Docker and the initial setup to get docker-compose working is in the Video linked above. Prior to setting this up, you will need to use a DNS provider, like DuckDns, to linkback to your home network. I’m also using this in connection with the Swag NGINX reverse proxy, whicj has duckdns built in, and has setup instructions here Nginx Reverse Proxy Set Up Guide – Docker .

The reverse proxy will also allow secure outside access. Many will choose to run a VPN or a reverse proxy, but I’ve found it can be beneficial to run both and which services you want to access through the proxy or the VPN (or both even) will be up to you. For example, I have Home Assistant available on the reverse proxy. This will allow integrations like Smartthings, that need an accessible URL to work, and access to Home Assistant to any machine. However, I also use Portainer, and do not want to expose that over the reverse proxy since it allows config access deep into the machine. Portainer would be accessible only over the VPN. My NAS drive is also available over VPN, and if I turn VPN on with my cell or laptop on an unsecure public wifi, my connection is now secure and encrypted back to my home. To use the Wireguard VPN, you must install software on the client (phone or computer) first to access it, and set it up by scanning a bar code or importing a setting file (more on that later). While with the reverse proxy, it will be accessible from any web browser.

The docker compose for initial Wireguard setup I used is below. You will need to modify some of the variables based on your setup:

version: "2.1"
    image: ghcr.io/linuxserver/wireguard
    container_name: wireguard
      - NET_ADMIN
      - SYS_MODULE
      - PUID=1000 #replace with your UID
      - PGID=1000 #replace with your GID
      - TZ=America/New_York #use your timezone
      - SERVERURL=yourDNS.duckdns.org #replace with your DNS
      - SERVERPORT=51820 #leave or change
      - PEERS=3 #set this to the number of clients outside the network that will connect
      - PEERDNS=auto #leave this alone
      - INTERNAL_SUBNET= #leave this alone
      - ALLOWEDIPS= #leave this alone for all IPS allowed
      - /home/$user/docker/wireguard/config:/config #replace $user with your user directory. 
      - /lib/modules:/lib/modules #leave this alone
      - 51820:51820/udp #if you changed the port above change it here
      - net.ipv4.conf.all.src_valid_mark=1 #leave this alone
    restart: unless-stopped #you can do always if you prefer

A few notes on the compose:

For PUID and PGID, you need to set this to your user. It is generally 1000, but to find it just SSH into your machine running docker and type in ‘id’ on the command line. Doing this is important otherwise the files created by the container won’t belong to you - the user, and you won’t be able to access them.

I use DuckDNS which is part of the Swag container, but there are a lot of other ways to set it up, or you could use the DNS provider of your choice.

For peers, set this to the number of phones and machines you will use to access the VPN. Each phone/machine will have a unique IP and barcode/settings file.

One of the volumes will be the “persistent” directory, which is where the config files will be accessible on the host machine. You can specify this directory wherever you want on the host machine.

Once you run the docker compose by creating the file as docker-compose.yaml, and running the command docker-compose up -d, it will create the wireguard container and you can move on to the next steps:

You will need to port forward port 51820 (or whatever other port you specified in the compose) over UDP to the host running docker and Wireguard. How to do this will depend on your router.

On the “client side”, ie your remote phone or laptop, you will need to install the wireguard client program. Instructions specific to your phone or OS are available here - Installation - WireGuard and the client program is available for many different systems.

When you have the client program running, you will need to access either the barcode or config file created in the peer directory in the config directory you specified in the compose on the host machine. There will be folders labeled peer1, peer2, and so on up to the number of peers specified in the compose file. There are two options, barcode and import from file.

If using an App or device with a camera, barcode is the easiest option. The barcode will be a picture file labeled .png in the peer# folder and you just need to scan it

If using a laptop or you don’t have a camera, you’ll need to securely move the peer#.conf file from the host machine over to the client machine first (don’t send it over an unencrypted email!) to add it that way by importing.

Once running, you can access your Home Assistant and other local applications like you are at home remotely, and have some security over public wifi too.


Thanks for this.

I saw it when you first posed it but completely forgot about it until you posted a link in the other thread.

I don’t use docker compose so I converted it to a docker run command. Here it is for anyone else who might want to use it:

sudo docker run -itd --name="wireguard" --restart=unless-stopped -v /home/finity/docker/wireguard/config:/config -v /lib/modules:/lib/modules -v /etc/localtime:/etc/localtime:ro -e TZ=America/New_York -e PGID=1000 -e PUID=1000 -p 51820:51820/udp -e SERVERURL=<my_domain>.duckdns.org -e SERVERPORT=51820 -e  PEERS=3 -e PEERDNS=auto -e INTERNAL_SUBNET= -e ALLOWEDIPS= --cap-add NET_ADMIN  --cap-add SYS_MODULE --sysctl net.ipv4.conf.all.src_valid_mark=1 ghcr.io/linuxserver/wireguard

Also it wasn’t clear where to find the QR code.

It will end up being in a .png file locasted in the config directory.

they will be shown in the logs as well but I couldn’t get those to work. The png’s in the config directory worked immediately.


Thanks I updated the top post to clarify that part a bit more.

Also, if you don’t want to bother installing docker compose, but you use Portainer, you can paste the same compose into a “stack” and create the container that way.

Then just scroll to the bottom and hit “deploy stack” and portainer will create the container without needing to install docker compose separately. Run commands are fine too but they can get kind of long with all the environment variables.

1 Like

I just got new phone and got rid of the old one.

Any idea how to remove the peer for that phone so I can re-use it on another device?

My understanding is you can just reuse the old key on the new device as long as the devices don’t connect at the same time.

If it was me though, I would be paranoid someone could somehow recover the key out of the old phone, so I would want to just delete it and make a new one. According to this post, it appears you can just delete the folder of the peer the phone was using (ie if it was peer 2, delete the peer2 folder). Then, you have to change the number of peers in the environment variable (probably just add one) and recreate the container and force the peer configs to refresh- per this post Revoke/delete Wireguard peer? - Container Support - LinuxServer.io At that point, a new replacement key would be generated you can use for the new device, and the old one would be revoked.

1 Like

OK, thanks for the info.

Haven’t had a chance to try it yet, tho. Not too worried about the old phone since I factory reset it myself before I got rid of it.

Hello mwav3!

Sorry for opening this outdated post again.

I indeed followed the same approach as you did. I am running the following images in my Docker containers: Homeassistant, Duckdns and swag as the reverse proxy. I have no problems reaching my public ip address, which Duckdns translates.

Now I would like to setup a VPN tunnel to make my connection more secure! I was lucky enough to find your guide. I have followed the instructions in your guide and only have 51820 as a port forward in my router, which leads to my Docker host.

My problem now is, is that I have problems reaching my homeassistant instance through wireguard. I can successfully reach the swag instance I am running, but the homeassistance instance is not reachable. I know that it somehow works, because once I turn off wireguard, my services are not reachable anymore using my local IP address.

Could you help me with this?

Kind regards,

I would assume it’s a home assistant config problem.

Can you access Home Assistant from other machines on your lan without issues?

Is your docker version of Home Assistant using host networking mode?

Are you using the mobile app or just typing the local ip on your browser on the device your using to try ave connect?

Hey Tim, thanks for your reply!

With your comment I managed to figure out how to get it working - by waiting somehow? The logs showed that swag had problems requesting a certificate! Somehow the problem resolved itself. Thanks!