Home Assistant

Home Assistant is an open source home automation software that puts local control and privacy first. Powered by a worldwide community of tinkerers and DIY enthusiasts.

Limited upstream support

Upstream has defined several installation methods which they are willing to support. NixOS is obviously not one of them. If you find a problem you can still report it upstream if you are certain that the issue is relevant to upstreams supported installation methods as well. If not, or if in doubt, please open an isssue on the nixpkgs issue tracker or visit us via matrix in #nixos-homeautomation:lossy.network.

Running a recent version using an overlay

Home Assistant is a fast-paced open source project, that currently features one major release every month, and a handful of minor ones in between. Firmwares and API endpoints tend to change from time to time, so Home Assistant and its bindings need to keep up to keep things work. The version we provide at the branch off is just a snapshot in time, and does not receive any updates, because there would just be too many dependencies to backport. But with NixOS it is still possible to use the version in nixpkgs/unstable by creating an overlay and using the module from nixos-unstable.

let
  # Track NixOS unstable via nix-channel, or replace it with something like niv at your own discretion
  # nix-channel --add http://nixos.org/channels/nixos-unstable nixos-unstable
  unstable = import <nixos-unstable> {};
in
{
  nixpkgs.overlays = [
    (self: super: {
      inherit (unstable) home-assistant;
    })
  ];

  disabledModules = [
    "services/misc/home-assistant.nix"
  ];

  imports = [
    <nixos-unstable/nixos/modules/services/misc/home-assistant.nix>
  ];
}

Snippets

Reverse Proxying with nginx

If you run a public Home Assistant instance it is a good idea to enable SSL/TLS. The following configuration generates a certificate using letsencrypt:

  services.home-assistant.config.http = {
    server_host = "::1";
    trusted_proxies = [ "::1" ];
    use_x_forwarded_for = true;
  };

  services.nginx = {
    recommendedProxySettings = true;
    virtualHosts."home.example.com" = {
      forceSSL = true;
      enableACME = true;
      extraConfig = ''
        proxy_buffering off;
      '';
      locations."/" = {
        proxyPass = "http://[::1]:8123";
        proxyWebsockets = true;
      };
    };
  };

Using PostgreSQL

Home Assistant supports PostgreSQL as a database backend for, among other things, its logger and history components. It's a lot more scalable and typically provides faster response times than the SQLite database, that is used by default.

Remember to make backups of your database, for Home Assistant is becoming more and more stateful and has moved away from a completely declarative YAML configuration for new and core components.

  services.home-assistant = {
    package = (pkgs.home-assistant.override {
      extraPackages = py: with py; [ psycopg2 ];
    });
    config.recorder.db_url = "postgresql://@/hass";
  };

  services.postgresql = {
    enable = true;
    ensureDatabases = [ "hass" ];
    ensureUsers = [{
      name = "hass";
      ensurePermissions = {
        "DATABASE hass" = "ALL PRIVILEGES";
      };
    }];
  };

Add custom lovelace modules

There are many useful and pretty lovelace components out there that you might want to integrate into your dashboards. Some of them are packaged up inside NUR repositories.

Usually you would install these into /var/lib/hass/www, but that comes with issues on NixOS, as their internal webserver does not follow symlinks. You could then think about exposing that directory over your webserver, but you'll notice that your webserver user has no permissions to enter the home assistant users state directory, which is due to proper hardening on the home-assistant.service.

let
  # https://nur.nix-community.org/repos/mweinelt/
  nur = import (builtins.fetchTarball "https://github.com/mweinelt/nur-packages/archive/master.tar.gz") {};

  mkLovelaceModule = name: {
    # https://www.home-assistant.io/lovelace/dashboards-and-views/#resources
    url = "/local/${name}.js?${nur.hassLovelaceModules."${name}".version}";
    type = "module";
  };
in {
  # Install lovelace components into temporary directory that can be
  # served by nginx.
  systemd.tmpfiles.rules = [
    "d /run/hass 0700 nginx nginx"
    "L+ /run/hass/mini-graph-card.js - - - - ${nur.hassLovelaceModules.mini-graph-card}/mini-graph-card-bundle.js"
    "L+ /run/hass/mini-media-player.js - - - - ${nur.hassLovelaceModules.mini-media-player}/mini-media-player-bundle.js"
    "L+ /run/hass/multiple-entity-row.js - - - - ${nur.hassLovelaceModules.multiple-entity-row}/multiple-entity-row.js"
  ];

  # Instruct home-assistant to load these resources in the lovelace frontend
  services.home-assistant.config.lovelace = {
    resources = [
      (mkLovelaceModule "mini-graph-card") # https://github.com/kalkih/mini-graph-card
      (mkLovelaceModule "mini-media-player") # https://github.com/kalkih/mini-media-player
      (mkLovelaceModule "multiple-entity-row") # https://github.com/benct/lovelace-multiple-entity-row
    ];
  };

  services.nginx.virtualHosts."home.example.com" = {
    locations."/local/" = {
      alias = "/run/hass/";
    };
  };
}

Add custom components

In order to install a custom component, you have to place it in /var/lib/hass/custom_components. This can be achieved using systemd tmpfiles like so (for sonoff custom component):

  systemd.tmpfiles.rules = [
    "C /var/lib/hass/custom_components/sonoff - - - - ${sources.sonoff-lan}/custom_components/sonoff"
    "Z /var/lib/hass/custom_components 770 hass hass - -"
  ];

Example configurations

- Mic92's config

Misc

Run Home Assistant from GitHub repository

When developing Home Assistant for some test dependencies additional libraries are needed. A nix-shell expression for this is available here.