Home Assistant with Docker, IPv6 and Let´s Encrypt

Install and configure on Raspberry Pi or other Linux devices

Notice

This tutorial allows you to installl Home Assistant on a Raspberry Pi (or other Linux device with small adjustments) using Docker, IPv6 and Let´s Encrypt.

After installation and configuration your Home Assistant is ready to get connected with your Google Home.

Install the system

I tested this setup on an Raspberry Pi B+ and Raspberry Pi 3 B but it should also work with every Raspberry Pi generation and also on other devices.

I decided to use Hypriot OS on my Pi because it´s based on Debian and is optimized for Docker, so I don´t need to find a compatible version that is up to date and have much less stress than using for example Raspbian.

It´s very easy to install the OS on the Raspberry Pi. Like most other systems you just need to download the image of Hypriot OS and flash it to your SD Card. I recommend you to use Etcher for flashing. It´s a nice tool for all common system that allows installing with only a bunch of clicks.

 

Download Hypriot OSDownload Etcher

Required packages

Docker comes preinstalled on Hypriot but you still need to install one additional package (6tunnel) if you wanna use the Home Assistant with IPv6. You can skip this step if you´re using IPv4 only!

Use apt-get to install 6tunnel:

 

# you must be root to update library and install packages!
sudo -i
apt-get update && apt-get install 6tunnel

IPv6 "port forwarding"

If you ever created IPv4 port forwardings before then you may faced some issues because you had only 1 public IP address that renews every 24 hours.

It´s much easier with IPv6. Every device has it´s own public IP address so you can "forward" the https port for each device without using your own creative port number. So the port "forwarding" is more exposing a port than "forwading" it but we name it forwarding though.

I recommend you to forward the https-Port only because you´ll have an Let´s Encrypt certificate so there´s no reason to use http any longer.

Up next we need a Domain because we´ll use Let´s encrypt to create a SSL-certificate. In my case I own a FRITZ!Box router that provides a free service called "MyFRITZ!". This services is like DynDNS and gives me an own subdomain for my device (see screenshot). You can use services like that or use your own domain putting an AAAA record on an subdomain.

Create/renew certificate and start Home Assistant after boot

Ok now it´s nearly done! We´ve flashed the system, installed required additional packagages and created our share (port forwarding) with a (sub)domain.

Now we´re adding a script to our autostart so the Let´s Encrypt certificate will be renewed and the Home Assistant be started on boot.

Login to the shell via ssh. If you´re a Windows user than you need an additional software to connect via ssh. In that case I recommend you to use PuTTY. If you´re using Linux or Mac than you can open the Terminal application and type the following (replace 192.168.0.42 with the IP address of your Pi):

 

ssh pirate@192.168.0.42

 

You should know the basics how to use a shell. Google for a cheat sheet or watch some tutorials if you´re really new using it.

Now we need to create folders for our docker containers and autostart script. I´m using /opt/container for.

 

mkdir -p /opt/container/home-assistant

 

I´ll also put the script for autostart into the home-assistant container folder. Let´s do this using the nano editor. Type in the following command:

 

nano /opt/container/home-assistant/start.sh

 

Then copy the code snippet below and paste it into your terminal using right click or Mac OS: CMD + V, Windows/Linux: CTRL + V, Ubuntu: CTRL + SHIFT + V:

 

#!/bin/bash
# home-assistant docker + lets encrypt + ipv6
# by crynton.com

# tunnel incoming v6 connections to v4
6tunnel -6 443 localhost 8443

# stop and remove container (to get the latest image on next run) if running
if [ "$(docker ps -q -a -f name=home-assistant)" ]; then
  docker stop home-assistant
  docker rm home-assistant
fi

# renew lets encrypt certificate
# certificates will be saved in /etc/letsencrypt/live/<domain>/
docker run -it --rm -p 8443:443 -v /etc/letsencrypt/:/etc/letsencrypt \
tobi312/rpi-certbot certonly --standalone \
--email your-mail@domain.tld -d my-forward-domain.tld \
--agree-tos -n

