Installation

HASS-WH-Triggers is available via pip. Deployment depends on what kind of server you are going to run this on. This is a Flask application, so their deployment options may be a good resource to get started.

Static configuration options

SECRET_KEY

This key will be used by Flask to sign cookies. The value in the example config.cfg is pretty random to begin with. But since it is public (here on GitHub) it is not secure anymore. You can generate a random key with this command: python3 -c 'import os;print(os.urandom(40))'. You have to include the b'... bit at the beginning!

SQLALCHEMY_DATABASE_URI

This is where the app will look for your database. The default points to a SQLite database in /tmp/settings.db. Adjust this part according to your requirements.

RP_ID and ORIGIN

The FIDO2 authentication requires a proper configuration in terms of TLS and your systems hostname. The certificate can be self-signed, but it has to be issued for the correct hostname / FQDN. The RP_ID must be the valid domain string. The ORIGIN effectively is the URI at which the app can be accessed.

PREFIX (reverse proxy deployment)

When deploying this app behind a reverse proxy like Nginx, it might be required to pass the location of the application root when it is not at /. Practically speaking, if your Nginx configuration looks like this:

server {
  listen 8443 ssl;
  ...
  location /hass-wh-triggers/ {
    proxy_pass https://localhost:8444/;
  }
}

...set PREFIX = "/hass-wh-triggers" in your configuration file to let the app know it is not operating at the root folder.
In this example you would also have to set ORIGIN = "https://localhost:8444" - the port the app itself is listening on has to be configured in this case, not the external port Nginx is listening on.

Installation

Example installation on Windows Subsystem for Linux (Debian)

This assumes you have already installed Python 3 (including the venv module), pip (and maybe other dependencies that don't ship with the default Debian environment) and curl.

cd /tmp
mkdir hass-wh-triggers
cd hass-wh-triggers
python3 -m venv venv
source venv/bin/activate
pip install hass-wh-triggers
curl -O https://raw.githubusercontent.com/danielperna84/hass-wh-triggers/master/wsgi.py
curl -O https://raw.githubusercontent.com/danielperna84/hass-wh-triggers/master/start.sh
curl -O https://raw.githubusercontent.com/danielperna84/hass-wh-triggers/master/config.cfg
chmod 755 start.sh
# In start.sh set APP_CONFIG_FILE to /tmp/hass-wh-triggers/config.cfg
# In config.cfg set SQLALCHEMY_DATABASE_URI to 'sqlite:////tmp/hass-wh-triggers/settings.db'
# If you are running this on a publicly reachable host, set RP_ID and ORIGIN to match your hostname
./start.sh
# Now browse to your configured host (https://localhost:8443 by default) to access the application

Using Gunicorn

The method above utilizes Flasks embedded webserver. For production use it is recommended to use a real webserver to handle the connections. Gunicorn is a popular example of such a webserver. Here is how to use this application with Gunicorn using the the paths from above and a self-signed TLS certificate. The start.sh and wsgi.py are not needed in this case.

# Install gunicorn
pip install gunicorn
# Create self-signed certificate
openssl req -newkey rsa:2048 -nodes -keyout server.key -x509 -out server.crt
# Run the webserver using your customized config.cfg
APP_CONFIG_FILE=/tmp/hass-wh-triggers/config.cfg gunicorn -w 4 --bind 0.0.0.0:8443 \
hass_wh_triggers.app:app --certfile=/tmp/hass-wh-triggers/server.crt --keyfile=/tmp/hass-wh-triggers/server.key

Using Gunicorn with Systemd

This is an example unit file to run the application as a service using Systemd. In this case the virtualenv has been created in /var/www/hass-wh-triggers, which is where the config.cfg is located as well. The application itself and Gunicorn have been installed like in the example above.

Using Docker

HASS-WH-Triggers is available as a linux/amd64 image at Docker Hub with the tag danielperna84/hass-wh-triggers:latest. If you're on Linux and have docker installed, follow these steps to run the container:

mkdir config
# Create self-signed certificate for localhost or copy your own
openssl req -newkey rsa:2048 -nodes -keyout config/server.key -x509 -out config/server.crt -subj "/C=XX/ST=None/O=None/CN=localhost"
curl -o config/config.cfg https://raw.githubusercontent.com/danielperna84/hass-wh-triggers/master/config.cfg
# In config.cfg set SQLALCHEMY_DATABASE_URI to 'sqlite:////config/settings.db'
# If you are running this on a publicly reachable host, set RP_ID and ORIGIN to match your hostname
docker run --publish 8443:8443 --mount type=bind,source="$(pwd)/config",target=/config danielperna84/hass-wh-triggers:latest