mirror of
https://github.com/home-assistant/developers.home-assistant.git
synced 2025-07-12 11:56:29 +00:00
Adjust documentation for add-ons (#826)
This commit is contained in:
parent
f94db5597c
commit
ee389906dc
@ -6,10 +6,12 @@ Each add-on is stored in a folder. The file structure looks like this:
|
||||
|
||||
```text
|
||||
addon_name/
|
||||
translations/
|
||||
en.(json/yaml/yml)
|
||||
apparmor.txt
|
||||
build.json
|
||||
build.(json/yaml/yml)
|
||||
CHANGELOG.md
|
||||
config.json
|
||||
config.(json/yaml/yml)
|
||||
DOCS.md
|
||||
Dockerfile
|
||||
icon.png
|
||||
@ -71,7 +73,7 @@ If you don't use local build on device or our build script, make sure that the D
|
||||
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` 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.(json/yaml/yml)` or if you do not need support for automatic multi-arch building you can also use a simple docker `FROM`.
|
||||
|
||||
### Build Args
|
||||
|
||||
@ -80,12 +82,12 @@ We support the following build arguments by default:
|
||||
| ARG | Description |
|
||||
|-----|-------------|
|
||||
| BUILD_FROM | Hold image for dynamic builds or buildings over our systems.
|
||||
| BUILD_VERSION | Add-on version (read from `config.json`).
|
||||
| BUILD_VERSION | Add-on version (read from `config.(json/yaml/yml)`).
|
||||
| BUILD_ARCH | Hold current build arch inside.
|
||||
|
||||
## Add-on config
|
||||
|
||||
The configuration for an add-on is stored in `config.json`.
|
||||
The configuration for an add-on is stored in `config.(json/yaml/yml)`.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -101,12 +103,28 @@ The configuration for an add-on is stored in `config.json`.
|
||||
"123/tcp": 123
|
||||
},
|
||||
"map": ["config:rw", "ssl"],
|
||||
"options": {},
|
||||
"schema": {},
|
||||
"image": "repo/{arch}-my-custom-addon"
|
||||
}
|
||||
```
|
||||
|
||||
```yaml
|
||||
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
|
||||
```
|
||||
|
||||
| Key | Type | Required | Description |
|
||||
| --- | ---- | -------- | ----------- |
|
||||
| name | string | yes | Name of the add-on.
|
||||
@ -217,7 +235,7 @@ We support:
|
||||
|
||||
## Add-on extended build
|
||||
|
||||
Additional build options for an add-on is stored in `build.json`. This file will be read from our build systems.
|
||||
Additional build options for an add-on is stored in `build.(json/yaml/yml)`. This file will be read from our build systems.
|
||||
You need this only, if you not use the default images or need additional things.
|
||||
|
||||
```json
|
||||
@ -232,6 +250,14 @@ You need this only, if you not use the default images or need additional things.
|
||||
}
|
||||
```
|
||||
|
||||
```yaml
|
||||
build_from:
|
||||
armhf: mycustom/base-image:latest
|
||||
squash: false
|
||||
args:
|
||||
my_build_arg: xy
|
||||
```
|
||||
|
||||
| Key | Required | Description |
|
||||
| --- | -------- | ----------- |
|
||||
| build_from | no | A dictionary with the hardware architecture as the key and the base Docker image as value.
|
||||
@ -241,3 +267,18 @@ You need this only, if you not use the default images or need additional things.
|
||||
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.
|
||||
|
||||
[docker-base]: https://github.com/home-assistant/docker-base
|
||||
|
||||
## Add-on translations
|
||||
|
||||
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)`
|
||||
|
||||
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.
|
||||
|
||||
```yaml
|
||||
configuration:
|
||||
ssl:
|
||||
name: SSL
|
||||
description: Enable usage of SSL on the webserver inside the add-on
|
||||
```
|
||||
|
@ -12,7 +12,7 @@ A user can add a repository by going to the Supervisor panel in Home Assistant,
|
||||
|
||||
## Repository configuration
|
||||
|
||||
Each repository is required to contain `repository.json` at the root in the git repository.
|
||||
Each repository is required to contain `repository.(json/yaml/yml)` at the root in the git repository.
|
||||
|
||||
```json
|
||||
{
|
||||
@ -22,6 +22,12 @@ Each repository is required to contain `repository.json` at the root in the git
|
||||
}
|
||||
```
|
||||
|
||||
```yaml
|
||||
name: Name of repository
|
||||
url: http://www.example/addons
|
||||
maintainer: HomeAssistant Team <info@home-assistant.io>
|
||||
```
|
||||
|
||||
| Key | Required | Description |
|
||||
| --- | -------- | ----------- |
|
||||
| name | yes | Name of the repository
|
||||
|
@ -145,6 +145,7 @@ Get details about a add-on
|
||||
| startup | string | The stage when the add-on is started (initialize, system, services, application, once) |
|
||||
| state | string or null | The state of the add-on (started, stopped) |
|
||||
| stdin | boolean | `true` if the add-on accepts stdin commands |
|
||||
| translations | dictionary | A dictionary containing content of translation files for the add-on |
|
||||
| udev | boolean | `true` if udev access is granted is enabled |
|
||||
| update_available | boolean | `true` if an update is available |
|
||||
| url | string or null | URL to more information about the add-on |
|
||||
@ -217,6 +218,13 @@ Get details about a add-on
|
||||
"startup": "application",
|
||||
"state": "started",
|
||||
"stdin": false,
|
||||
"translations": {
|
||||
"en": {
|
||||
"configuration": {
|
||||
"lorem": "ipsum"
|
||||
}
|
||||
}
|
||||
},
|
||||
"udev": false,
|
||||
"update_available": false,
|
||||
"url": null,
|
||||
|
Loading…
x
Reference in New Issue
Block a user