422 lines
14 KiB
Markdown
422 lines
14 KiB
Markdown
# Home-Assistant Service {#services-home-assistant}
|
|
|
|
Defined in [`/modules/services/home-assistant.nix`](@REPO@/modules/services/home-assistant.nix).
|
|
|
|
This NixOS module is a service that sets up a [Home-Assistant](https://www.home-assistant.io/) instance.
|
|
|
|
Compared to the stock module from nixpkgs,
|
|
this one sets up, in a fully declarative manner
|
|
LDAP and SSO integration.
|
|
|
|
## Features {#services-home-assistant-features}
|
|
|
|
- Declarative creation of users, admin or not.
|
|
- Also declarative [LDAP](#services-home-assistant-options-shb.home-assistant.ldap) Configuration. [Manual](#services-home-assistant-usage-ldap).
|
|
- Access through [subdomain](#services-home-assistant-options-shb.home-assistant.subdomain) using reverse proxy. [Manual](#services-home-assistant-usage-configuration).
|
|
- Access through [HTTPS](#services-home-assistant-options-shb.home-assistant.ssl) using reverse proxy. [Manual](#services-home-assistant-usage-configuration).
|
|
- [Backup](#services-home-assistant-options-shb.home-assistant.backup) through the [backup block](./blocks-backup.html). [Manual](#services-home-assistant-usage-backup).
|
|
- Integration with the [dashboard contract](contracts-dashboard.html) for displaying user facing application in a dashboard. [Manual](#services-home-assistant-usage-applicationdashboard)
|
|
|
|
- Not yet: declarative SSO.
|
|
|
|
## Usage {#services-home-assistant-usage}
|
|
|
|
### Initial Configuration {#services-home-assistant-usage-configuration}
|
|
|
|
The following snippet enables Home-Assistant and makes it available under the `ha.example.com` endpoint.
|
|
|
|
```nix
|
|
shb.home-assistant = {
|
|
enable = true;
|
|
subdomain = "ha";
|
|
domain = "example.com";
|
|
|
|
config = {
|
|
name = "SelfHostBlocks - Home Assistant";
|
|
country.source = config.shb.sops.secret."home-assistant/country".result.path;
|
|
latitude.source = config.shb.sops.secret."home-assistant/latitude_home".result.path;
|
|
longitude.source = config.shb.sops.secret."home-assistant/longitude_home".result.path;
|
|
time_zone.source = config.shb.sops.secret."home-assistant/time_zone".result.path;
|
|
unit_system = "metric";
|
|
};
|
|
};
|
|
|
|
shb.sops.secret."home-assistant/country".request = {
|
|
mode = "0440";
|
|
owner = "hass";
|
|
group = "hass";
|
|
restartUnits = [ "home-assistant.service" ];
|
|
};
|
|
shb.sops.secret."home-assistant/latitude_home".request = {
|
|
mode = "0440";
|
|
owner = "hass";
|
|
group = "hass";
|
|
restartUnits = [ "home-assistant.service" ];
|
|
};
|
|
shb.sops.secret."home-assistant/longitude_home".request = {
|
|
mode = "0440";
|
|
owner = "hass";
|
|
group = "hass";
|
|
restartUnits = [ "home-assistant.service" ];
|
|
};
|
|
shb.sops.secret."home-assistant/time_zone".request = {
|
|
mode = "0440";
|
|
owner = "hass";
|
|
group = "hass";
|
|
restartUnits = [ "home-assistant.service" ];
|
|
};
|
|
```
|
|
|
|
This assumes secrets are setup with SOPS
|
|
as mentioned in [the secrets setup section](usage.html#usage-secrets) of the manual.
|
|
|
|
Any item in the `config` can be passed a secret, which means it will not appear
|
|
in the `/nix/store` and instead be added to the config file out of band, here using sops.
|
|
To do that, append `.source` to the settings name and give it the path to the secret.
|
|
|
|
I advise using secrets to set personally identifiable information,
|
|
like shown in the snippet. Especially if you share your repository publicly.
|
|
|
|
### Home-Assistant through HTTPS {#services-home-assistant-usage-https}
|
|
|
|
:::: {.note}
|
|
We will build upon the [Initial Configuration](#services-home-assistant-usage-configuration) section,
|
|
so please follow that first.
|
|
::::
|
|
|
|
If the `shb.ssl` block is used (see [manual](blocks-ssl.html#usage) on how to set it up),
|
|
the instance will be reachable at `https://ha.example.com`.
|
|
|
|
Here is an example with Let's Encrypt certificates, validated using the HTTP method.
|
|
First, set the global configuration for your domain:
|
|
|
|
```nix
|
|
shb.certs.certs.letsencrypt."example.com" = {
|
|
domain = "example.com";
|
|
group = "nginx";
|
|
reloadServices = [ "nginx.service" ];
|
|
adminEmail = "myemail@mydomain.com";
|
|
};
|
|
```
|
|
|
|
Then you can tell Home-Assistant to use those certificates.
|
|
|
|
```nix
|
|
shb.certs.certs.letsencrypt."example.com".extraDomains = [ "ha.example.com" ];
|
|
|
|
shb.home-assistant = {
|
|
ssl = config.shb.certs.certs.letsencrypt."example.com";
|
|
};
|
|
```
|
|
|
|
### With LDAP Support {#services-home-assistant-usage-ldap}
|
|
|
|
:::: {.note}
|
|
We will build upon the [HTTPS](#services-home-assistant-usage-https) section,
|
|
so please follow that first.
|
|
::::
|
|
|
|
We will use the [LLDAP block][] provided by Self Host Blocks.
|
|
Assuming it [has been set already][LLDAP block setup], add the following configuration:
|
|
|
|
[LLDAP block]: blocks-lldap.html
|
|
[LLDAP block setup]: blocks-lldap.html#blocks-lldap-global-setup
|
|
|
|
```nix
|
|
shb.home-assistant.ldap
|
|
enable = true;
|
|
host = "127.0.0.1";
|
|
port = config.shb.lldap.webUIListenPort;
|
|
userGroup = "homeassistant_user";
|
|
};
|
|
```
|
|
|
|
And that's it.
|
|
Now, go to the LDAP server at `http://ldap.example.com`,
|
|
create the `home-assistant_user` group,
|
|
create a user and add it to one or both groups.
|
|
When that's done, go back to the Home-Assistant server at
|
|
`http://home-assistant.example.com` and login with that user.
|
|
|
|
### With SSO Support {#services-home-assistant-usage-sso}
|
|
|
|
:::: {.warning}
|
|
This is not implemented yet. Any contributions ([issue #12](https://github.com/ibizaman/selfhostblocks/issues/12)) are welcomed!
|
|
::::
|
|
|
|
### Backup {#services-home-assistant-usage-backup}
|
|
|
|
Backing up Home-Assistant using the [Restic block](blocks-restic.html) is done like so:
|
|
|
|
```nix
|
|
shb.restic.instances."home-assistant" = {
|
|
request = config.shb.home-assistant.backup;
|
|
settings = {
|
|
enable = true;
|
|
};
|
|
};
|
|
```
|
|
|
|
The name `"home-assistant"` in the `instances` can be anything.
|
|
The `config.shb.home-assistant.backup` option provides what directories to backup.
|
|
You can define any number of Restic instances to backup Home-Assistant multiple times.
|
|
|
|
You will then need to configure more options like the `repository`,
|
|
as explained in the [restic](blocks-restic.html) documentation.
|
|
|
|
### Application Dashboard {#services-home-assistant-usage-applicationdashboard}
|
|
|
|
Integration with the [dashboard contract](contracts-dashboard.html) is provided
|
|
by the [dashboard option](#services-home-assistant-options-shb.home-assistant.dashboard).
|
|
|
|
For example using the [Homepage](services-homepage.html) service:
|
|
|
|
```nix
|
|
{
|
|
shb.homepage.servicesGroups.Home.services.HomeAssistant = {
|
|
sortOrder = 1;
|
|
dashboard.request = config.shb.home-assistant.dashboard.request;
|
|
settings.icon = "si-homeassistant";
|
|
};
|
|
}
|
|
```
|
|
|
|
The icon needs to be set manually otherwise it is not displayed correctly.
|
|
|
|
An API key can be set to show extra info:
|
|
|
|
```nix
|
|
{
|
|
shb.homepage.servicesGroups.Home.services.HomeAssistant = {
|
|
apiKey.result = config.shb.sops.secret."home-assistant/homepageApiKey".result;
|
|
};
|
|
|
|
shb.sops.secret."home-assistant/homepageApiKey".request =
|
|
config.shb.homepage.servicesGroups.Home.services.HomeAssistant.apiKey.request;
|
|
}
|
|
```
|
|
|
|
Custom widgets can be set using Home Assistant templating:
|
|
|
|
```nix
|
|
{
|
|
shb.homepage.servicesGroups.Home.services.HomeAssistant = {
|
|
settings.widget.custom = [
|
|
{
|
|
template = "{{ states('sensor.power_consumption_power_consumption', with_unit=True, rounded=True) }}";
|
|
label = "energy now";
|
|
}
|
|
{
|
|
state = "sensor.power_consumption_daily_power_consumption";
|
|
label = "energy today";
|
|
}
|
|
];
|
|
};
|
|
}
|
|
```
|
|
|
|
### Extra Components {#services-home-assistant-usage-extra-components}
|
|
|
|
Packaged components can be found in the documentation of the corresponding option
|
|
[services.home-assistant.extraComponents](https://search.nixos.org/options?channel=25.05&show=services.home-assistant.extraComponents&from=0&size=50&sort=relevance&type=packages&query=services.home-assistant.extraComponents)
|
|
|
|
[services.home-assistant-extraComponents]: https://search.nixos.org/options?channel=25.05&show=services.home-assistant.extraComponents&from=0&size=50&sort=relevance&type=packages&query=services.home-assistant.extraComponents
|
|
|
|
When you find an interesting one add it to the option:
|
|
|
|
```bash
|
|
services.home-assistant.extraComponents = [
|
|
"backup"
|
|
"bluetooth"
|
|
"esphome"
|
|
|
|
"assist_pipeline"
|
|
"conversation"
|
|
"piper"
|
|
"wake_word"
|
|
"whisper"
|
|
"wyoming"
|
|
];
|
|
```
|
|
|
|
Some components are not available as extra components, but need to be added as cusotm components.
|
|
If the component is not packaged, you'll need to use a [custom component](#services-home-assistant-usage-custom-components).
|
|
|
|
### Custom Components {#services-home-assistant-usage-custom-components}
|
|
|
|
:::: {.note}
|
|
I'm still confused for why is there a difference between custom components and extra components.
|
|
::::
|
|
|
|
Available custom components can be found by searching packages for [home-assistant-custom-components][].
|
|
|
|
[home-assistant-custom-components]: https://search.nixos.org/packages?channel=25.05&from=0&size=50&sort=alpha_asc&type=packages&query=home-assistant-custom-components
|
|
|
|
Add them like so:
|
|
|
|
```nix
|
|
services.home-assistant.customComponents = with pkgs.home-assistant-custom-components; [
|
|
adaptive_lighting
|
|
];
|
|
```
|
|
|
|
To add a not packaged component, you can get inspiration from existing [packaged components.
|
|
To help you package a custom component [nixpkgs code][component-packages.nix] to package it
|
|
using the `pkgs.buildHomeAssistantComponent` function.
|
|
|
|
[component-packages.nix]: https://github.com/NixOS/nixpkgs/blob/master/pkgs/servers/home-assistant/component-packages.nix
|
|
|
|
When done, add it to the same `services.home-assistant.customComponents` option.
|
|
Also, don't hesitate to upstream it to nixpkgs.
|
|
|
|
### Custom Lovelace Modules {#services-home-assistant-usage-custom-lovelace-modules}
|
|
|
|
To add custom Lovelace UI elements, add them to the `services.home-assistant.customLovelaceModules` option.
|
|
Available custom components can be found by searching packages for [home-assistant-custom-lovelace-modules][].
|
|
|
|
[home-assistant-custom-lovelace-modules]: https://search.nixos.org/packages?channel=25.05&from=0&size=50&sort=alpha_asc&type=packages&query=home-assistant-custom-lovelace-modules
|
|
|
|
```nix
|
|
services.home-assistant.customLovelaceModules = with pkgs.home-assistant-custom-lovelace-modules; [
|
|
mini-graph-card
|
|
mini-media-player
|
|
hourly-weather
|
|
weather-card
|
|
];
|
|
```
|
|
|
|
### Extra Packages {#services-home-assistant-usage-extra-packages}
|
|
|
|
This is really only needed if by mischance, one of the components added earlier
|
|
fail because of a missing Python3 package when the home-assistant systemd service is started.
|
|
Usually, the required module will be shown in the traceback.
|
|
To know to which nixpkgs package this Python3 package correspond,
|
|
search for a package in the [python3XXPackages set][].
|
|
|
|
[python3XXPackages set]: https://search.nixos.org/packages?channel=25.05&from=0&size=50&buckets=%7B%22package_attr_set%22%3A%5B%22python313Packages%22%5D%2C%22package_license_set%22%3A%5B%5D%2C%22package_maintainers_set%22%3A%5B%5D%2C%22package_teams_set%22%3A%5B%5D%2C%22package_platforms%22%3A%5B%5D%7D&sort=alpha_asc&type=packages&query=grpcio
|
|
|
|
```nix
|
|
services.home-assistant.extraPackages = python3Packages: with python3Packages; [
|
|
grpcio
|
|
];
|
|
```
|
|
|
|
### Extra Groups {#services-home-assistant-usage-extra-groups}
|
|
|
|
Some components need access to hardware components which mean the home-assistant user
|
|
`hass` must be added to some Unix group.
|
|
For example, the `hass` user must be added to the `dialout` group for the Sonoff component.
|
|
|
|
There's no systematic way to know this apart reading the logs when a
|
|
home-assistant component fails to start.
|
|
|
|
```nix
|
|
users.users.hass.extraGroups = [ "dialout" ];
|
|
```
|
|
|
|
### Voice {#services-home-assistant-usage-voice}
|
|
|
|
Text to speech (TTS) and speech to text (STT) can be added with the
|
|
stock nixpkgs options. The most performance hungry one is STT.
|
|
If you don't have a good CPU or better a GPU, you won't be able
|
|
to use medium to big models. From my own experience using a low-end
|
|
CPU, voice is pretty much unusable like that, even with mini models.
|
|
|
|
Here is the configuration I use on a low-end CPU:
|
|
|
|
```nix
|
|
shb.home-assistant.voice.text-to-speech = {
|
|
"fr" = {
|
|
enable = true;
|
|
voice = "fr-siwis-medium";
|
|
uri = "tcp://0.0.0.0:10200";
|
|
speaker = 0;
|
|
};
|
|
"en" = {
|
|
enable = true;
|
|
voice = "en_GB-alba-medium";
|
|
uri = "tcp://0.0.0.0:10201";
|
|
speaker = 0;
|
|
};
|
|
};
|
|
shb.home-assistant.voice.speech-to-text = {
|
|
"tiny-fr" = {
|
|
enable = true;
|
|
model = "base-int8";
|
|
language = "fr";
|
|
uri = "tcp://0.0.0.0:10300";
|
|
device = "cpu";
|
|
};
|
|
"tiny-en" = {
|
|
enable = true;
|
|
model = "base-int8";
|
|
language = "en";
|
|
uri = "tcp://0.0.0.0:10301";
|
|
device = "cpu";
|
|
};
|
|
};
|
|
systemd.services.wyoming-faster-whisper-tiny-en.environment."HF_HUB_CACHE" = "/tmp";
|
|
systemd.services.wyoming-faster-whisper-tiny-fr.environment."HF_HUB_CACHE" = "/tmp";
|
|
shb.home-assistant.voice.wakeword = {
|
|
enable = true;
|
|
uri = "tcp://127.0.0.1:10400";
|
|
preloadModels = [
|
|
"ok_nabu"
|
|
];
|
|
};
|
|
```
|
|
|
|
### Music Assistant {#services-home-assistant-usage-music-assistant}
|
|
|
|
To add Music Assistant under the `ma.example.com` domain
|
|
with two factor SSO authentication, use the following configuration.
|
|
This assumes the [SSL][] and [SSO][] blocks are configured.
|
|
|
|
[SSL]: blocks-ssl.html
|
|
[SSO]: blocks-sso.html
|
|
|
|
```nix
|
|
services.music-assistant = {
|
|
enable = true;
|
|
providers = [
|
|
"airplay"
|
|
"hass"
|
|
"hass_players"
|
|
"jellyfin"
|
|
"radiobrowser"
|
|
"sonos"
|
|
"spotify"
|
|
];
|
|
};
|
|
|
|
shb.nginx.vhosts = [
|
|
{
|
|
subdomain = "ma";
|
|
domain = "example.com";
|
|
ssl = config.shb.certs.certs.letsencrypt.${domain};
|
|
authEndpoint = "https://${config.shb.authelia.subdomain}.${config.shb.authelia.domain}";
|
|
upstream = "http://127.0.0.1:8095";
|
|
autheliaRules = [{
|
|
domain = "ma.${domain}";
|
|
policy = "two_factor";
|
|
subject = ["group:music-assistant_user"];
|
|
}];
|
|
}
|
|
];
|
|
```
|
|
|
|
## Debug {#services-home-assistant-debug}
|
|
|
|
In case of an issue, check the logs for systemd service `home-assistant.service`.
|
|
|
|
Enable verbose logging by setting the `shb.home-assistant.debug` boolean to `true`.
|
|
|
|
Access the database with `sudo -u home-assistant psql`.
|
|
|
|
## Options Reference {#services-home-assistant-options}
|
|
|
|
```{=include=} options
|
|
id-prefix: services-home-assistant-options-
|
|
list-id: selfhostblocks-service-home-assistant-options
|
|
source: @OPTIONS_JSON@
|
|
```
|