# start home-assistant container
# be sure to add the certificate to /config/configuration.yml as described in
# hass.io documentation
if [ ! "$(docker ps -q -a -f name=home-assistant)" ]; then
  docker run -d --name="home-assistant" -v /opt/container/home-assistant/data/config:/config \
  -v /etc/localtime:/etc/localtime:ro -v /etc/letsencrypt:/etc/letsencrypt:ro \
  --net=host homeassistant/raspberrypi3-homeassistant
else
  docker start home-assistant
fi

echo "Done!"

exit 0

 

Using a Raspberry Pi 1? Then replace homeassistant/raspberrypi3-homeassistant with homeassistant/raspberrypi-homeassistant .
Using a Raspberry PI 2? Then replace it with homeassistant/raspberrypi2-homeassistant .
Using a Raspberry Pi3? Then you can leave the defined image.

Then we need to modify the pasted content. Replace your-mail@domain.tld with your own e-mail. It will be used for notifications from Let´s Encrypt if your certificate expires (than you know there were problems renewing it). The second thing to replace is my-forward-domain.tld. Replace it with your own domain where you´ll get your port forwared Pi.

Done? Ok then save the content using: CTRL + O then ENTER then CTRL + X. Sounds complicated but is very easy.

Up next we need to grant the execution permission for our file. For that we´ll use chmod +x:

 

chmod +x /opt/container/home-assistant/start.sh

 

It´s time to modify the autostart. I´m using rc.local for that:

 

nano /etc/rc.local

 

Insert the following:

 

# start home-assistant
if [ ! "$(sh /opt/container/home-assistant/start.sh)" ]; then
  exit 1
fi

exit 0

 

Be sure that there´s only one exit 0 at the end of the file! Then save the file same as before (CTRL + O, ...).

First start and configuration of Home Assistant

Last but not least we need to configure the Home Assistant. We need to call the script manually the first time to create and boot the Let´s Encrypt and the Home Assistant Docker containers and get a basic configuration file from Home Assistant.

 

sh /opt/container/home-assistant/start.sh

 

Check your port forwarding and domain spelling in the start.sh file If an error message from Let´s Encrypt appears. And don´t forget to read error messages carefully if one (hopefully not) appear.

Wait until "Done!" appears on your screen. This can take a while.

Then we´ve to wait a little bit. On my old Raspberry Pi the Home Assistant start took about 5 minutes. You can take a look into the logs if wanna know what happens while waiting with

 

docker logs -f home-assistant

 

but you should be ok waiting 5 minutes.

Then you need to edit the Home Assistant configuration. Edit the file:

 

nano /opt/container/home-assistant/data/config/configuration.yaml

 

Use the arrow keys on your keyboard to move the text cursor. Go down to http: and change it like that:

 

http:
  # Secrets are defined in the file secrets.yaml
  base_url: my-forward-domain.tld
  api_password: MyWellSecuredPassword
  server_port: 8443
  ssl_certificate: /etc/letsencrypt/live/my-forward-domain.tld/fullchain.pem
  ssl_key: /etc/letsencrypt/live/my-forward-domain.tld/privkey.pem

 

Be sure to change the api_password to a secure one and replace my-forward-domain.tld with your own like above.

Then save the file like before with CTRL + O and so on.

 

Final test

That´s it. If everything went fine you are ready to reboot your Pi and open the Home Assitant for the first time.

Either unplug and replug your Pi OR type reboot on the shell to reboot the Pi (cleaner way).

After that you´ve to wait. It depends on which Rasperry Pi you´re using but older models can take so much time (about 5 minutes) to boot Home Assistant.

Try to call https://my-forward-domain.tld your webbrowser (replace the domain with your own) and you should see your Home Assistant with a secure connection thanks to Let´s Encrypt.

Now you´re ready to enjoy the big amount of well documented supported components from Home Assistant. Have fun :)

Any Questions?

Feel free to use the contact form if you´ve questions, problems or suggestions.