Skip to content

Home Assistant venv

Jump to bottom Edit New page
ArtMG edited this page Oct 17, 2019 · 1 revision

Install Home Assistant

This article currently focusses on a single deployment method. For others see https://github.com/artmg/MuGammaPi/wiki/home-assistant

If you start to outgrow this deployment method you can:

venv install

The Home Assistant software is written in Python 3. Once of the recommended methods of deploying it
is using a Python Virtual Environment, a neat way to avoid clashes over version dependencies.

Here are a straightforward set of instructions for installing on a clean Raspbian Stretch Lite distro, with a virtual environment set up in the folder /srv/homeassistant/.

Note that although the sudo command is used to 'become' the homeassistant user, the elevated privilege is rarely required. We simply use sudo instead of su so no user password is requested.

### Dependencies
# credit - https://www.home-assistant.io/docs/installation/raspberry-pi/
# Install Python 3 with virtual environments and installer
# v3.5.3 requires c. 60MB on Stretch Lite 
sudo apt-get install -y python3 python3-venv python3-pip

# prepare homeassistant user etc
sudo useradd -rm homeassistant -G dialout,gpio
cd /srv
sudo mkdir homeassistant
sudo chown homeassistant:homeassistant homeassistant
sudo -u homeassistant -H -s

### venv
# Now as that user activate the virtual environment
cd /srv/homeassistant
python3 -m venv .
source bin/activate
# technically speaking, as you have initiated the current venv
# with python3 you no longer need to specify 3 after python or pip

### obtain python modules
# within that venv install the software and test it
python3 -m pip install wheel

# installing this software is likely to take a few minutes
pip3 install homeassistant
# if it fails with an error (such as urlopen) it could 
# be a simple network hiccup - just retry that command

### initial install
# this will likely to take a few minutes
hass
# once you see `(MainThread)` messages it is running
# test with http:MyServer:8123
# once the installation messages stop appearing...
# break with Ctrl-C
# and `exit` from su shell

install as service

### autostart daemon
sudo tee /etc/systemd/system/[email protected] <<EOF!
[Unit]
Description=Home Assistant
After=network-online.target

[Service]
Type=simple
User=%i
# this is the command for hass in python venv
# credit https://www.home-assistant.io/docs/autostart/systemd/
ExecStart=/srv/homeassistant/bin/hass -c "/home/homeassistant/.homeassistant"

[Install]
WantedBy=multi-user.target
EOF!

sudo systemctl start home-assistant@homeassistant
sudo systemctl status home-assistant@homeassistant

http services

Clients connect to Hass via a web browser, and by default this is on port 8123

allow privileged ports

Note that this has to allow the home assistant user to attach to privileged ports (those under port 1024). Normally only root can attach to privileged ports.

# This will not work!
# sudo setcap 'cap_net_bind_service=+ep' /srv/homeassistant/bin/hass
# because it actually runs python

We chose to not use setcap to allow any python program whatsoever, but you make the choice for the security of your environment. We assume here that you are happy to trust any code run by the home assistant user to bind to listen for https.

sudo apt install -y autobind
sudo touch /etc/authbind/byport/443
sudo chown homeassistant:homeassistant /etc/authbind/byport/443
sudo chmod 755 /etc/authbind/byport/443

sudo sed -i 's\ExecStart=/srv/homeassistant\ExecStart=/usr/bin/authbind --deep /srv/homeassistant\g' /etc/systemd/system/[email protected]

If you are hesitant to allow access to any privileged ports, then consider using nginx to proxy in front of hass - see https://www.home-assistant.io/docs/ecosystem/nginx/

Alternatively you can use iptables to redirect

automatic port redirects

Redirect to default port on correct protocol and fully qualified domain name (FQDN).

sudo apt install -y nginx

DOMAIN_NAME=example.tld
PROTOCOL_PREFIX=https
WRONG_PORT1=80
WRONG_PORT2=8123

# credit https://www.home-assistant.io/docs/ecosystem/nginx_subdomain/#http-to-https-redirection
# credit https://www.reddit.com/r/nginx/comments/4hov19/redirect_from_short_name_to_fqdn/

sudo tee /etc/nginx/sites-available/default <<EOF!
server {
    listen       $WRONG_PORT1;
    server_name  _;
    return       301 $PROTOCOL_PREFIX://\$host.$DOMAIN_NAME\$request_uri;
}

server {
    listen       $WRONG_PORT1;
    server_name  *.$DOMAIN_NAME;
    return       301 $PROTOCOL_PREFIX://\$host\$request_uri;
}

server {
    listen       $WRONG_PORT2;
    server_name  _;
    return       301 $PROTOCOL_PREFIX://\$host.$DOMAIN_NAME\$request_uri;
}

server {
    listen       $WRONG_PORT2;
    server_name  *.$DOMAIN_NAME;
    return       301 $PROTOCOL_PREFIX://\$host\$request_uri;
}
EOF!

remember to switch from the default port 8123 in configuration.yaml

http: server_port: 443

Issues

Empty Response

If your browser tells you the server does not respond, it might be because you switched over to https with an ssl certificate.

If you use standard ports, you can redirect http (80) requests to https (443) by configuring a lightweight webserver to respond instead.

If you use a custom port then you simply have to remember the correct protocol to specify on the url!

misc issues

[aiohttp.access] Error in logging
asyncio/sslproto.py", line 306, in get_extra_info

Fixed in recent Python versions https://github.com/home-assistant/home-assistant/issues/9762

https certificate issues with API

requests.exceptions.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:720)

This occurred when running scenegen on server with https certs

sudo pip3 install certifi

still fails

sudo pip3 install requests[security]

requests.exceptions.SSLError: ("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')],)",)

Maintain and troubleshoot

prepare configuration for workflow

These make it easier when you are iterat

