add documentation for home-assistant
This commit is contained in:
ibizaman
Pierre Penninckx
parent
7f86a7541a
commit
7dd7f41622
5 changed files with 586 additions and 11 deletions
|
|
@ -163,6 +163,11 @@ in stdenv.mkDerivation {
|
|||
'@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 \
|
||||
--replace \
|
||||
'@OPTIONS_JSON@' \
|
||||
|
|
|
|||
|
|
@ -1028,6 +1028,9 @@
|
|||
"native-prometheus-metrics": [
|
||||
"service-implementation-guide.html#native-prometheus-metrics"
|
||||
],
|
||||
"next-steps": [
|
||||
"index.html#next-steps"
|
||||
],
|
||||
"nixpkgs-integration": [
|
||||
"service-implementation-guide.html#nixpkgs-integration"
|
||||
],
|
||||
|
|
@ -1364,6 +1367,165 @@
|
|||
"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-nextcloud.html#services-nextcloudserver"
|
||||
],
|
||||
|
|
|
|||
|
|
@ -381,6 +381,16 @@ source: @OPTIONS_JSON@
|
|||
|
||||
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}
|
||||
|
||||
After creating documentation, generate the required redirects:
|
||||
|
|
@ -608,4 +618,4 @@ git add .
|
|||
git commit -m "Add SERVICENAME with full integration"
|
||||
```
|
||||
|
||||
This guide provides a complete roadmap for implementing production-ready SelfHostBlocks services that meet the project's quality standards.
|
||||
This guide provides a complete roadmap for implementing production-ready SelfHostBlocks services that meet the project's quality standards.
|
||||
|
|
|
|||
|
|
@ -13,9 +13,10 @@ information is provided in the respective manual sections.
|
|||
|
||||
| Service | Backup | Reverse Proxy | SSO | LDAP | Monitoring | Profiling |
|
||||
|-----------------------|--------|---------------|-----|-------|------------|-----------|
|
||||
| [Nextcloud Server][1] | Y (1) | Y | Y | Y | Y (2) | P (3) |
|
||||
| [Vaultwarden][2] | Y (1) | Y | Y | Y | Y (2) | N |
|
||||
| [Forgejo][3] | Y (1) | Y | Y | Y | Y (2) | N |
|
||||
| [Forgejo][] | Y (1) | Y | Y | Y | Y (2) | N |
|
||||
| [Home-Assistant][] | Y (1) | Y | N | 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
|
||||
|
||||
|
|
@ -23,9 +24,18 @@ Legend: **N**: no but WIP; **P**: partial; **Y**: yes
|
|||
2. Dashboard is common to all services.
|
||||
3. Works but the traces are not exported to Grafana yet.
|
||||
|
||||
[1]: services-nextcloud.html
|
||||
[2]: services-vaultwarden.html
|
||||
[3]: services-forgejo.html
|
||||
[Forgejo]: services-forgejo.html
|
||||
[Home-Assistant]: services-home-assistant.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
|
||||
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
|
||||
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