add documentation for home-assistant
This commit is contained in:
ibizaman
parent
547817d0c9
commit
8dcee5cd2d
5 changed files with 586 additions and 11 deletions
|
|
@ -163,6 +163,11 @@ in stdenv.mkDerivation {
|
||||||
'@OPTIONS_JSON@' \
|
'@OPTIONS_JSON@' \
|
||||||
${individualModuleOptionsDocs [ ../modules/blocks/sops.nix ]}/share/doc/nixos/options.json
|
${individualModuleOptionsDocs [ ../modules/blocks/sops.nix ]}/share/doc/nixos/options.json
|
||||||
|
|
||||||
|
substituteInPlace ./modules/services/home-assistant/docs/default.md \
|
||||||
|
--replace \
|
||||||
|
'@OPTIONS_JSON@' \
|
||||||
|
${individualModuleOptionsDocs [ ../modules/services/home-assistant.nix ]}/share/doc/nixos/options.json
|
||||||
|
|
||||||
substituteInPlace ./modules/services/nextcloud-server/docs/default.md \
|
substituteInPlace ./modules/services/nextcloud-server/docs/default.md \
|
||||||
--replace \
|
--replace \
|
||||||
'@OPTIONS_JSON@' \
|
'@OPTIONS_JSON@' \
|
||||||
|
|
|
||||||
|
|
@ -1028,6 +1028,9 @@
|
||||||
"native-prometheus-metrics": [
|
"native-prometheus-metrics": [
|
||||||
"service-implementation-guide.html#native-prometheus-metrics"
|
"service-implementation-guide.html#native-prometheus-metrics"
|
||||||
],
|
],
|
||||||
|
"next-steps": [
|
||||||
|
"index.html#next-steps"
|
||||||
|
],
|
||||||
"nixpkgs-integration": [
|
"nixpkgs-integration": [
|
||||||
"service-implementation-guide.html#nixpkgs-integration"
|
"service-implementation-guide.html#nixpkgs-integration"
|
||||||
],
|
],
|
||||||
|
|
@ -1364,6 +1367,165 @@
|
||||||
"services-forgejo-usage-sso": [
|
"services-forgejo-usage-sso": [
|
||||||
"services-forgejo.html#services-forgejo-usage-sso"
|
"services-forgejo.html#services-forgejo-usage-sso"
|
||||||
],
|
],
|
||||||
|
"services-home-assistant": [
|
||||||
|
"services-home-assistant.html#services-home-assistant"
|
||||||
|
],
|
||||||
|
"services-home-assistant-debug": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-debug"
|
||||||
|
],
|
||||||
|
"services-home-assistant-features": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-features"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.backup": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.backup"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.backup.request": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.backup.request"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.backup.request.excludePatterns": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.backup.request.excludePatterns"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.backup.request.hooks": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.backup.request.hooks"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.backup.request.hooks.afterBackup": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.backup.request.hooks.afterBackup"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.backup.request.hooks.beforeBackup": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.backup.request.hooks.beforeBackup"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.backup.request.sourceDirectories": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.backup.request.sourceDirectories"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.backup.request.user": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.backup.request.user"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.backup.result": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.backup.result"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.backup.result.backupService": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.backup.result.backupService"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.backup.result.restoreScript": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.backup.result.restoreScript"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.config": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.config"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.config.country": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.config.country"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.config.latitude": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.config.latitude"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.config.longitude": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.config.longitude"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.config.name": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.config.name"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.config.time_zone": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.config.time_zone"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.config.unit_system": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.config.unit_system"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.domain": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.domain"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.enable": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.enable"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.ldap": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.ldap"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.ldap.enable": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.ldap.enable"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.ldap.host": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.ldap.host"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.ldap.keepDefaultAuth": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.ldap.keepDefaultAuth"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.ldap.port": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.ldap.port"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.ldap.userGroup": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.ldap.userGroup"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.ssl": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.ssl"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.ssl.paths": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.ssl.paths"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.ssl.paths.cert": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.ssl.paths.cert"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.ssl.paths.key": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.ssl.paths.key"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.ssl.systemdService": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.ssl.systemdService"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.subdomain": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.subdomain"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.voice": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.voice"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.voice.speech-to-text": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.voice.speech-to-text"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.voice.text-to-speech": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.voice.text-to-speech"
|
||||||
|
],
|
||||||
|
"services-home-assistant-options-shb.home-assistant.voice.wakeword": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-options-shb.home-assistant.voice.wakeword"
|
||||||
|
],
|
||||||
|
"services-home-assistant-usage": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-usage"
|
||||||
|
],
|
||||||
|
"services-home-assistant-usage-backup": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-usage-backup"
|
||||||
|
],
|
||||||
|
"services-home-assistant-usage-configuration": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-usage-configuration"
|
||||||
|
],
|
||||||
|
"services-home-assistant-usage-custom-components": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-usage-custom-components"
|
||||||
|
],
|
||||||
|
"services-home-assistant-usage-custom-lovelace-modules": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-usage-custom-lovelace-modules"
|
||||||
|
],
|
||||||
|
"services-home-assistant-usage-extra-components": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-usage-extra-components"
|
||||||
|
],
|
||||||
|
"services-home-assistant-usage-extra-groups": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-usage-extra-groups"
|
||||||
|
],
|
||||||
|
"services-home-assistant-usage-extra-packages": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-usage-extra-packages"
|
||||||
|
],
|
||||||
|
"services-home-assistant-usage-https": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-usage-https"
|
||||||
|
],
|
||||||
|
"services-home-assistant-usage-ldap": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-usage-ldap"
|
||||||
|
],
|
||||||
|
"services-home-assistant-usage-music-assistant": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-usage-music-assistant"
|
||||||
|
],
|
||||||
|
"services-home-assistant-usage-sso": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-usage-sso"
|
||||||
|
],
|
||||||
|
"services-home-assistant-usage-voice": [
|
||||||
|
"services-home-assistant.html#services-home-assistant-usage-voice"
|
||||||
|
],
|
||||||
"services-nextcloudserver": [
|
"services-nextcloudserver": [
|
||||||
"services-nextcloud.html#services-nextcloudserver"
|
"services-nextcloud.html#services-nextcloudserver"
|
||||||
],
|
],
|
||||||
|
|
|
||||||
|
|
@ -381,6 +381,16 @@ source: @OPTIONS_JSON@
|
||||||
|
|
||||||
Note: Replace `servicename` with your actual service name (e.g., `nzbget`, `jellyfin`).
|
Note: Replace `servicename` with your actual service name (e.g., `nzbget`, `jellyfin`).
|
||||||
|
|
||||||
|
For the `@OPTIONS_JSON@` to work, the following snippet must be added
|
||||||
|
in the `docs/default.nix` file.
|
||||||
|
|
||||||
|
```nix
|
||||||
|
substituteInPlace ./modules/services/servicename/docs/default.md \
|
||||||
|
--replace \
|
||||||
|
'@OPTIONS_JSON@' \
|
||||||
|
${individualModuleOptionsDocs [ ../modules/services/servicename.nix ]}/share/doc/nixos/options.json
|
||||||
|
```
|
||||||
|
|
||||||
### 7. Update Redirects Automatically {#update-redirects-automatically}
|
### 7. Update Redirects Automatically {#update-redirects-automatically}
|
||||||
|
|
||||||
After creating documentation, generate the required redirects:
|
After creating documentation, generate the required redirects:
|
||||||
|
|
|
||||||
|
|
@ -13,9 +13,10 @@ information is provided in the respective manual sections.
|
||||||
|
|
||||||
| Service | Backup | Reverse Proxy | SSO | LDAP | Monitoring | Profiling |
|
| Service | Backup | Reverse Proxy | SSO | LDAP | Monitoring | Profiling |
|
||||||
|-----------------------|--------|---------------|-----|-------|------------|-----------|
|
|-----------------------|--------|---------------|-----|-------|------------|-----------|
|
||||||
| [Nextcloud Server][1] | Y (1) | Y | Y | Y | Y (2) | P (3) |
|
| [Forgejo][] | Y (1) | Y | Y | Y | Y (2) | N |
|
||||||
| [Vaultwarden][2] | Y (1) | Y | Y | Y | Y (2) | N |
|
| [Home-Assistant][] | Y (1) | Y | N | Y | Y (2) | N |
|
||||||
| [Forgejo][3] | Y (1) | Y | Y | Y | Y (2) | N |
|
| [Nextcloud Server][] | Y (1) | Y | Y | Y | Y (2) | P (3) |
|
||||||
|
| [Vaultwarden][] | Y (1) | Y | Y | Y | Y (2) | N |
|
||||||
|
|
||||||
Legend: **N**: no but WIP; **P**: partial; **Y**: yes
|
Legend: **N**: no but WIP; **P**: partial; **Y**: yes
|
||||||
|
|
||||||
|
|
@ -23,9 +24,18 @@ Legend: **N**: no but WIP; **P**: partial; **Y**: yes
|
||||||
2. Dashboard is common to all services.
|
2. Dashboard is common to all services.
|
||||||
3. Works but the traces are not exported to Grafana yet.
|
3. Works but the traces are not exported to Grafana yet.
|
||||||
|
|
||||||
[1]: services-nextcloud.html
|
[Forgejo]: services-forgejo.html
|
||||||
[2]: services-vaultwarden.html
|
[Home-Assistant]: services-home-assistant.html
|
||||||
[3]: services-forgejo.html
|
[Nextcloud Server]: services-nextcloud.html
|
||||||
|
[Vaultwarden]: services-vaultwarden.html
|
||||||
|
|
||||||
|
```{=include=} chapters html:into-file=//services-forgejo.html
|
||||||
|
modules/services/forgejo/docs/default.md
|
||||||
|
```
|
||||||
|
|
||||||
|
```{=include=} chapters html:into-file=//services-home-assistant.html
|
||||||
|
modules/services/home-assistant/docs/default.md
|
||||||
|
```
|
||||||
|
|
||||||
```{=include=} chapters html:into-file=//services-nextcloud.html
|
```{=include=} chapters html:into-file=//services-nextcloud.html
|
||||||
modules/services/nextcloud-server/docs/default.md
|
modules/services/nextcloud-server/docs/default.md
|
||||||
|
|
@ -34,7 +44,3 @@ modules/services/nextcloud-server/docs/default.md
|
||||||
```{=include=} chapters html:into-file=//services-vaultwarden.html
|
```{=include=} chapters html:into-file=//services-vaultwarden.html
|
||||||
modules/services/vaultwarden/docs/default.md
|
modules/services/vaultwarden/docs/default.md
|
||||||
```
|
```
|
||||||
|
|
||||||
```{=include=} chapters html:into-file=//services-forgejo.html
|
|
||||||
modules/services/forgejo/docs/default.md
|
|
||||||
```
|
|
||||||
|
|
|
||||||
392
modules/services/home-assistant/docs/default.md
Normal file
392
modules/services/home-assistant/docs/default.md
Normal file
|
|
@ -0,0 +1,392 @@
|
||||||
|
# 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).
|
||||||
|
|
||||||
|
- 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://fogejo.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 LDAP block provided by Self Host Blocks
|
||||||
|
to setup a [LLDAP](https://github.com/lldap/lldap) service.
|
||||||
|
First, setup the global ldap block if not done yet:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
shb.ldap = {
|
||||||
|
enable = true;
|
||||||
|
domain = "example.com";
|
||||||
|
subdomain = "ldap";
|
||||||
|
ssl = config.shb.certs.certs.letsencrypt."example.com";
|
||||||
|
ldapPort = 3890;
|
||||||
|
webUIListenPort = 17170;
|
||||||
|
dcdomain = "dc=example,dc=com";
|
||||||
|
ldapUserPassword.result = config.shb.sops.secrets."ldap/userPassword".result;
|
||||||
|
jwtSecret.result = config.shb.sops.secrets."ldap/jwtSecret".result;
|
||||||
|
};
|
||||||
|
|
||||||
|
shb.certs.certs.letsencrypt."example.com".extraDomains = [ "ldap.example.com" ];
|
||||||
|
|
||||||
|
shb.sops.secrets."ldap/userPassword".request = config.shb.ldap.userPassword.request;
|
||||||
|
shb.sops.secrets."ldap/jwtSecret".request = config.shb.ldap.jwtSecret.request;
|
||||||
|
```
|
||||||
|
|
||||||
|
We then need to configure the `home-assistant` service
|
||||||
|
to talk to the LDAP server we just defined:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
shb.home-assistant.ldap
|
||||||
|
enable = true;
|
||||||
|
host = "127.0.0.1";
|
||||||
|
port = config.shb.ldap.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.
|
||||||
|
|
||||||
|
Work is in progress to make the creation of the LDAP user and group declarative too.
|
||||||
|
|
||||||
|
### 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.
|
||||||
|
|
||||||
|
### 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@
|
||||||
|
```
|
||||||
Loading…
Reference in a new issue