# link config/data folders back to default pi user's home
ln -s /home/homeassistant/.homeassistant/ ~/haconf
ln -s /srv/Data/ ~/hadata

# tweak permissions on folder owned by homeassistant user
cd ~/haconf
sudo chmod 777 .
sudo chmod -R 766 *
umask 11

Workflow scripts

Create the three workflow scripts you will use over and over again to pull the latest config, restart the server and check the logs for progress/errors.

cd ~/haconf

tee update-config.sh << EOF!
# updates the configuration from the repo
# and sets permissions
git stash
git pull
sudo chown homeassistant:homeassistant *
sudo chmod -R 777 .
EOF!
chmod +r update-config.sh

tee restart.sh << EOF!
sudo systemctl restart home-assistant@homeassistant
sudo systemctl status home-assistant@homeassistant
EOF!
chmod +r restart.sh

tee log-view.sh << EOF!
sudo journalctl -u [email protected]
EOF!
chmod +r log-view.sh

Check the Logs

From the front-end, you can view the Logs on the About Page:

  • open the side-bar
  • look under Developer
  • click on the last icon (i) for Info page
  • when the "About" page appears, scroll down towards the bottom

If you are logged onto the console via ssh:

sudo journalctl -u [email protected]

and if you want to capture the logs into a file add > filename onto the end. See also Workflow Scripts below for ./log-view.sh

Update HA

# first ensure the service is stopped for the upgrade
sudo systemctl stop home-assistant@homeassistant

# credit - https://www.home-assistant.io/docs/installation/raspberry-pi/#updating

sudo -u homeassistant -H -s
source /srv/homeassistant/bin/activate
# you may want to upgrade the pip version at the same time
# pip3 install --upgrade pip
pip3 install --upgrade homeassistant

# this will begin the download and upgrade process
# which may take a few minutes

# although you could restart the service now, you might prefer 
# to run it in the console first time to check for errors
hass

# break with Ctrl-C once the installation messages stop appearing


# quit the virtual environment
exit

For other options, such as downgrading to a specific version, or upgrading to the beta or head, see https://www.home-assistant.io/docs/installation/virtualenv/#run-a-specific-version

Upgrade Python

You may be interested to know that Raspbian's Python package versions lag behind the latest available for download from python.org. You may instead choose to download and build the latest version by following instructions such as below:

NB: for python 3.7 - depends: add libffi-dev Also use the make option: `make -j4 # use 4 cores = much faster``

Alternatively you could use conda (not sure if 3.7 is there yet?)

  • install in user (not sudo)
  • add the rpi channel conda config --add channels rpi
  • install it precompiled conda install python=3.6
  • you can even use conda to manage your environments conda create -n hass python=3.6 that you then source activate hass

create new venv

Once you have upgraded the Python version you must then create a new virtual environment using this newer Python version.

# credit https://community.home-assistant.io/t/you-just-won-the-lottery-how-do-you-build-the-most-stable-ha-server/50762/9

# stop the service so it can't interfere
sudo service home-assistant@homeassistant stop
# save the old environment
sudo mv /srv/homeassistant{,.`date +%y%m%d`}
# permission a folder for the new one
sudo mkdir /srv/homeassistant
sudo chown homeassistant:homeassistant /srv/homeassistant

# go into the user context ready to set up the new venv
sudo -u homeassistant -H -s

# check which versions are installed
ls -la /usr/bin/python*
# and choose the APPROPRIATE VERSION below

# use the version you want to create the venv 
# this may take a minute or three
python3 -m venv /srv/homeassistant
# now activate it
source /srv/homeassistant/bin/activate

# test the version
# in the venv the major version is set automatically
python --version
pip --version

# you may want to upgrade the pip version at the same time
pip install --upgrade pip

pip install homeassistant
hass

This method is less time consuming and more reliable than a previously used method of freezing the requirements.txt file as described in https://community.home-assistant.io/t/python-3-6-upgrade-of-a-virtualenv/21722

Upgrade Raspbian

Very occasionally you may come across an issue that requires you to upgrade your whole OS to a new version of Raspbian. It takes quite a while, but is pretty straightforward, and is usually far less effort than reinstalling afresh.

# change e.g. from stretch to buster
sudo editor /etc/apt/sources.list
sudo editor /etc/apt/sources.list.d/raspi.list
sudo apt update

# do the upgrade
sudo apt dist-upgrade
# alternatively if you want it to be totally hands off...
# this leaves old configs you had changed as they were
# DEBIAN_FRONTEND=noninteractive sudo apt-get -o Dpkg::Options::=--force-confold -o Dpkg::Options::=--force-confdef -y --allow-downgrades --allow-remove-essential --allow-change-held-packages dist-upgrade
# credit https://stackoverflow.com/a/55043303

sudo apt autoremove
sudo apt list --installed

As the Python version is likely to have been upgraded, you should follow instructions above to recreate the venv.

Advanced configuration

Data onto USB

In order to make the device more resilient by reducing the probability of drive failure on the main OS microSD card, we can move the recorder database onto a USB flash drive instead.

  • (Moving database to USB)[http://blog.ceard.tech/2017/10/home-assistant-moving-logs-and-database.html]

You can also move (and trim) the log file too, not by using the logger: in configuration.yaml, but with command line options.

with MySQL

Also, perhaps using MySql instead might help with resilience?

  • (using MySql for Recorder)[https://www.home-assistant.io/components/recorder/#custom-database-engines]
# check where mysql cnf file could be
mysql --help | grep "Default options" -A 1 
# now edit it
datadir=
# use a sed to change this?
  • Later could consider using influx db instead, although there may be a HA component (on its way to help with that)[https://community.home-assistant.io/t/64399].
Add a custom footer
Add a custom sidebar
Clone this wiki locally