jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-07-13 12:26:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update add-on documentation (#1098)

Browse Source 
Co-authored-by: Tom Brien <TomBrien@users.noreply.github.com>
This commit is contained in:
Joakim Sørensen 2021-12-17 15:05:15 +01:00 committed by GitHub
parent b1271d6f25
commit 38b3b85f22
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 334 additions and 328 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
docs/add-ons.md
View File

@ -5,7 +5,7 @@ sidebar_label: Introduction
Add-ons for Home Assistant allow the user to extend the functionality around Home Assistant. This can be running an application that Home Assistant can integrate with (like an MQTT broker) or to share the configuration via Samba for easy editing from other computers. Add-ons can be configured via the Supervisor panel in Home Assistant. Add-ons for Home Assistant allow the user to extend the functionality around Home Assistant. This can be running an application that Home Assistant can integrate with (like an MQTT broker) or to share the configuration via Samba for easy editing from other computers. Add-ons can be configured via the Supervisor panel in Home Assistant.
Under the hood, add-ons are Docker images published in [Docker Hub](https://hub.docker.com/). Developers can create [GitHub](https://github.com) repositories that contain multiple references to add-ons for easy sharing with the community. Under the hood, add-ons are container images published to a container registry like [GitHub container registry](https://github.com/features/packages) and [Docker Hub](https://hub.docker.com/). Developers can create [GitHub](https://github.com) repositories that contain multiple add-ons for easy sharing with the community.
- [Tutorial: Making your first add-on](add-ons/tutorial.md) - [Tutorial: Making your first add-on](add-ons/tutorial.md)
- [Configuration](add-ons/configuration.md) - [Configuration](add-ons/configuration.md)
@ -18,10 +18,11 @@ Under the hood, add-ons are Docker images published in [Docker Hub](https://hub.
Useful links: Useful links:
- [Supervisor](https://github.com/home-assistant/supervisor) - [Example Add-on repository](https://github.com/home-assistant/addons-example)
- [Core Add-ons](https://github.com/home-assistant/hassio-addons) - [Home Assistant Supervisor](https://github.com/home-assistant/supervisor)
- [Docker base images](https://github.com/home-assistant/docker-base) - [Home Assistant Core Add-ons](https://github.com/home-assistant/addons)
- [Builder](https://github.com/home-assistant/hassio-builder) - [Home Assistant Docker base images](https://github.com/home-assistant/docker-base)
- [Home Assistant Builder](https://github.com/home-assistant/builder)
- [Home Assistant community Add-ons](https://github.com/hassio-addons) - [Home Assistant community Add-ons](https://github.com/hassio-addons)
- [Home Assistant Operating System](https://github.com/home-assistant/operating-system) - [Home Assistant Operating System](https://github.com/home-assistant/operating-system)
- [Home Assistant Docker](https://github.com/home-assistant/docker) - [Home Assistant Docker images](https://github.com/home-assistant/docker)

261
docs/add-ons/configuration.md
View File

@ -7,11 +7,11 @@ Each add-on is stored in a folder. The file structure looks like this:
```text ```text
addon_name/ addon_name/
translations/ translations/
en.(json/yaml/yml) en.yaml
apparmor.txt apparmor.txt
build.(json/yaml/yml) build.yaml
CHANGELOG.md CHANGELOG.md
config.(json/yaml/yml) config.yaml
DOCS.md DOCS.md
Dockerfile Dockerfile
icon.png icon.png
@ -20,6 +20,12 @@ addon_name/
run.sh run.sh
``` ```
:::note
Translation files, `config` and `build` all support `.json`, `.yml` and `.yaml` as the file type.
To keep it simple all examples are using `.yaml`
:::
## Add-on script ## Add-on script
As with every Docker container, you will need a script to run when the container is started. A user might run many add-ons, so it is encouraged to try to stick to Bash scripts if you're doing simple things. As with every Docker container, you will need a script to run when the container is started. A user might run many add-ons, so it is encouraged to try to stick to Bash scripts if you're doing simple things.
@ -55,10 +61,10 @@ All add-ons are based on latest Alpine Linux image. Home Assistant will automati
ARG BUILD_FROM ARG BUILD_FROM
FROM $BUILD_FROM FROM $BUILD_FROM
ENV LANG C.UTF-8
# Install requirements for add-on # Install requirements for add-on
RUN apk add --no-cache example_alpine_package RUN \
apk add --no-cache \
example_alpine_package
# Copy data for add-on # Copy data for add-on
COPY run.sh / COPY run.sh /
@ -70,10 +76,13 @@ CMD [ "/run.sh" ]
If you don't use local build on device or our build script, make sure that the Dockerfile have also a set of labels include: If you don't use local build on device or our build script, make sure that the Dockerfile have also a set of labels include:
```dockerfile ```dockerfile
LABEL io.hass.version="VERSION" io.hass.type="addon" io.hass.arch="armhf|aarch64|i386|amd64" LABEL \
io.hass.version="VERSION" \
io.hass.type="addon" \
io.hass.arch="armhf|aarch64|i386|amd64"
``` ```
It is possible to use own base image with `build.(json/yaml/yml)` or if you do not need support for automatic multi-arch building you can also use a simple docker `FROM`. It is possible to use own base image with `build.yaml` or if you do not need support for automatic multi-arch building you can also use a simple docker `FROM`.
### Build Args ### Build Args
@ -81,42 +90,23 @@ We support the following build arguments by default:
| ARG | Description | | ARG | Description |
|-----|-------------| |-----|-------------|
| BUILD_FROM | Hold image for dynamic builds or buildings over our systems. | `BUILD_FROM` | Holds the image for dynamic builds or buildings over our systems.
| BUILD_VERSION | Add-on version (read from `config.(json/yaml/yml)`). | `BUILD_VERSION` | Add-on version (read from `config.yaml`).
| BUILD_ARCH | Hold current build arch inside. | `BUILD_ARCH` | Holds the current build arch inside.
## Add-on config ## Add-on configuration
The configuration for an add-on is stored in `config.(json/yaml/yml)`. The configuration for an add-on is stored in `config.yaml`.
```json
{
"name": "xy",
"version": "1.2",
"slug": "folder",
"description": "long description",
"arch": ["amd64"],
"url": "website with more information about add-on (e.g., a forum thread for support)",
"startup": "application",
"boot": "auto",
"ports": {
"123/tcp": 123
},
"map": ["config:rw", "ssl"],
"image": "repo/{arch}-my-custom-addon"
}
```
```yaml ```yaml
name: xy name: "Hello world"
version: '1.2' version: "1.1.0"
slug: folder slug: folder
description: long description description: >-
"Long description"
arch: arch:
- amd64 - amd64
url: website with more information about add-on (e.g., a forum thread for support) url: "website with more information about add-on (e.g., a forum thread for support)"
startup: application
boot: auto
ports: ports:
123/tcp: 123 123/tcp: 123
map: map:
@ -125,103 +115,110 @@ map:
image: repo/{arch}-my-custom-addon image: repo/{arch}-my-custom-addon
``` ```
| Key | Type | Required | Description | ### Required configuration options
| Key | Type | Description |
| --- | ---- | ----------- |
| `name` | string | The name of the add-on.
| `version` | string | Version of the add-on. If you are using a docker image with the `image` option, this needs to match the tag of the image that will be used.
| `slug` | string | Slug of the add-on. This needs to be unique in the scope of the [repository](/docs/add-ons/repository) that the add-on is published in and URI friendly.
| `description` | string | Description of the add-on.
| `arch` | list | A list of supported architectures: `armhf`, `armv7`, `aarch64`, `amd64`, `i386`.
### Optional configuration options
| Key | Type | Default | Description |
| --- | ---- | -------- | ----------- | | --- | ---- | -------- | ----------- |
| name | string | yes | Name of the add-on. | `machine` | list | | Default it support any machine type. You can select that this add-on run only on specific machines. You can use `!` before a machine type to negate it. By default all machines are allowed.
| version | string | yes | Version of the add-on. If using a docker image with the `image` option, this needs to match the tag of the image that is already published. | `url` | url | | Homepage of the add-on. Here you can explain the add-ons and options.
| slug | string | yes | Slug of the add-on. This needs to be unique in the scope of the [repository](repository.md) that the add-on is published in and URI friendly. | `startup` | string | `application` | `initialize` will start add-on on setup of Home Assistant. `system` is for things like databases and not dependent on other things. `services` will start before Home Assistant, while `application` is started afterwards. Finally `once` is for applications that don't run as a daemon.
| description | string | yes | Description of the add-on. | `webui` | string | | An URL for the web interface of this add-on. Like `http://[HOST]:[PORT:2839]/dashboard`, the port needs the internal port, which will be replaced with the effective port. It is also possible to bind the protocol part to a configuration options with: `[PROTO:option_name]://[HOST]:[PORT:2839]/dashboard` and it's looked up if it is `true` and it's going to `https`.
| arch | list | yes | List of supported arch: `armhf`, `armv7`, `aarch64`, `amd64`, `i386`. | `boot` | string | `auto` | `auto` start at boot is controlled by the system. `manual` for only manual starting.
| machine | list | no | Default it support any machine type. You can select that this add-on run only on specific machines. You can use `!` before a machine type to negate it. | `ports` | dict | | Network ports to expose from the container. Format is `"container-port/type": host-port`. If the host port is `null` then the mapping is disabled.
| url | url | no | Homepage of the add-on. Here you can explain the add-ons and options. | `ports_description` | dict | | Network ports description mapping. Format is `"container-port/type": "description of this port"`.
| startup | string | no | Default `application`. `initialize` will start add-on on setup of Home Assistant. `system` is for things like databases and not dependent on other things. `services` will start before Home Assistant, while `application` is started afterwards. Finally `once` is for applications that don't run as a daemon. | `host_network` | bool | `false` | If `true`, the add-on runs on host network.
| webui | string | no | An URL for the web interface of this add-on. Like `http://[HOST]:[PORT:2839]/dashboard`, the port needs the internal port, which will be replaced with the effective port. It is also possible to bind the protocol part to a configuration options with: `[PROTO:option_name]://[HOST]:[PORT:2839]/dashboard` and it's looked up if it is `true` and it's going to `https`. | `host_ipc` | bool | `false` | Allow to share the IPC namespace with others.
| boot | string | no | Default `auto`. `auto` start at boot is controlled by the system. `manual` for only manual starting. | `host_dbus` | bool | `false` | Map the host D-Bus service into the add-on.
| ports | dict | no | Network ports to expose from the container. Format is `"container-port/type": host-port`. If the host port is `null` then the mapping is disabled. | `host_pid` | bool | `false` | Allow to run container on host PID namespace. Works only for not protected add-ons.
| ports_description | dict | no | Network ports description mapping. Format is `"container-port/type": "description of this port"`. | `devices` | list | | Device list to map into the add-on. Format is: `<path_on_host>`. E.g., `/dev/ttyAMA0`
| host_network | bool | no | If `true`, the add-on runs on host network. | `homeassistant` | string | | Pin a minimum required Home Assistant Core version for the add-on. Value is a version string like `0.91.2`.
| host_ipc | bool | no | Default `false`. Allow to share the IPC namespace with others. | `hassio_role` | str | `default` |Role-based access to Supervisor API. Available: `default`, `homeassistant`, `backup`, `manager` or `admin`
| host_dbus | bool | no | Default `false`. Map the host D-Bus service into the add-on. | `hassio_api` | bool | `false` | This add-on can access the Supervisor's REST API. Use `http://supervisor`.
| host_pid | bool | no | Default `false`. Allow to run container on host PID namespace. Works only for not protected add-ons. | `homeassistant_api` | bool | `false` | This add-on can access to the Home Assistant REST API proxy. Use `http://supervisor/core/api`.
| devices | list | no | Device list to map into the add-on. Format is: `<path_on_host>`. E.g., `/dev/ttyAMA0` | `docker_api` | bool | `false` | Allow read-only access to Docker API for add-on. Works only for not protected add-ons.
| homeassistant | string | no | Pin a minimum required Home Assistant Core version for the add-on. Value is a version string like `0.91.2`. | `privileged` | list | | Privilege for access to hardware/system. Available access: `NET_ADMIN`, `SYS_ADMIN`, `SYS_RAWIO`, `SYS_TIME`, `SYS_NICE`, `SYS_RESOURCE`, `SYS_PTRACE`, `SYS_MODULE` or `DAC_READ_SEARCH`
| hassio_role | str | no | Default `default`. Role-based access to Supervisor API. Available: `default`, `homeassistant`, `backup`, `manager` or `admin` | `full_access` | bool | `false` | Give full access to hardware like the privileged mode in Docker. Works only for not protected add-ons. Consider using other add-on options instead of this, like `devices`. If you enable this option, don't add `devices`, `uart`, `usb` or `gpio` this is not needed.
| hassio_api | bool | no | This add-on can access the Supervisor's REST API. Use `http://supervisor`. | `apparmor` | bool/string | `false` | Enable or disable AppArmor support. If it is enable, you can also use custom profiles with the name of the profile.
| homeassistant_api | bool | no | This add-on can access to the Home Assistant REST API proxy. Use `http://supervisor/core/api`. | `map` | list | | List of maps for additional Home Assistant folders. Possible values: `config`, `ssl`, `addons`, `backup`, `share` or `media`. Defaults to `ro`, which you can change by adding `:rw` to the end of the name.
| docker_api | bool | no | Allow read-only access to Docker API for add-on. Works only for not protected add-ons. | `environment` | dict | | A dictionary of environment variable to run add-on.
| privileged | list | no | Privilege for access to hardware/system. Available access: `NET_ADMIN`, `SYS_ADMIN`, `SYS_RAWIO`, `SYS_TIME`, `SYS_NICE`, `SYS_RESOURCE`, `SYS_PTRACE`, `SYS_MODULE` or `DAC_READ_SEARCH` | `audio` | bool | `false` | Mark this add-on to use internal audio system. We map a working PulseAudio setup into container. If your application does not support PulseAudio, you may need to install: Alpine Linux `alsa-plugins-pulse` or Debian/Ubuntu `libasound2-plugins`.
| full_access | bool | no | Give full access to hardware like the privileged mode in Docker. Works only for not protected add-ons. Consider using other add-on options instead of this, like `devices`. If you enable this option, don't add `devices`, `uart`, `usb` or `gpio` this is not needed. | `video` | bool | `false` | Mark this add-on to use the internal video system. All available devices will be mapped into the add-on.
| apparmor | bool/string | no | Enable or disable AppArmor support. If it is enable, you can also use custom profiles with the name of the profile. | `gpio` | bool | `false` | If this is set to `true`, `/sys/class/gpio` will map into add-on for access to GPIO interface from kernel. Some libraries also need `/dev/mem` and `SYS_RAWIO` for read/write access to this device. On systems with AppArmor enabled, you need to disable AppArmor or provide you own profile for the add-on, which is better for security.
| map | list | no | List of maps for additional Home Assistant folders. Possible values: `config`, `ssl`, `addons`, `backup`, `share` or `media`. Defaults to `ro`, which you can change by adding `:rw` to the end of the name. | `usb` | bool | `false` | If this is set to `true`, it would map the raw USB access `/dev/bus/usb` into add-on with plug&play support.
| environment | dict | no | A dictionary of environment variable to run add-on. | `uart` | bool | `false` | Default `false`. Auto mapping all UART/serial devices from the host into the add-on.
| audio | bool | no | Mark this add-on to use internal audio system. We map a working PulseAudio setup into container. If your application does not support PulseAudio, you may need to install: Alpine Linux `alsa-plugins-pulse` or Debian/Ubuntu `libasound2-plugins`. | `udev` | bool | `false` | Default `false`. Set this `true`, gets the host udev database read-only mounted into the add-on.
| video | bool | no | Mark this add-on to use the internal video system. All available devices will be mapped into the add-on. | `devicetree` | bool | `false` | If this is set to True, `/device-tree` will map into add-on.
| gpio | bool | no | If this is set to `true`, `/sys/class/gpio` will map into add-on for access to GPIO interface from kernel. Some libraries also need `/dev/mem` and `SYS_RAWIO` for read/write access to this device. On systems with AppArmor enabled, you need to disable AppArmor or provide you own profile for the add-on, which is better for security. | `kernel_modules` | bool | `false` | Map host kernel modules and config into add-on (readonly) and give you SYS_MODULE permission.
| usb | bool | no | If this is set to `true`, it would map the raw USB access `/dev/bus/usb` into add-on with plug&play support. | `stdin` | bool | `false` | If enabled, you can use the STDIN with Home Assistant API.
| uart | bool | no | Default `false`. Auto mapping all UART/serial devices from the host into the add-on. | `legacy` | bool | `false` | If the Docker image has no `hass.io` labels, you can enable the legacy mode to use the config data.
| udev | bool | no | Default `false`. Set this `true`, gets the host udev database read-only mounted into the add-on. | `options` | dict | | Default options value of the add-on.
| devicetree | bool | no | Boolean. If this is set to True, `/device-tree` will map into add-on. | `schema` | dict | | Schema for options value of the add-on. It can be `false` to disable schema validation and options.
| kernel_modules | bool | no | Map host kernel modules and config into add-on (readonly) and give you SYS_MODULE permission. | `image` | string | | For use with Docker Hub and other container registries. This should be set to the name of the image only (E.g, `ghcr.io/home-assistant/{arch}-addon-example`). If you use this option, set the active docker tag using the `version` option.
| stdin | bool | no | Boolean. If enabled, you can use the STDIN with Home Assistant API. | `timeout` | integer | | Default 10 (seconds). The timeout to wait until the Docker daemon is done or will be killed.
| legacy | bool | no | Boolean. If the Docker image has no `hass.io` labels, you can enable the legacy mode to use the config data. | `tmpfs` | bool | `false` | If this is set to `true`, the containers `/tmp` is using tmpfs, a memory file system.
| options | dict | no | Default options value of the add-on. | `discovery` | list | | A list of services that this add-on provides for Home Assistant. Currently supported: `mqtt`
| schema | dict | no | Schema for options value of the add-on. It can be `false` to disable schema validation and options. | `services` | list | | A list of services that will be provided or consumed with this add-on. Format is `service`:`function` and functions are: `provide` (this add-on can provide this service), `want` (this add-on can use this service) or `need` (this add-on need this service to work correctly).
| image | string | no | For use with Docker Hub and other container registries. This should be set to the name of the image only (E.g, `ghcr.io/home-assistant/{arch}-addon-example`). If you use this option, set the active docker tag using the `version` option. | `auth_api` | bool | `false` | Allow access to Home Assistant user backend.
| timeout | integer | no | Default 10 (seconds). The timeout to wait until the Docker daemon is done or will be killed. | `ingress` | bool | `false` | Enable the ingress feature for the add-on.
| tmpfs | bool | no | If this is set to `true`, the containers `/tmp` is using tmpfs, a memory file system. | `ingress_port` | integer | `8099` | For add-ons that run on the host network, you can use `0` and read the port later via API.
| discovery | list | no | A list of services that this add-on provides for Home Assistant. Currently supported: `mqtt` | `ingress_entry` | string | `/` | Modify the URL entry point.
| services | list | no | A list of services that will be provided or consumed with this add-on. Format is `service`:`function` and functions are: `provide` (this add-on can provide this service), `want` (this add-on can use this service) or `need` (this add-on need this service to work correctly). | `ingress_stream` | bool | `false` | When enabled requests to the add-on are streamed
| auth_api | bool | no | Allow access to Home Assistant user backend. | `panel_icon` | string | `mdi:puzzle` | [MDI icon](https://materialdesignicons.com/) for the menu panel integration.
| ingress | bool | no | Enable the ingress feature for the add-on. | `panel_title` | string | | Defaults to the add-on name, but can be modified with this option.
| ingress_port | integer | no | Default `8099`. For add-ons that run on the host network, you can use `0` and read the port later via API. | `panel_admin` | bool | `true` | Make menu entry only available with users in the admin group.
| ingress_entry | string | no | Modify the URL entry point from `/`. | `backup` | string | `hot` | `hot` or `cold`. If `cold`, the supervisor turns the add-on off before taking a backup (the `pre/post` options are ignored when `cold` is used).
| ingress_stream | bool | no | Default `false`, when enabled POST requests to the add-on are streamed | `backup_pre` | string | | Command to execute in the context of the add-on before the backup is taken.
| panel_icon | string | no | Default: `mdi:puzzle`. MDI icon for the menu panel integration. | `backup_post` | string | | Command to execute in the context of the add-on after the backup was taken.
| panel_title | string | no | Default is the add-on name, but can be modified with this option. | `backup_exclude` | list | | List of file/path (with glob support) that are excluded from backups.
| panel_admin | bool | no | Default `true`. Make menu entry only available with admin privileged. | `advanced` | bool | `false` | Set this to `true` to require the user to have enabled "Advanced" mode for it to show.
| backup | string | no | `hot` (default) or `cold`. If `cold`, the supervisor turns the add-on off before taking a backup (the `pre/post` options are ignored when `cold` is used). | `stage` | string | `stable` | Flag add-on with follow attribute: `stable`, `experimental` or `deprecated`
| backup_pre | string | no | Command to execute in the context of the add-on before the backup is taken. | `init` | bool | `true` | Set this to `false` to disable the Docker default system init. Use this if the image has its own init system (Like [s6-overlay](https://github.com/just-containers/s6-overlay)).
| backup_post | string | no | Command to execute in the context of the add-on after the backup was taken. | `watchdog` | string | | An URL for monitor an application this add-on. Like `http://[HOST]:[PORT:2839]/dashboard`, the port needs the internal port, which will be replaced with the effective port. It is also possible to bind the protocol part to a configuration options with: `[PROTO:option_name]://[HOST]:[PORT:2839]/dashboard` and it's looked up if it is `true` and it's going to `https`. For simple TCP port monitoring you can use `tcp://[HOST]:[PORT:80]`. It work for add-ons on host or internal network.
| backup_exclude | list | no | List of file/path (with glob support) that are excluded from backups. | `realtime` | bool | `false` | Give add-on access to host schedule including `SYS_NICE` for change execution time/priority.
| advanced | bool | no | Default `false`. Make addon visible in simple mode. | `journald` | bool | `false` | If set to `true`, the host's system journal will be mapped read-only into the add-on. Most of the time the journal will be in `/var/log/journal` however on some hosts you will find it in `/run/log/journal`. Add-ons relying on this capability should check if the directory `/var/log/journal` is populated and fallback on `/run/log/journal` if not.
| stage | string | no | Default `stable`. Flag add-on with follow attribute: `stable`, `experimental` or `deprecated`
| init | bool | no | Default `true`. Disable the Docker default system init. Use this if the image has its own init system.
| watchdog | string | no | An URL for monitor an application this add-on. Like `http://[HOST]:[PORT:2839]/dashboard`, the port needs the internal port, which will be replaced with the effective port. It is also possible to bind the protocol part to a configuration options with: `[PROTO:option_name]://[HOST]:[PORT:2839]/dashboard` and it's looked up if it is `true` and it's going to `https`. For simple TCP port monitoring you can use `tcp://[HOST]:[PORT:80]`. It work for add-ons on host or internal network.
| realtime | bool | no | Give add-on access to host schedule including SYS_NICE for change execution time/priority.
| journald | bool | no | Default `false`. If set to `true`, the host's system journal will be mapped read-only into the add-on. Most of the time the journal will be in `/var/log/journal` however on some hosts you will find it in `/run/log/journal`. Add-ons relying on this capability should check if the directory `/var/log/journal` is populated and fallback on `/run/log/journal` if not.
### Options / Schema ### Options / Schema
The `options` dictionary contains all available options and their default value. Set the default value to `null` if the value is required to be given by the user before the add-on can start, and it show it inside default values. Only nested arrays and dictionaries are supported with a deep of two size. If you want make an option optional, put `?` to the end of data type, otherwise it will be a required value. The `options` dictionary contains all available options and their default value. Set the default value to `null` if the value is required to be given by the user before the add-on can start, and it show it inside default values. Only nested arrays and dictionaries are supported with a deep of two size. If you want make an option optional, put `?` to the end of data type, otherwise it will be a required value.
```json ```yaml
{ message: "custom things"
"message": "custom things", logins:
"logins": [ - username: beer
{ "username": "beer", "password": "123456" }, password: "123456"
{ "username": "cheep", "password": "654321" } - username: cheep
], password: "654321"
"random": ["haha", "hihi", "huhu", "hghg"], random:
"link": "http://example.com/", - haha
"size": 15, - hihi
"count": 1.2 link: "http://example.com/"
} size: 15
count: 1.2
``` ```
The `schema` looks like `options` but describes how we should validate the user input. For example: The `schema` looks like `options` but describes how we should validate the user input. For example:
```json ```yaml
{ message: str
"message": "str", logins:
"logins": [ - username: str
{ "username": "str", "password": "str" } password: str
], random:
"random": ["match(^\\w*$)"], - "match(^\\w*$)"
"link": "url", link: url
"size": "int(5,20)", size: "int(5, 20)"
"count": "float", count: float
"not_need": "str?" not_need: "str?"
}
``` ```
We support: We support:
@ -240,21 +237,9 @@ We support:
## Add-on extended build ## Add-on extended build
Additional build options for an add-on is stored in `build.(json/yaml/yml)`. This file will be read from our build systems. Additional build options for an add-on is stored in `build.yaml`. This file will be read from our build systems.
You need this only, if you not use the default images or need additional things. You need this only, if you not use the default images or need additional things.
```json
{
"build_from": {
"armhf": "mycustom/base-image:latest"
},
"squash": false,
"args": {
"my_build_arg": "xy"
}
}
```
```yaml ```yaml
build_from: build_from:
armhf: mycustom/base-image:latest armhf: mycustom/base-image:latest
@ -281,7 +266,7 @@ We provide a set of [base images][docker-base] which should cover a lot of needs
Add-ons can provide translation files for configuration options that are used in the UI. Add-ons can provide translation files for configuration options that are used in the UI.
Example path to translation file: `addon/translations/{language_code}.(json/yaml/yml)` Example path to translation file: `addon/translations/{language_code}.yaml`
For `{language_code}` use a valid language code, like `en`, for a [full list have a look here](https://github.com/home-assistant/frontend/blob/dev/src/translations/translationMetadata.json), `en.yaml` would be a valid filename. For `{language_code}` use a valid language code, like `en`, for a [full list have a look here](https://github.com/home-assistant/frontend/blob/dev/src/translations/translationMetadata.json), `en.yaml` would be a valid filename.

76
docs/add-ons/presentation.md
View File

@ -51,9 +51,10 @@ By default, AppArmor gives you a certain level of security by restricting some g
As for Home Assistant's implementation, you can activate your own custom AppArmor profile by putting an `apparmor.txt` file into your add-on folder. Adding your own `apparmor.txt` will load that file as the primary AppArmor profile instead of the default implementation. On top of knowing your add-on will run in a constrained and effective manner, writing your own custom `apparmor.txt` file will earn your add-on a security point after your add-on is installed, thus improving your user's confidence and perception of your add-on. As for Home Assistant's implementation, you can activate your own custom AppArmor profile by putting an `apparmor.txt` file into your add-on folder. Adding your own `apparmor.txt` will load that file as the primary AppArmor profile instead of the default implementation. On top of knowing your add-on will run in a constrained and effective manner, writing your own custom `apparmor.txt` file will earn your add-on a security point after your add-on is installed, thus improving your user's confidence and perception of your add-on.
An `apparmor.txt` goes in the same folder as your `config.json` file. Below is an example `apparmor.txt`. Replace `ADDON_SLUG` with the slug defined in your add-on configuration. An `apparmor.txt` goes in the same folder as your `config.yaml` file. Below is an example `apparmor.txt`. Replace `ADDON_SLUG` with the slug defined in your add-on configuration.
apparmor.txt apparmor.txt
```txt ```txt
#include <tunables/global> #include <tunables/global>
@ -79,7 +80,7 @@ profile ADDON_SLUG flags=(attach_disconnected,mediate_deleted) {
/usr/lib/bashio/** ix, /usr/lib/bashio/** ix,
/tmp/** rw, /tmp/** rw,
# Access to Options.json and other files within your addon # Access to options.json and other files within your addon
/data/** rw, /data/** rw,
# Start new profile for service # Start new profile for service
@ -99,8 +100,8 @@ profile ADDON_SLUG flags=(attach_disconnected,mediate_deleted) {
Ingress allows users to access the add-on web interface via the Home Assistant UI. Authentication is handled by Home Assistant, so neither the user nor the add-on developer will need to care about the security or port forwarding. Users love this feature! It connects your user directly to the add-on, can provide a seamless UX within Home Assistant and grants your add-on 2 points of security. Ingress allows users to access the add-on web interface via the Home Assistant UI. Authentication is handled by Home Assistant, so neither the user nor the add-on developer will need to care about the security or port forwarding. Users love this feature! It connects your user directly to the add-on, can provide a seamless UX within Home Assistant and grants your add-on 2 points of security.
Here are the requirements of Ingress: Here are the requirements of Ingress:
- Ingress must be enabled. Set `ingress: true` in [`config.json`](/docs/add-ons/configuration#add-on-config). - Ingress must be enabled. Set `ingress: true` in [`config.yaml`](/docs/add-ons/configuration#optional-configuration-options).
- Your server may run on port 8099. If it does not run on 8099, you must set `ingress_port: PORT_NUMBER` in [`config.json`](/docs/add-ons/configuration/#add-on-config) to match your configuration. - Your server may run on port 8099. If it does not run on 8099, you must set `ingress_port: PORT_NUMBER` in [`config.yaml`](/docs/add-ons/configuration/#add-on-config) to match your configuration.
- Only connections from `172.30.32.2` must be allowed. You should deny access to all other IP addresses within your add-on server. - Only connections from `172.30.32.2` must be allowed. You should deny access to all other IP addresses within your add-on server.
- Users are previously authenticated via Home Assistant. Authentication is not required. - Users are previously authenticated via Home Assistant. Authentication is not required.
@ -117,12 +118,13 @@ Ingress API gateway supports the following:
## Basic Ingress Example with Nginx ## Basic Ingress Example with Nginx
The following is a basic ingress implementation with an Nginx server. This contains an example`Dockerfile`, `config.json`, and `ingress.conf` configuration. The following is a basic ingress implementation with an Nginx server. This contains an example`Dockerfile`, `config.yaml`, and `ingress.conf` configuration.
The `ingress.conf` is configured to accept only connections from IP address `172.30.32.2` as we are only expecting connections from this IP address for Ingress purposes. Any other IP address will be rejected. The ingress port 8099 is utilized to reduce configuration work. If you wish to configure a different ingress port you may, but the `config.json` option `ingress_port` must be defined to match. The `ingress.conf` is configured to accept only connections from IP address `172.30.32.2` as we are only expecting connections from this IP address for Ingress purposes. Any other IP address will be rejected. The ingress port 8099 is utilized to reduce configuration work. If you wish to configure a different ingress port you may, but the `config.yaml` option `ingress_port` must be defined to match.
ingress.conf ingress.conf
```nginx
```nginx
server { server {
listen 8099; listen 8099;
allow 172.30.32.2; allow 172.30.32.2;
@ -133,37 +135,45 @@ server {
Our example `Dockerfile` is configured to support only our Nginx server and does not support a `run.sh` like most add-ons. You may replace the `CMD` with your own command to allow more configuration options while launching your add-on. This Dockerfile will `RUN` to install our Nginx dependencies, `COPY` our example `ingress.conf` from above to the add-on container, then `CMD` start Nginx. Our example `Dockerfile` is configured to support only our Nginx server and does not support a `run.sh` like most add-ons. You may replace the `CMD` with your own command to allow more configuration options while launching your add-on. This Dockerfile will `RUN` to install our Nginx dependencies, `COPY` our example `ingress.conf` from above to the add-on container, then `CMD` start Nginx.
Dockerfile Dockerfile
```Dockerfile
```dockerfile
ARG BUILD_FROM ARG BUILD_FROM
FROM $BUILD_FROM FROM $BUILD_FROM
ENV LANG C.UTF-8
#Add nginx and create the run folder for nginx. #Add nginx and create the run folder for nginx.
RUN apk --no-cache add nginx;mkdir -p /run/nginx; RUN \
apk --no-cache add \
nginx \
\
&& mkdir -p /run/nginx
#Copy our conf into the nginx http.d folder. #Copy our conf into the nginx http.d folder.
COPY ingress.conf /etc/nginx/http.d/ COPY ingress.conf /etc/nginx/http.d/
#Launch nginx with debug options. #Launch nginx with debug options.
CMD [ "nginx","-g","daemon off;error_log /dev/stdout debug;" ] CMD [ "nginx","-g","daemon off;error_log /dev/stdout debug;" ]
``` ```
In order to enable Ingress, our `config.json` file _must_ include `ingress: true` and _may_ specify the `ingress_port`, along with other required information. In order to enable Ingress, our `config.yaml` file _must_ include `ingress: true` and _may_ specify the `ingress_port`, along with other required information.
config.json config.yaml
```json
{ ```yaml
"name": "Ingress Example", name: "Ingress Example"
"version": "0.00.0.0.000.0.000", version: "1.0.0"
"slug": "nginx-ingress-example", slug: "nginx-ingress-example"
"description": "ingress testing", description: "Ingress testing"
"arch": ["armhf", "armv7", "aarch64", "amd64", "i386"], arch:
"ingress": true, - amd64
"ingress_port": 8099 - armhf
} - armv7
- i386
ingress: true
``` ```
After the add-on is started, you should be able to view your Ingress server by clicking "OPEN WEB UI" within the add-on info screen. After the add-on is started, you should be able to view your Ingress server by clicking "OPEN WEB UI" within the add-on info screen.
# Security ## Security
Add-on security should be a matter of pride. You should strive for the highest level of security you can possibly attain. If your add-on has a lower security rating, then users will be less likely to trust it. Add-on security should be a matter of pride. You should strive for the highest level of security you can possibly attain. If your add-on has a lower security rating, then users will be less likely to trust it.
@ -171,14 +181,14 @@ Each add-on starts with a base rating of 5, on a scale of 1 to 6. Depending on d
| Action | Change | Notes | | Action | Change | Notes |
|---|---|---| |---|---|---|
| Use `ingress: true` in [`config.json`](/docs/add-ons/configuration#add-on-config) | +2 | overrides `auth_api` rating | | Use `ingress: true` in [`config.yaml`](/docs/add-ons/configuration#optional-configuration-options) | +2 | overrides `auth_api` rating |
| Use `auth_api: true` in [`config.json`](/docs/add-ons/configuration#add-on-config) | +1 | overridden by `ingress` | | Use `auth_api: true` in [`config.yaml`](/docs/add-ons/configuration#optional-configuration-options) | +1 | overridden by `ingress` |
| Use custom [`apparmor.txt`](/docs/add-ons/presentation#apparmor)| +1| Rating applied after installation | | Use custom [`apparmor.txt`](/docs/add-ons/presentation#apparmor)| +1| Rating applied after installation |
| Set `apparmor: false` in [`config.json`](/docs/add-ons/configuration#add-on-config) | -1 | | | Set `apparmor: false` in [`config.yaml`](/docs/add-ons/configuration#optional-configuration-options) | -1 | |
| Use `privileged: NET_ADMIN`, `SYS_ADMIN`, `SYS_RAWIO`, `SYS_PTRACE`, `SYS_MODULE`, or `DAC_READ_SEARCH`, or `kernel_modules: ` used in [`config.json`](/docs/add-ons/configuration#add-on-config)| -1 | Rating applied only once if multiple are used. | | Use `privileged: NET_ADMIN`, `SYS_ADMIN`, `SYS_RAWIO`, `SYS_PTRACE`, `SYS_MODULE`, or `DAC_READ_SEARCH`, or `kernel_modules: ` used in [`config.yaml`](/docs/add-ons/configuration#optional-configuration-options)| -1 | Rating applied only once if multiple are used. |
| Use `hassio_role: manager` in [`config.json`](/docs/add-ons/configuration#add-on-config) | -1 | | | Use `hassio_role: manager` in [`config.yaml`](/docs/add-ons/configuration#optional-configuration-options) | -1 | |
| Use `host_network: true` in [`config.json`](/docs/add-ons/configuration#add-on-config) | -1 | | | Use `host_network: true` in [`config.yaml`](/docs/add-ons/configuration#optional-configuration-options) | -1 | |
| Use `hassio_role: admin` in [`config.json`](/docs/add-ons/configuration#add-on-config) | -2 | | | Use `hassio_role: admin` in [`config.yaml`](/docs/add-ons/configuration#optional-configuration-options) | -2 | |
| Use `host_pid: true` in [`config.json`](/docs/add-ons/configuration#add-on-config) | -2 | | | Use `host_pid: true` in [`config.yaml`](/docs/add-ons/configuration#optional-configuration-options) | -2 | |
| Use `full_access: true` in [`config.json`](/docs/add-ons/configuration#add-on-config) | Security set to 1 | Overrides all other adjustments | | Use `full_access: true` in [`config.yaml`](/docs/add-ons/configuration#optional-configuration-options) | Security set to 1 | Overrides all other adjustments |
| Use `docker_api: true` in [`config.json`](/docs/add-ons/configuration#add-on-config) | Security set to 1 | Overrides all other adjustments | | Use `docker_api: true` in [`config.yaml`](/docs/add-ons/configuration#optional-configuration-options) | Security set to 1 | Overrides all other adjustments |

50
docs/add-ons/publishing.md
View File

@ -2,55 +2,63 @@
title: "Publishing your add-on" title: "Publishing your add-on"
--- ---
There are two different ways of publishing add-ons. One is to publish pre-built containers to Docker Hub and the other option is to have users build the containers locally on their Home Assistant instance. There are two different ways of publishing add-ons. One is to publish pre-built containers to a container registry and the other option is to have users build the containers locally on their Home Assistant instance.
#### Pre-built containers #### Pre-built containers
With pre-built containers, the developer is responsible for building the images for each architecture on their machine and push the results out to Docker Hub. This has a lot of advantages for the user. As a user it will only have to download the final container and be up and running once the download finishes. This makes the installation process fast and almost no chance of failure. This is the preferred method. With pre-built containers, the developer is responsible for building the images for each architecture on their machine and push the results out to a container registry. This has a lot of advantages for the user. As a user it will only have to download the final container and be up and running once the download finishes. This makes the installation process fast and almost no chance of failure. This is the preferred method.
We have automated the process of building and publishing add-ons. See below for the instructions. We have automated the process of building and publishing add-ons. See below for the instructions.
#### Locally build containers #### Locally build containers
Starting with Supervisor 26, it is possible to distribute add-ons that will be built on the users machine. The advantage is that as a developer it is easy to test an idea and see if people are interested in your add-ons. This method includes installing and potentially compiling code. This means that installing such an add-on is slow and adds more wear and tear to users SD card/hard drive than the above mentioned pre-built solution. It also has a higher chance of failure if one of the dependencies of the container has changed or is no longer available. With the Supervisor, it is possible to distribute add-ons that will be built on the users machine. The advantage is that as a developer it is easy to test an idea and see if people are interested in your add-ons. This method includes installing and potentially compiling code. This means that installing such an add-on is slow and adds more wear and tear to users SD card/hard drive than the above mentioned pre-built solution. It also has a higher chance of failure if one of the dependencies of the container has changed or is no longer available.
Use this option when you are playing with add-ons and seeing if someone is interested in your work. Once you're an established repository, please migrate to pushing builds to Docker Hub as it greatly improves the user experience. In the future we will mark locally built add-ons in the add-on store to warn users. Use this option when you are playing with add-ons and seeing if someone is interested in your work. Once you're an established repository, please migrate to pushing builds to a container registry as it greatly improves the user experience. In the future we will mark locally built add-ons in the add-on store to warn users.
## Build scripts to publish add-ons to Docker Hub ## Build scripts to publish add-ons to a container registry
All add-ons are simple docker containers. Inside your add-on `config.json` you specify the Docker image that will be installed for your add-on: All add-ons are containers. Inside your add-on `config.yaml` you specify the container image that will be installed for your add-on:
```json ```yaml
{ ...
... image: "myhub/image-{arch}-addon-name"
"image": "myhub/image-{arch}-addon-name", ...
...
}
``` ```
You can use `{arch}` inside the image name to support multiple architectures with one (1) configuration file. It will be replaced with the architecture of the user when we load the image. If you use `Buildargs` you can use the `build.json` to overwrite our default args. You can use `{arch}` inside the image name to support multiple architectures with one (1) configuration file. It will be replaced with the architecture of the user when we load the image. If you use `Buildargs` you can use the `build.yaml` to overwrite our default args.
Home Assistant assumes that the default branch of your add-on repository matches the latest tag on Docker Hub. When you're building a new version, it's suggested that you use another branch, ie `build` or do it with a PR on GitHub. After you push the add-on to [Docker Hub](https://hub.docker.com/), you can merge this branch to master. Home Assistant assumes that the default branch of your add-on repository matches the latest tag on the container registry. When you're building a new version, it's suggested that you use another branch, ie `build` or do it with a PR on GitHub. After you push the add-on to a container registry, you can merge this branch to master.
## Custom Add-ons ## Custom Add-ons
You need a Docker Hub account to make your own add-ons. You can build your Docker images with the Docker `build` command or use our script that make it simple. Pull our [Builder Docker engine][builder] and run one of the following commands. You need a Docker Hub account to make your own add-ons. You can build your container images with the Docker `build` command or use our [builder] that make it simple. Pull our [Builder Docker engine][builder] and run one of the following commands.
For a git repository: For a git repository:
```shell ```shell
docker run --rm --privileged -v \ docker run \
~/.docker:/root/.docker homeassistant/amd64-builder \ --rm \
--all -t addon-folder -r https://github.com/xy/addons \ --privileged \
-v ~/.docker:/root/.docker \
homeassistant/amd64-builder \
--all \
-t addon-folder \
-r https://github.com/xy/addons \
-b branchname -b branchname
``` ```
For a local repository: For a local repository:
```shell ```shell
docker run --rm --privileged -v \ docker run \
~/.docker:/root/.docker -v /my_addon:/data homeassistant/amd64-builder \ --rm \
--all -t /data --privileged \
-v ~/.docker:/root/.docker \
-v /my_addon:/data \
homeassistant/amd64-builder \
--all \
-t /data
``` ```
:::tip :::tip

20
docs/add-ons/repository.md
View File

@ -10,17 +10,13 @@ Check the [Example add-on repository](https://github.com/home-assistant/addons-e
A user can add a repository by going to the Supervisor panel in Home Assistant, clicking on the store icon in the top right, copy/paste the URL of your repository into the repository textarea and click on **Save**. A user can add a repository by going to the Supervisor panel in Home Assistant, clicking on the store icon in the top right, copy/paste the URL of your repository into the repository textarea and click on **Save**.
:::tip
You can generate a [my.home-assistant.io](https://my.home-assistant.io/create-link/) for your users to do this with the click of a button in your readme file.
:::
## Repository configuration ## Repository configuration
Each repository is required to contain `repository.(json/yaml/yml)` at the root in the git repository. Each repository is required to contain `repository.yaml` at the root in the git repository.
```json
{
"name": "Name of repository",
"url": "http://www.example/addons",
"maintainer": "HomeAssistant Team <info@home-assistant.io>"
}
```
```yaml ```yaml
name: Name of repository name: Name of repository
@ -30,6 +26,6 @@ maintainer: HomeAssistant Team <info@home-assistant.io>
| Key | Required | Description | | Key | Required | Description |
| --- | -------- | ----------- | | --- | -------- | ----------- |
| name | yes | Name of the repository | `name` | yes | Name of the repository
| url | no | Homepage of the repository. Here you can explain the various add-ons. | `url` | no | Homepage of the repository. Here you can explain the various add-ons.
| maintainer | no | Contact info of the maintainer. | `maintainer` | no | Contact info of the maintainer.

10
docs/add-ons/security.md
View File

@ -12,11 +12,11 @@ For access to Supervisor API you need to define a role or you run in default mod
| Role | Description | | Role | Description |
|------|-------------| |------|-------------|
| default | Have access to all `info` calls | | `default` | Have access to all `info` calls |
| homeassistant | Can access all Home Assistant API endpoints | | `homeassistant` | Can access all Home Assistant API endpoints |
| backup | Can access all backup API endpoints | | `backup` | Can access all backup API endpoints |
| manager | Is for Add-ons that run CLIs and need extended rights | | `manager` | Is for Add-ons that run CLIs and need extended rights |
| admin | Have access to every API call. That is the only one they can disable/enable the Add-on protection mode | | `admin` | Have access to every API call. That is the only one they can disable/enable the Add-on protection mode |
## Protection ## Protection

66
docs/add-ons/testing.md
View File

@ -2,45 +2,42 @@
title: "Local add-on testing" title: "Local add-on testing"
--- ---
The fastest and recommended way to develop add-ons is using a local Visual Studio Code dev environment. The [Official Add-ons][hassio-addons] repository includes a dev container setup for VS Code which will run Supervisor and Home Assistant, with all of the add-ons mapped as Local Add-ons inside, making it simple for add-on developers on Windows, Mac and Linux desktop OS-es. The fastest and recommended way to develop add-ons is using a local Visual Studio Code devcontainer. We maintain a [devcontainer for this purpose](https://github.com/home-assistant/devcontainer) which is used in all our add-ons repositories. This devcontainer setup for VS Code which will run Supervisor and Home Assistant, with all of the add-ons mapped as Local Add-ons inside, making it simple for add-on developers on Windows, Mac and Linux desktop OS-es.
- Follow the instructions to download and install the [Remote Containers][remote-containers] VS Code extension. - Follow the instructions to download and install the [Remote Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) VS Code extension.
- Copy the `.devcontainer` and `.vscode` folder from [Official Add-ons][hassio-addons] repository into the root of your add-ons folders. - Copy the [`devcontainer.json` file](https://github.com/home-assistant/devcontainer/blob/main/addons/devcontainer.json) to `.devcontainer/devcontainer.json` in your repository.
- Open the root folder inside VS Code, and when prompted re-open the window inside the container (or, from the Command Palette, select 'Rebuild and Reopen in Container'). - Copy the [`tasks.json` file](https://github.com/home-assistant/devcontainer/blob/main/addons/tasks.json) to `.vscode/tasks.json` in your repository.
- When VS Code has opened your folder in the container (which can take some time for the first run) you'll need to run the task (Terminal -> Run Task) 'Start Home Assistant', which will bootstrap Supervisor and Home Assistant. - Open the root folder inside VS Code, and when prompted re-open the window inside the container (or, from the Command Palette, select 'Rebuild and Reopen in Container').
- When VS Code has opened your folder in the container (which can take some time for the first run) you'll need to run the task (Terminal -> Run Task) 'Start Home Assistant', which will bootstrap Supervisor and Home Assistant.
- You'll then be able to access the normal onboarding process via the Home Assistant instance at `http://localhost:7123/`. - You'll then be able to access the normal onboarding process via the Home Assistant instance at `http://localhost:7123/`.
- The add-on(s) found in your root folder will automatically be found in the Local Add-ons repository. - The add-on(s) found in your root folder will automatically be found in the Local Add-ons repository.
[hassio-addons]: https://github.com/home-assistant/hassio-addons
[remote-containers]: https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers
:::info
The bootstrap script `start_supervisor.sh` currently does not support Docker on Windows using the WSL 2 based engine. The message "_Timeout while waiting for docker to come up_" will appear in the terminal.
If you are using Docker Desktop and have Hyper-V support, you can switch back to legacy Hyper-V backend in Settings > General.
:::
## Remote development ## Remote development
If you require access to physical hardware or other resources that cannot be locally emulated (for example, serial ports), the next best option to develop add-ons is by adding them to the local add-on repository on a real device running Home Assistant. To access the local add-on repository on a remote device, install either the [Samba add-on] or [SSH add-on] and copy the add-on files to a subdirectory of `/addons`. If you require access to physical hardware or other resources that cannot be locally emulated (for example, serial ports), the next best option to develop add-ons is by adding them to the local add-on repository on a real device running Home Assistant. To access the local add-on repository on a remote device, install either the [Samba](https://my.home-assistant.io/redirect/supervisor_addon/?addon=core_samba) or the [SSH](https://my.home-assistant.io/redirect/supervisor_addon/?addon=core_ssh) add-ons and copy the add-on files to a subdirectory of `/addons`.
Right now add-ons will work with images that are stored on Docker Hub (using `image` from add-on config). To ensure that the add-on is built locally and not fetched from an upstream repository, ensure that the `image` key is *not* present in your `config.json`. Right now add-ons will work with images that are stored on Docker Hub (using `image` from add-on config). To ensure that the add-on is built locally and not fetched from an upstream repository, ensure that the `image` key is commented out in your `config.yaml` file (You can do that by adding a `#` in front of it, like `#image: xxx`).
[Samba add-on]: https://www.home-assistant.io/addons/samba/
[SSH add-on]: https://www.home-assistant.io/addons/ssh/
## Local build ## Local build
If you don't want to use the devcontainer environment, you can still build add-ons locally with Docker. The recommended method is to use the [official build tool][hassio-builder] to create the Docker images. If you don't want to use the devcontainer environment, you can still build add-ons locally with Docker. The recommended method is to use the [official build tool][hassio-builder] to create the Docker images.
Assuming that your addon is in the folder `/path/to/addon` and your Docker socket is at `/var/run/docker.sock`, you can build the addon for all supported architectures by running the following: Assuming that your addon is in the folder `/path/to/addon` and your Docker socket is at `/var/run/docker.sock`, you can build the addon for all supported architectures by running the following:
```
docker run --rm -ti --name hassio-builder --privileged \ ```shell
docker run \
--rm \
-it \
--name builder \
--privileged \
-v /path/to/addon:/data \ -v /path/to/addon:/data \
-v /var/run/docker.sock:/var/run/docker.sock:ro \ -v /var/run/docker.sock:/var/run/docker.sock:ro \
homeassistant/amd64-builder -t /data --all --test \ homeassistant/amd64-builder \
-i my-test-addon-{arch} -d local -t /data \
--all \
--test \
-i my-test-addon-{arch} \
-d local
``` ```
If you don't want to use the official build tool, you can still build with standalone Docker. If you use `FROM $BUILD_FROM` you'll need to set a base image with build args. Normally you can use follow base images: If you don't want to use the official build tool, you can still build with standalone Docker. If you use `FROM $BUILD_FROM` you'll need to set a base image with build args. Normally you can use follow base images:
@ -50,10 +47,13 @@ If you don't want to use the official build tool, you can still build with stand
- amd64: `homeassistant/amd64-base:latest` - amd64: `homeassistant/amd64-base:latest`
- i386: `homeassistant/i386-base:latest` - i386: `homeassistant/i386-base:latest`
Use `docker` from the directory containing the add-on files to build the test addon: Use `docker` from the directory containing the add-on files to build the test addon:
```
docker build --build-arg BUILD_FROM="homeassistant/amd64-base:latest" \ ```shell
-t local/my-test-addon . docker build \
--build-arg BUILD_FROM="homeassistant/amd64-base:latest" \
-t local/my-test-addon \
.
``` ```
[hassio-builder]: https://github.com/home-assistant/hassio-builder [hassio-builder]: https://github.com/home-assistant/hassio-builder
@ -62,9 +62,13 @@ docker build --build-arg BUILD_FROM="homeassistant/amd64-base:latest" \
If you don't want to use the devcontainer environment, you can still run add-ons locally with Docker. If you don't want to use the devcontainer environment, you can still run add-ons locally with Docker.
Create a new folder for data and add a test _options.json_ file. After that you can run your add-on with: Create a new folder for data and add a test _options.json_ file. After that you can run your add-on with:
```
docker run --rm -v /tmp/my_test_data:/data -p PORT_STUFF_IF_NEEDED \ ```shell
docker run \
--rm \
-v /tmp/my_test_data:/data \
-p PORT_STUFF_IF_NEEDED \
local/my-test-addon local/my-test-addon
``` ```

166
docs/add-ons/tutorial.md
View File

@ -2,37 +2,36 @@
title: "Tutorial: Making your first add-on" title: "Tutorial: Making your first add-on"
--- ---
So you've got Home Assistant going and you've been enjoying the built-in add-ons but you're missing this one application. Time to make your own add-on! In Supervisor 24 we introduced the option to have local add-ons be built on your device. This is great for developing new add-ons locally. So you've got Home Assistant going and you've been enjoying the built-in add-ons but you're missing this one application. Time to make your own add-on!
To get started with developing add-ons, we first need access to where Home Assistant looks for local add-ons. For this you can use the Samba add-on or the SSH add-on. To get started with developing add-ons, we first need access to where Home Assistant looks for local add-ons. For this you can use the [Samba](https://my.home-assistant.io/redirect/supervisor_addon/?addon=core_samba) or the [SSH](https://my.home-assistant.io/redirect/supervisor_addon/?addon=core_ssh) add-ons.
For Samba, once you have enabled and started it, your Home Assistant instance will show up in your local network tab and share a folder called "addons". This is the folder to store your custom add-ons. For Samba, once you have enabled and started it, your Home Assistant instance will show up in your local network tab and share a folder called "addons". This is the folder to store your custom add-ons.
If you are on macOS and the folder is not showing up automatically, go to Finder and press CMD+K then enter 'smb://homeassistant.local' :::tip
If you are on macOS and the folder is not showing up automatically, go to Finder and press CMD+K then enter `smb://homeassistant.local`
:::
![Screenshot of Windows Explorer showing a folder on the Home Assistant server](/img/en/hass.io/tutorial/samba.png) For SSH, you will have to install it. Before you can start it, you will have to have a private/public key pair and store your public key in the add-on config ([see docs for more info](https://github.com/home-assistant/addons/blob/master/ssh/DOCS.md#configuration)). Once started, you can SSH to Home Assistant and store your custom add-ons in the `/addons` directory.
For SSH, you will have to install it. Before you can start it, you will have to have a private/public key pair and store your public key in the add-on config ([see docs for more info][ssh]). Once started, you can SSH to Home Assistant and store your custom add-ons in "/addons".
![Screenshot of Putty connected to Home Assistant](/img/en/hass.io/tutorial/ssh.png)
Once you have located your add-on directory, it's time to get started! Once you have located your add-on directory, it's time to get started!
[ssh]: https://www.home-assistant.io/addons/ssh/
## Step 1: The basics ## Step 1: The basics
- Create a new directory called `hello_world` - Create a new directory called `hello_world`
- Inside that directory create three files. - Inside that directory create three files:
- `Dockerfile`
- `config.yaml`
- `run.sh`
`Dockerfile`: ### The `Dockerfile` file
This is the image that will be used to build your add-on.
```dockerfile ```dockerfile
ARG BUILD_FROM ARG BUILD_FROM
FROM $BUILD_FROM FROM $BUILD_FROM
ENV LANG C.UTF-8
# Copy data for add-on # Copy data for add-on
COPY run.sh / COPY run.sh /
RUN chmod a+x /run.sh RUN chmod a+x /run.sh
@ -40,51 +39,59 @@ RUN chmod a+x /run.sh
CMD [ "/run.sh" ] CMD [ "/run.sh" ]
``` ```
`config.json`: ### The `config.yaml` file
```json This is your add-on configuration, which tell the Supervisor what to do and how to present your add-on.
{
"name": "Hello world", For an overview of all valid add-on configuration options have a look [here](/docs/add-ons/configuration#add-on-configuration)
"version": "1",
"slug": "hello_world", ```yaml
"description": "My first real add-on!", name: "Hello world"
"arch": ["armhf", "armv7", "aarch64", "amd64", "i386"], description: "My first real add-on!"
"startup": "application", version: "1.0.0"
"boot": "auto", slug: "hello_world"
"options": {}, arch:
"schema": {} - aarch64
} - amd64
- armhf
- armv7
- i386
``` ```
`run.sh`: ### The `run.sh` file
This is the script that will run when your add-on starts.
```shell ```shell
#!/usr/bin/with-contenv bashio #!/usr/bin/with-contenv bashio
echo Hello world! echo "Hello world!"
``` ```
:::note
Make sure your editor is using UNIX-like line breaks (LF), not Dos/Windows (CRLF). Make sure your editor is using UNIX-like line breaks (LF), not Dos/Windows (CRLF).
:::
## Step 2: Installing and testing your add-on ## Step 2: Installing and testing your add-on
Now comes the fun part, time to open the Home Assistant UI and install and run your add-on. Now comes the fun part, time to open the Home Assistant UI and install and run your add-on.
- Open the Home Assistant frontend - Open the Home Assistant frontend
- Go to the Supervisor panel - Go to "Configuration"
- On the top right click the shopping basket to go to the add-on store. - Click on "Add-ons, backups & Supervisor"
- Click "add-on store" in the bottom right corner.
![Screenshot of the Home Assistant Supervisor main panel](/img/en/hass.io/screenshots/main_panel_addon_store.png) [![Open your Home Assistant instance and show the Supervisor add-on store.](https://my.home-assistant.io/badges/supervisor_store.svg)](https://my.home-assistant.io/redirect/supervisor_store/)
- On the top right overflow menu, click the "Reload" button - On the top right overflow menu, click the "Reload" button
- You should now see a new card called "Local" that lists your add-on! - You should now see a new section at the top of the store called "Local add-ons" that lists your add-on!
![Screenshot of the local repository card](/img/en/hass.io/screenshots/local_repository.png) ![Screenshot of the local repository card](/img/en/hass.io/screenshots/local_repository.png)
- Click on your add-on to go to the add-on details page. - Click on your add-on to go to the add-on details page.
- Install your add-on - Install your add-on
- Start your add-on - Start your add-on
- Refresh the logs of your add-on, you should now see "Hello world!" in your logs. - Click on the "Logs" tab, and refresh the logs of your add-on, you should now see "Hello world!" in your logs.
![Screenshot of the add-on logs](/img/en/hass.io/tutorial/addon_hello_world_logs.png) ![Screenshot of the add-on logs](/img/en/hass.io/tutorial/addon_hello_world_logs.png)
@ -92,7 +99,7 @@ Now comes the fun part, time to open the Home Assistant UI and install and run y
Oops! You clicked "Reload" in the store and your add-on didn't show up. Or maybe you just updated an option, clicked refresh and saw your add-on disappear. Oops! You clicked "Reload" in the store and your add-on didn't show up. Or maybe you just updated an option, clicked refresh and saw your add-on disappear.
When this happens, it means that your `config.json` is invalid. It's either invalid JSON or one of the specified options is incorrect. To see what went wrong, go to the Supervisor panel and in the supervisor card click on "View logs". This should bring you to a page with the logs of the supervisor. Scroll to the bottom and you should be able to find the validation error. When this happens, it means that your `config.yaml` is invalid. It's either [invalid YAML](http://www.yamllint.com/) or one of the specified options is incorrect. To see what went wrong, go to the Supervisor panel and in the supervisor card click on "View logs". This should bring you to a page with the logs of the supervisor. Scroll to the bottom and you should be able to find the validation error.
Once you fixed the error, go to the add-on store and click "Reload" again. Once you fixed the error, go to the add-on store and click "Reload" again.
@ -103,7 +110,7 @@ Until now we've been able to do some basic stuff, but it's not very useful yet.
To do this, we will need to update our files as follows: To do this, we will need to update our files as follows:
- `Dockerfile`: Install Python 3 - `Dockerfile`: Install Python 3
- `config.json`: Make the port from the container available on the host - `config.yaml`: Make the port from the container available on the host
- `run.sh`: Run the Python 3 command to start the HTTP server - `run.sh`: Run the Python 3 command to start the HTTP server
Update your `Dockerfile`: Update your `Dockerfile`:
@ -112,10 +119,10 @@ Update your `Dockerfile`:
ARG BUILD_FROM ARG BUILD_FROM
FROM $BUILD_FROM FROM $BUILD_FROM
ENV LANG C.UTF-8
# Install requirements for add-on # Install requirements for add-on
RUN apk add --no-cache python3 RUN \
apk add --no-cache \
python3
# Python 3 HTTP Server serves the current working dir # Python 3 HTTP Server serves the current working dir
# So let's set it to our add-on persistent data directory. # So let's set it to our add-on persistent data directory.
@ -128,23 +135,22 @@ RUN chmod a+x /run.sh
CMD [ "/run.sh" ] CMD [ "/run.sh" ]
``` ```
Add "ports" to `config.json`. This will make TCP on port 8000 inside the container available on the host on port 8000. Add "ports" to `config.yaml`. This will make TCP on port 8000 inside the container available on the host on port 8000.
```json ```yaml
{ name: "Hello world"
"name": "Hello world", description: "My first real add-on!"
"version": "0.2", version: "1.1.0"
"slug": "hello_world", slug: "hello_world"
"description": "My first real add-on!", arch:
"arch": ["armhf", "armv7", "aarch64", "amd64", "i386"], - aarch64
"startup": "before", - amd64
"boot": "auto", - armhf
"options": {}, - armv7
"schema": {}, - i386
"ports": { startup: before
"8000/tcp": 8000 ports:
} 8000/tcp: 8000
}
``` ```
Update `run.sh` to start the Python 3 server: Update `run.sh` to start the Python 3 server:
@ -152,14 +158,14 @@ Update `run.sh` to start the Python 3 server:
```shell ```shell
#!/usr/bin/with-contenv bashio #!/usr/bin/with-contenv bashio
echo Hello world! echo "Hello world!"
python3 -m http.server 8000 python3 -m http.server 8000
``` ```
## Step 4: Installing the update ## Step 4: Installing the update
Since we updated the version number in our `config.json`, Home Assistant will show an update button when looking at the add-on details. You might have to refresh your browser or click the "Reload" button in the add-on store for it to show up. If you did not update the version number, you can also uninstall and install the add-on again. After installing the add-on again, make sure you start it. Since we updated the version number in our `config.yaml`, Home Assistant will show an update button when looking at the add-on details. You might have to refresh your browser or click the "Reload" button in the add-on store for it to show up. If you did not update the version number, you can also uninstall and install the add-on again. After installing the add-on again, make sure you start it.
Now navigate to [http://homeassistant.local:8000](http://homeassistant.local:8000) to see our server in action! Now navigate to [http://homeassistant.local:8000](http://homeassistant.local:8000) to see our server in action!
@ -167,35 +173,31 @@ Now navigate to [http://homeassistant.local:8000](http://homeassistant.local:800
## Bonus: Working with add-on options ## Bonus: Working with add-on options
In the screenshot you've probably seen that our server only served up 1 file: `options.json`. This file contains the user configuration for this add-on. Because we specified an empty "config" and "schema" in our `config.json`, the file is currently empty. In the screenshot you've probably seen that our server only served up 1 file: `options.json`. This file contains the user configuration for this add-on. Because we specified an empty "config" and "schema" in our `config.yaml`, the file is currently empty.
Let's see if we can get some data into that file! Let's see if we can get some data into that file!
To do this, we need to specify the default options and a schema for the user to change the options. To do this, we need to specify the default options and a schema for the user to change the options. Change the options and schema entries in your `config.yaml` with the following:
Change the options and schema entries in your `config.json` with the following: ```yaml
...
```json options:
{ beer: true
… wine: true
liquor: false
"options": { name: "world"
"beer": true, year: 2017
"wine": true, schema:
"liquor": false, beer: bool
"name": "world", wine: bool
"year": 2017 liquor: bool
}, name: str
"schema": { year: int
"beer": "bool", ...
"wine": "bool",
"liquor": "bool",
"name": "str",
"year": "int"
},
…
}
``` ```
Reload the add-on store and re-install your add-on. You will now see the options available in the add-on config screen. When you now go back to our Python 3 server and download `options.json`, you'll see the options you set. [Example of how options.json can be used inside `run.sh`](https://github.com/home-assistant/addons/blob/master/dhcp_server/data/run.sh#L10-L13) Reload the add-on store and re-install your add-on. You will now see the options available in the add-on config screen. When you now go back to our Python 3 server and download `options.json`, you'll see the options you set. [Example of how options.json can be used inside `run.sh`](https://github.com/home-assistant/addons/blob/master/dhcp_server/data/run.sh#L10-L13)
## Bonus: Template add-on repository
We maintain a full template example repository for add-ons you can use to get started. You can find that in the [`home-assistant/addons-example` repository](https://github.com/home-assistant/addons-example).

BIN
static/img/en/hass.io/screenshots/local_repository.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 4.3 KiB

After

Width:  |  Height:  |  Size: 7.1 KiB

BIN
static/img/en/hass.io/screenshots/main_panel_addon_store.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 9.2 KiB

BIN
static/img/en/hass.io/tutorial/samba.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 4.7 KiB