Edit 19 Jan 2024
I wrote this back in 2001 and was thinking was an update required but I am glad to know that people have reported this is still valid.
You shouldn’t have to wade through everybodies comments to get things working.
Often, people report that their connection is reported by the browser as unsafe. I think this is caused by the Let’s encrypt certificate limits. I wait and it eventually goes away. If necessary, read this, but I stick with Letsencrypt.
As remote access exposes your machine to the outside world, security worried me.
The solution I use is something called Crowdsec. I started to write a guide, but didn’t feel satisfied with it as I couldn’t properly summarise what was going on. In brief it can analyse logs (both linux and home assistant) , checks suspicious behaviour and blocks it. Attackers are reported to a central server and your system recieves and blocks the crowdsourced attackers. The linuxserver.io guide provides detailed explanations.
Introduction
For those of us who can’t ( or don’t want to) run the supervised system, getting remote access to Home Assistant without the add-ons seemed to be a nightmare.
But there is real simple way to get everything done, including Letsencrypt, NGINX, certificate renewal, duckdns, security etc.
It is a docker package called SWAG and it includes a sample home assistant configuration file that only need a few tweaks.
A basic understanding of Docker is presumed and Docker-Compose is installed on your machine.
The configuration is minimal so you can get the test system working very quickly. After that, it should be easy to modify your existing configuration.
Rather than upset your production system, I suggest you create a test directory; /home/user/test.
Also, create the data volumes so that you own them;
/home/user/volumes/hass
/home/user/volumes/swag
1) Port Forwarding
Forward ports 80 and 443 through your router to ports 80 and 443 on your server.
No need to forward port 8123
2) DuckDNS
Set up a Duckdns account. This is simple and fully explained on their web site.
Keep a record of “your-domain” and “your-access-token”.
3) docker-compose.yml
The config below is the basic for home assistant and swag.
The first service is standard home assistant container configuration.
Note that Network mode is “host” which now means Docker port mapping is not allowwed; I comment them out.
The second service is swag.
Since docker creates some files as root, you will need your PUID & GUID; just use the Unix command ‘id’ to find these.
Change your duckdns info.
The third part fixes the docker network so it can be trusted by HA.
version: "3"
services:
hass:
container_name: hass
image: homeassistant/home-assistant
volumes:
- /home/USER/volumes/hass:/config
- /etc/localtime:/etc/localtime:ro
# ports:
# - 8123:8123
network_mode: host
restart: unless-stopped
swag:
image: ghcr.io/linuxserver/swag
container_name: swag
cap_add:
- NET_ADMIN
environment:
- PUID=1001
- PGID=1001
- TZ=Europe/Paris
- URL=YOUR-DOMAIN.duckdns.org
- VALIDATION=duckdns
- DUCKDNSTOKEN=YOUR-TOKEN
- SUBDOMAINS=wildcard
volumes:
- /home/USER/volumes/swag:/config
# ports:
# - 443:443
# - 80:80
restart: unless-stopped
# set trusted docker internal network
networks:
default:
ipam:
config:
- subnet: 172.10.0.0/24
4) Set up SWAG
Run
docker-compose up swag
This will down load the swag image, create the swag volume, unpack and set up the default configuration.
It takes a some time to generate the certificates etc
If all goes well, it should end with
swag | [services.d] starting services
swag | [services.d] done.
swag | Server ready.
Use ctrl-c to stop docker gracefully.
5) Set up Homeassistant
Run
docker-compose up homeassistant
When it is done, use ctrl-c to stop docker gracefully.
6) SWAG configuration for Homeassistant
The SWAG container contains a standard (NGINX) configuration sample file for home assistant;
homeassistant.subdomain.conf.sample
Rename it to
homeassistant.subdomain.conf
Note: It is found in /home/user/test/volumes/swag/nginx/proxy-confs/
Normally, docker would know the IP address of homeassistant, but since we use ‘net mode’, the IP address of your server needs to be given in two places:
set $upstream_app homeassistant;
to your host IP address
set $upstream_app 192.168.X.XXX;
This is the homeassistant.subdomain.conf file (with all #comments removed for clarity)
server {
listen 443 ssl;
listen [::]:443 ssl;
server_name homeassistant.*;
include /config/nginx/ssl.conf;
client_max_body_size 0;
location / {
include /config/nginx/proxy.conf;
include /config/nginx/resolver.conf;
set $upstream_app 192.168.XX.XXX;
set $upstream_port 8123;
set $upstream_proto http;
proxy_pass $upstream_proto://$upstream_app:$upstream_port;
}
location /api {
include /config/nginx/proxy.conf;
include /config/nginx/resolver.conf;
set $upstream_app 192.168.XX.XXX;
set $upstream_port 8123;
set $upstream_proto http;
proxy_pass $upstream_proto://$upstream_app:$upstream_port;
}
}
7) HA config.yaml
We need to keep our ip address in duckdns uptodate. ( Note: SWAG will do this and it is not really necessary to ask home assistant to do it aswell)
Add the following to you home assistant config.yaml ( /home/user/test/volumes/hass/configuration.yaml)
Adjust for your local lan network and duckdns info
http:
ip_ban_enabled: true
login_attempts_threshold: 3
use_x_forwarded_for: true
trusted_proxies:
- 192.168.X.0/24 # Local Lan
- 172.10.0.0/24 # Docker network
duckdns:
domain: "YOUR-DOMAIN"
access_token: "YOUR-TOKEN"
Note: If you use Crowdsec security, the ip_ban_ enabled should be false or you won’t be reporting attackers.
8) Finally-Test it is working
Launch homeassistant and swag
docker-compose up -d
Wait a little.
Then, use your browser to logon from your local network 192.168.X.XXX:8123 and you should get your normal home assistant login.
Finally, use your browser to logon from outside your home
https://homeassistant.YOUR-SUB-DOMAIN.duckdns.org
Note: unless your router supports ’ loopback’ ( and mine didn’t) you might not be able to connect; in that case use a telephone ( or tor browser) rather than your local LAN connection.
That’s it. You have remote access to home assistant.
Footnotes:
You must include homeassistant in the address when you connect.
If you use just https://
YOUR-SUB-DOMAIN.duckdns.org ( which defaults to https://www.YOUR-SUB-DOMAIN.duckdns.org ), you will get taken to the default SWAG web page of your server.
Thanks, yes no need to forward port 80. l wasn’t quite sure, so I left in in