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"
services:
wireguard:
image: ghcr.io/linuxserver/wireguard
container_name: wireguard
cap_add:
- NET_ADMIN
- SYS_MODULE
environment:
- 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=10.13.13.0 #leave this alone
- ALLOWEDIPS=0.0.0.0/0 #leave this alone for all IPS allowed
volumes:
- /home/$user/docker/wireguard/config:/config #replace $user with your user directory.
- /lib/modules:/lib/modules #leave this alone
ports:
- 51820:51820/udp #if you changed the port above change it here
sysctls:
- 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.
