Home Assistant

Open source home automation that puts local control and privacy first. Powered by a worldwide community of tinkerers and DIY enthusiasts. Perfect to run on a Raspberry Pi or a local server. 1


For this guide you should be familiar with the basic concepts of


Home Assistant is written in Python and licensed under the Apache License 2.0. All relevant legal information can be found here:


Your domain needs to be setup:

[isabell@stardust ~]$ uberspace web domain list
[isabell@stardust ~]$


Create a virtual environment and install packages

Install Home Assistant in a virtual environment. We’re using Python 3.11.

[isabell@stardust ~]$ mkdir ~/homeassistant
[isabell@stardust ~]$ cd ~/homeassistant
[isabell@stardust homeassistant]$ python3.11 -m venv .
[isabell@stardust homeassistant]$ source ./bin/activate
(homeassistant) [isabell@stardust homeassistant]$ python -m pip install wheel
(homeassistant) [isabell@stardust homeassistant]$ python -m pip install homeassistant
(homeassistant) [isabell@stardust homeassistant]$

First time startup

Now we can start Home Assistant for the first time in order to create all needed configuration files. Just run the following command in the created homeassistant directory with active venv.

[isabell@stardust ~]$ cd ~/homeassistant
[isabell@stardust homeassistant]$ source ./bin/activate
(homeassistant) [isabell@stardust homeassistant]$ hass
Unable to find configuration. Creating default one in /home/isabell/.homeassistant
[isabell@stardust homeassistant]$

A directory containing config files is created at /home/isabell/.homeassistant. You can now terminate the homeassistant using Ctrl-C.


Configure Home Assistant

Now it’s time to make a basic configuration. Home Assistant documentation to find out more about Home Assistant configuration.

Use an editor such as nano to edit Home Assistant’s configuration file:

[isabell@stardust ~]$ nano ~/.homeassistant/configuration.yaml

Add the following lines at the bottom of the file. Modify external_url to reflect your domain.

  name: Home
  unit_system: metric
  time_zone: Europe/Berlin
  external_url: "https://isabell.uber.space"
  internal_url: ""
  legacy_templates: false

  use_x_forwarded_for: true
    - fd00::/8

Setup a web backend


Home Assistant is running on port 8123.

To make the application accessible from the outside, configure a web backend:

[isabell@stardust ~]$ uberspace web backend set / --http --port <port>
Set backend for / to port <port>; please make sure something is listening!
You can always check the status of your backend using "uberspace web backend list".
[isabell@stardust ~]$

Create a supervisord service entry

Create ~/etc/services.d/homeassistant.ini with the following content:

command=python -m homeassistant

After creating the configuration, tell supervisord to refresh its configuration and start the service:

[isabell@stardust ~]$ supervisorctl reread
SERVICE: available
[isabell@stardust ~]$ supervisorctl update
SERVICE: added process group
[isabell@stardust ~]$ supervisorctl status
SERVICE                            RUNNING   pid 26020, uptime 0:03:14
[isabell@stardust ~]$

If it’s not in state RUNNING, check your configuration.

Finishing installation

Now Home Assistant should be running and you can point your webbrowser to the configured domain in order to make the initial homeserver setup.

Best practices


Change all default passwords. Look at folder permissions. Don’t get hacked!

And last but not least, don’t forget to check out the security checklist:



Check out the packageindex regularly to stay informed about the newest version.

Tested with homeassistant 2020.12.2, Uberspace

Written by: Dirk <https://github.com/universalappfactory/>

https://www.home-assistant.io/, 30.12.2020