diff --git a/docs/add-ons/communication.md b/docs/add-ons/communication.md index 6ca524d4..1f8797eb 100644 --- a/docs/add-ons/communication.md +++ b/docs/add-ons/communication.md @@ -2,14 +2,14 @@ title: "Add-On Communication" --- -There are different ways for communication between add-ons inside Home Assistant. +There are different ways of communicating between add-ons inside Home Assistant. ## Network We use an internal network that's allowed to communicate with every add-on, including to/from Home Assistant, by using its name or alias. Only add-ons that run on the host network are limited in that they can talk with all internal add-ons by their name, but all other add-ons can't address these add-ons by name. However, using an alias works for both! Names/aliases are used for communication inside Home Assistant. -The name is generated using the following format: `{REPO}_{SLUG}`, e.g., `local_xy` or `3283fh_myaddon`. In this example, `{SLUG}` is defined in an add-on's `config.yaml` file. You can use this name as the DNS name also, but you need replace any `_` with `-` to have a valid hostname. If an add-on is installed locally, `{REPO}` will be `local`. If the add-on is installed from a Github repository, `{REPO}` is a hashed identifier generated from the GitHub repository's URL (ex: `https://github.com/xy/my_hassio_addons`). See [here](https://github.com/home-assistant/supervisor/blob/587047f9d648b8491dc8eef17dc6777f81938bfd/hassio/addons/utils.py#L17) to understand how this identifier is generated. Note that this identifier is required in certain service calls that use the [Supervisor add-on API][supervisor-addon-api]. You can view the repository identifiers for all currently installed add-ons via a GET request to the Supervisor API `addons` endpoint. +The name is generated using the following format: `{REPO}_{SLUG}`, e.g., `local_xy` or `3283fh_myaddon`. In this example, `{SLUG}` is defined in an add-on's `config.yaml` file. You can use this name as the DNS name also, but you need to replace any `_` with `-` to have a valid hostname. If an add-on is installed locally, `{REPO}` will be `local`. If the add-on is installed from a Github repository, `{REPO}` is a hashed identifier generated from the GitHub repository's URL (ex: `https://github.com/xy/my_hassio_addons`). See [here](https://github.com/home-assistant/supervisor/blob/587047f9d648b8491dc8eef17dc6777f81938bfd/hassio/addons/utils.py#L17) to understand how this identifier is generated. Note that this identifier is required in certain service calls that use the [Supervisor add-on API][supervisor-addon-api]. You can view the repository identifiers for all currently installed add-ons via a GET request to the Supervisor API `addons` endpoint. Use `supervisor` for communication with the internal API. @@ -43,7 +43,7 @@ Add-ons can call some API commands without needing to set `hassio_api: true`: ## Services API -We have an internal services API to make services public to other add-ons without the user need to add additional configuration. An add-on can get the full configuration for a service to use and to connect to. The add-on need to mark the usage of a service over his [configuration](configuration.md) in order to be able to access a service. All supported services, including its available options, are documented in the [API documentation][supervisor-services-api]. +We have an internal services API to make services public to other add-ons without the user needing to add any configuration. An add-on can get the full configuration for a service to use and to connect to it. The add-on needs to mark the usage of a service in the add-on [configuration](configuration.md) in order to be able to access a service. All supported services, including its available options, are documented in the [API documentation][supervisor-services-api]. Supported services are: diff --git a/docs/add-ons/configuration.md b/docs/add-ons/configuration.md index 55038e50..af33e73a 100644 --- a/docs/add-ons/configuration.md +++ b/docs/add-ons/configuration.md @@ -23,14 +23,14 @@ addon_name/ :::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` +To keep it simple all examples use `.yaml` ::: ## 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. -All our images have also [bashio][bashio] installed. It contains a set of commonly used operations and can be used to be included in add-ons to reduce code duplication across add-ons and therefore making it easier to develop and maintain add-ons. +All our images also have [bashio][bashio] installed. It contains a set of commonly used operations and can be used to be included in add-ons to reduce code duplication across add-ons, therefore making it easier to develop and maintain add-ons. When developing your script: @@ -55,7 +55,7 @@ then there will be a variable `TARGET` containing `beer` in the environment of y ## Add-on Dockerfile -All add-ons are based on latest Alpine Linux image. Home Assistant will automatically substitute the right base image based on the machine architecture. Add `tzdata` if you need run in a different timezone. `tzdata` Is is already added to our base images. +All add-ons are based on the latest Alpine Linux image. Home Assistant will automatically substitute the right base image based on the machine architecture. Add `tzdata` if you need to run in a different timezone. `tzdata` Is is already added to our base images. ```dockerfile ARG BUILD_FROM @@ -73,7 +73,7 @@ RUN chmod a+x /run.sh 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 the device or our build script, make sure that the Dockerfile also has a set of labels that include: ```dockerfile LABEL \ @@ -106,7 +106,7 @@ description: >- "Long description" arch: - amd64 -url: "website with more information about add-on (e.g., a forum thread for support)" +url: "website with more information about the add-on (e.g., a forum thread for support)" ports: 123/tcp: 123 map: @@ -131,68 +131,68 @@ Note: Avoid the use of this filename for anything other than add-on configurati | Key | Type | Default | Description | | --- | ---- | -------- | ----------- | -| `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. -| `url` | url | | Homepage of the add-on. Here you can explain the add-ons and options. -| `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. -| `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`. -| `boot` | string | `auto` | `auto` start at boot is controlled by the system. `manual` for only manual starting. +| `machine` | list | | Default is support of all machine types. You can configure the add-on to only run on specific machines. You can use `!` before a machine type to negate it. +| `url` | url | | Homepage of the add-on. Here you can explain the add-on and options. +| `startup` | string | `application` | `initialize` will start the 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. +| `webui` | string | | A 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 option with: `[PROTO:option_name]://[HOST]:[PORT:2839]/dashboard` and it's looked up if it is `true` and it's going to `https`. +| `boot` | string | `auto` | `auto` start at boot is controlled by the system. `manual` configures the add-on to only be started manually. | `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. | `ports_description` | dict | | Network ports description mapping. Format is `"container-port/type": "description of this port"`. Alternatively use [Port description translations](#port-description-translations). -| `host_network` | bool | `false` | If `true`, the add-on runs on host network. -| `host_ipc` | bool | `false` | Allow to share the IPC namespace with others. +| `host_network` | bool | `false` | If `true`, the add-on runs on the host network. +| `host_ipc` | bool | `false` | Allow the IPC namespace to be shared with others. | `host_dbus` | bool | `false` | Map the host D-Bus service into the add-on. -| `host_pid` | bool | `false` | Allow to run container on host PID namespace. Works only for not protected add-ons. **Warning:** Does not work with S6 Overlay. If need this to be `true` and you use the normal add-on base image you disable S6 by overriding `/init`. Or use an alternate base image. +| `host_pid` | bool | `false` | Allow the container to run on the host PID namespace. Works only for not protected add-ons. **Warning:** Does not work with S6 Overlay. If need this to be `true` and you use the normal add-on base image you disable S6 by overriding `/init`. Or use an alternate base image. | `devices` | list | | Device list to map into the add-on. Format is: ``. E.g., `/dev/ttyAMA0` -| `homeassistant` | string | | Pin a minimum required Home Assistant Core version for the add-on. Value is a version string like `0.91.2`. +| `homeassistant` | string | | Pin a minimum required Home Assistant Core version for the add-on. Value is a version string like `2022.10.5`. | `hassio_role` | str | `default` |Role-based access to Supervisor API. Available: `default`, `homeassistant`, `backup`, `manager` or `admin` | `hassio_api` | bool | `false` | This add-on can access the Supervisor's REST API. Use `http://supervisor`. -| `homeassistant_api` | bool | `false` | This add-on can access to the Home Assistant REST API proxy. Use `http://supervisor/core/api`. -| `docker_api` | bool | `false` | Allow read-only access to Docker API for add-on. Works only for not protected add-ons. +| `homeassistant_api` | bool | `false` | This add-on can access the Home Assistant REST API proxy. Use `http://supervisor/core/api`. +| `docker_api` | bool | `false` | Allow read-only access to the Docker API for the add-on. Works only for not protected add-ons. | `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` -| `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. -| `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. +| `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` as this is not needed. +| `apparmor` | bool/string | `false` | Enable or disable AppArmor support. If it is enabled, you can also use custom profiles with the name of the profile. | `map` | list | | List of Home Assistant directories to bind mount into your container. 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. -| `environment` | dict | | A dictionary of environment variable to run add-on. -| `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`. +| `environment` | dict | | A dictionary of environment variables to run the add-on with. +| `audio` | bool | `false` | Mark this add-on to use the internal audio system. We map a working PulseAudio setup into the container. If your application does not support PulseAudio, you may need to install: Alpine Linux `alsa-plugins-pulse` or Debian/Ubuntu `libasound2-plugins`. | `video` | bool | `false` | Mark this add-on to use the internal video system. All available devices will be mapped into the add-on. -| `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. -| `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. +| `gpio` | bool | `false` | If this is set to `true`, `/sys/class/gpio` will map into the add-on for access to the GPIO interface from the 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. +| `usb` | bool | `false` | If this is set to `true`, it would map the raw USB access `/dev/bus/usb` into the add-on with plug&play support. | `uart` | bool | `false` | Default `false`. Auto mapping all UART/serial devices from the host into the add-on. -| `udev` | bool | `false` | Default `false`. Set this `true`, gets the host udev database read-only mounted into the add-on. -| `devicetree` | bool | `false` | If this is set to True, `/device-tree` will map into add-on. -| `kernel_modules` | bool | `false` | Map host kernel modules and config into add-on (readonly) and give you SYS_MODULE permission. +| `udev` | bool | `false` | Default `false`. Setting this to `true` gets the host udev database read-only mounted into the add-on. +| `devicetree` | bool | `false` | If this is set to `true`, `/device-tree` will map into the add-on. +| `kernel_modules` | bool | `false` | Map host kernel modules and config into the add-on (readonly) and give you `SYS_MODULE` permission. | `stdin` | bool | `false` | If enabled, you can use the STDIN with Home Assistant API. | `legacy` | bool | `false` | If the Docker image has no `hass.io` labels, you can enable the legacy mode to use the config data. | `options` | dict | | Default options value of the add-on. | `schema` | dict | | Schema for options value of the add-on. It can be `false` to disable schema validation and options. | `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. | `codenotary` | string | | For use with Codenotary CAS. This is the E-Mail address used to verify your image with Codenotary (E.g, `example@home-assistant.io`). This should match the E-Mail address used as the signer in the [add-on's extended build options](#add-on-extended-build) -| `timeout` | integer | | Default 10 (seconds). The timeout to wait until the Docker daemon is done or will be killed. -| `tmpfs` | bool | `false` | If this is set to `true`, the containers `/tmp` is using tmpfs, a memory file system. +| `timeout` | integer | 10 | Default 10 (seconds). The timeout to wait until the Docker daemon is done or will be killed. +| `tmpfs` | bool | `false` | If this is set to `true`, the containers `/tmp` uses tmpfs, a memory file system. | `discovery` | list | | A list of services that this add-on provides for Home Assistant. Currently supported: `mqtt` -| `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). +| `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 needs this service to work correctly). | `auth_api` | bool | `false` | Allow access to Home Assistant user backend. | `ingress` | bool | `false` | Enable the ingress feature for the add-on. -| `ingress_port` | integer | `8099` | For add-ons that run on the host network, you can use `0` and read the port later via API. +| `ingress_port` | integer | `8099` | For add-ons that run on the host network, you can use `0` and read the port later via the API. | `ingress_entry` | string | `/` | Modify the URL entry point. -| `ingress_stream` | bool | `false` | When enabled requests to the add-on are streamed +| `ingress_stream` | bool | `false` | When enabled, requests to the add-on are streamed | `panel_icon` | string | `mdi:puzzle` | [MDI icon](https://materialdesignicons.com/) for the menu panel integration. | `panel_title` | string | | Defaults to the add-on name, but can be modified with this option. -| `panel_admin` | bool | `true` | Make menu entry only available with users in the admin group. +| `panel_admin` | bool | `true` | Make the menu entry only available to users in the admin group. | `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). | `backup_pre` | string | | Command to execute in the context of the add-on before the backup is taken. | `backup_post` | string | | Command to execute in the context of the add-on after the backup was taken. -| `backup_exclude` | list | | List of file/path (with glob support) that are excluded from backups. +| `backup_exclude` | list | | List of files/paths (with glob support) that are excluded from backups. | `advanced` | bool | `false` | Set this to `true` to require the user to have enabled "Advanced" mode for it to show. | `stage` | string | `stable` | Flag add-on with follow attribute: `stable`, `experimental` or `deprecated`. Add-ons set to `experimental` or `deprecated` will not show up in the store unless the user enables advanced mode. | `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)). *Note: Starting in V3 of S6 setting this to `false` is required or the addon won't start, see [here](https://developers.home-assistant.io/blog/2022/05/12/s6-overlay-base-images) for more information.* -| `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. +| `watchdog` | string | | A URL for monitoring the add-on health. 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 option 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 works for add-ons on the host or internal network. | `realtime` | bool | `false` | Give add-on access to host schedule including `SYS_NICE` for change execution time/priority. | `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. ### 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. Nested arrays and dictionaries are supported with a maximum depth of two. To make an option optional, put `?` at the end of the data type, otherwise it will be a required value. ```yaml message: "custom things" @@ -236,12 +236,12 @@ We support: - `port` - `match(REGEX)` - `list(val1|val2|...)` -- `device` / `device(filter)`: Device filter can be following format: `subsystem=TYPE` i.e. `subsystem=tty` for serial devices. +- `device` / `device(filter)`: Device filter can be in the following format: `subsystem=TYPE` i.e. `subsystem=tty` for serial devices. ## Add-on extended build -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. +Additional build options for an add-on are stored in `build.yaml`. This file will be read from our build systems. +This is only needed if you are not using the default images or need additional things. ```yaml build_from: @@ -253,15 +253,15 @@ args: | Key | Required | Description | | --- | -------- | ----------- | -| build_from | no | A dictionary with the hardware architecture as the key and the base Docker image as value. +| build_from | no | A dictionary with the hardware architecture as the key and the base Docker image as the value. | squash | no | Default `False`. Be careful with this option, as you can not use the image for caching stuff after that! -| args | no | Allow to set additional Docker build arguments as a dictionary. -| labels | no | Allow to set additional Docker labels as a dictionary. -| codenotary | no | Allows to enable container signature with codenotary CAS. +| args | no | Allow additional Docker build arguments as a dictionary. +| labels | no | Allow additional Docker labels as a dictionary. +| codenotary | no | Enable container signature with codenotary CAS. | codenotary.signer | no | Owner signer E-Mail address for this image. | codenotary.base_image | no | Verify the base container image. If you use our official images, use `notary@home-assistant.io` -We provide a set of [base images][docker-base] which should cover a lot of needs. If you don't want use the Alpine based version or need a specific image tag, feel free to pin this requirements for you build with `build_from` option. +We provide a set of [base images][docker-base] which should cover a lot of needs. If you don't want to use the Alpine based version or need a specific image tag, feel free to pin this requirement for your build with the `build_from` option. [docker-base]: https://github.com/home-assistant/docker-base @@ -273,7 +273,7 @@ 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. -This file support 2 main keys `configuration` and `network`. +This file supports 2 main keys `configuration` and `network`. ### Configuration translations diff --git a/docs/add-ons/presentation.md b/docs/add-ons/presentation.md index 9a652ed9..cc37ef24 100644 --- a/docs/add-ons/presentation.md +++ b/docs/add-ons/presentation.md @@ -2,11 +2,11 @@ title: "Presenting your addon" --- -If you decide to share your add-on to the public, paying attention to details is recommended. Of course, your add-on should have a proper name and description, but Home Assistant also gives you some other tools to present your add-on even nicer. +If you choose to make your add-on available to the public, providing clear information, graphics and security reassurances will help attract users. The recommendations below are a guideline for presenting your add-on. ## Adding intro -This shows in add-on store and give the user a short instruction what the addon can. +This shows in the add-on store and gives the user a short description of what the add-on can do. This file containing the intro is usually referred to as the "README", which is generally published as the `README.md` file. @@ -18,13 +18,13 @@ This file containing the documentation is usually referred to as the "DOCS", whi ## Add-on icon & logo -A picture is worth a thousand words. Therefore, your add-on can be improved by adding a proper image icon and logo. Those images are used when showing your add-on in the Home Assistant Supervisor panel and which will significantly improve the visual representation of your add-on. +A picture is worth a thousand words. Therefore, your add-on can be improved by adding a proper image icon and logo. These images are used when showing your add-on in the Home Assistant Supervisor panel and will significantly improve the visual representation of your add-on. Requirements for the logo of your add-on: - The logo must be in the Portable Network Graphics format (`.png`). - The filename must be `logo.png`. -- It is recommended to keep the logo size around 250x100px. You may choose to use a different size or aspect ratio as you seem fit for your add-on. +- It is recommended to keep the logo size around 250x100px. You may choose to use a different size or aspect ratio as you see fit for your add-on. Requirements for the icon of your add-on: @@ -35,15 +35,15 @@ Requirements for the icon of your add-on: ## Keeping a changelog -It is likely you are going to release newer versions of your add-on in the future. In case that happens, the users of your add-on would see an upgrade notice and probably want to know what changes were made in the latest version. +It is likely you are going to release newer versions of your add-on in the future. In case that happens, the users of your add-on will see an upgrade notice and probably want to know what changes were made in the latest version. A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of your add-on and is generally published as the `CHANGELOG.md` file. -If you are in need of a guide on keeping a changelog, we would recommend checking the [keep a changelog](http://keepachangelog.com) website. They have developed a standard that is used by many open source projects around the world. +For guidance on keeping a changelog, we recommend the [keep a changelog](http://keepachangelog.com) website. They have developed a standard used by many open source projects around the world. ## AppArmor -In the event, an API call returns something you, as a developer were not expecting, access to too many resources could be a liability for your users. As an add-on developer, it is your responsibility to ensure your add-on will not ruin your user's machine, or perform actions that you would never expect. That's where AppArmor comes in. +In the event that an API call returns something you, as a developer were not expecting, access to too many resources could be a liability for your users. As an add-on developer, it is your responsibility to ensure your add-on will not ruin your user's machine, or perform actions that you would never expect. That's where AppArmor comes in. While your talents in input validation, handling sensitive data and other defensive programming tactics are not being judged here, AppArmor is your add-on's second line of defense against malicious API calls, malformed settings or other forms of system hijacking. diff --git a/docs/add-ons/publishing.md b/docs/add-ons/publishing.md index b23211bf..2ddaa990 100644 --- a/docs/add-ons/publishing.md +++ b/docs/add-ons/publishing.md @@ -6,7 +6,7 @@ There are two different ways of publishing add-ons. One is to publish pre-built #### 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 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. +With pre-built containers, the developer is responsible for building the images for each architecture on their machine and pushing the results out to a container registry. This has a lot of advantages for the user who will only have to download the final container and be up and running once the download finishes. This makes the installation process fast and has almost no chance of failure so it is the preferred method. We have automated the process of building and publishing add-ons. See below for the instructions. @@ -32,7 +32,7 @@ Home Assistant assumes that the default branch of your add-on repository matches ## Custom Add-ons -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. +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] to simplify the process. Pull our [Builder Docker engine][builder] and run one of the following commands. For a git repository: diff --git a/docs/add-ons/security.md b/docs/add-ons/security.md index 00a0bb3b..4f7a9e14 100644 --- a/docs/add-ons/security.md +++ b/docs/add-ons/security.md @@ -6,7 +6,7 @@ Home Assistant rates every add-on based on the wanted rights. An add-on with a r ## API Role -For access to Supervisor API you need to define a role or you run in default mode. This is only required for Supervisor API not Home Assistant proxy. Any of the roles already have access to the default API calls, and do not require any additional settings. +For access to the Supervisor API you need to define a role or run in default mode. This is only required for the Supervisor API and not the Home Assistant proxy. All of the roles already have access to the default API calls, and do not require any additional settings. ### Available Roles @@ -20,7 +20,7 @@ For access to Supervisor API you need to define a role or you run in default mod ## Codenotary CAS -You can sign your images and also verify our base image which you build from to provide a full chain of trust. This feature us supported by our [Builder](https://github.com/home-assistant/builder) and the [build config](/docs/add-ons/configuration#add-on-extended-build). For enable this feature on the Supervisor for your Add-on, you simple need add your email address to the Add-on configuration `codenotary`. +You can sign your images and also verify our base image which you build from to provide a full chain of trust. This feature is supported by our [Builder](https://github.com/home-assistant/builder) and the [build config](/docs/add-ons/configuration#add-on-extended-build). To enable this feature on the Supervisor for your add-on, you simply need to add your email address to the add-on configuration `codenotary`. ## Protection @@ -38,4 +38,4 @@ As a developer, follow the following best practices to make your add-on secure: ## Use Home Assistant User backend -Instead of allowing users to set new login credential in plain text config, use the Home Assistant [Auth backend](/docs/api/supervisor/endpoints#auth). You can enable the access to API with `auth_api: true`. Now you are able to send the login credential to auth backend and validate it again Home Assistant. +Instead of allowing users to set new login credentials in plain text config, use the Home Assistant [Auth backend](/docs/api/supervisor/endpoints#auth). You can enable the access to the API with `auth_api: true`. Now you are able to send the login credentials to the auth backend and validate them in Home Assistant. diff --git a/docs/add-ons/testing.md b/docs/add-ons/testing.md index 0083fec3..f998e73a 100644 --- a/docs/add-ons/testing.md +++ b/docs/add-ons/testing.md @@ -2,7 +2,7 @@ title: "Local add-on testing" --- -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. +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-on repositories. This devcontainer setup for VS Code runs 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](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) VS Code extension. - Copy the [`devcontainer.json` file](https://github.com/home-assistant/devcontainer/raw/main/addons/devcontainer.json) to `.devcontainer.json` in your repository. @@ -40,7 +40,7 @@ docker run \ -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 following base images: - armhf: `homeassistant/armhf-base:latest` - aarch64: `homeassistant/aarch64-base:latest`