New build system of Hass.io (#3406)
* Update addon_config.markdown * Update addon_tutorial.markdown * add build.json * Update addon_config.markdown * Update addon_config.markdown * Update addon_testing.markdown * Create 2019-09-21-new-hassio-build-system.markdown * Update 2019-09-21-new-hassio-build-system.markdown * Update addon_config.markdown * Update addon_publishing.markdown * Update addon_publishing.markdown * Update and rename 2019-09-21-new-hassio-build-system.markdown to 2019-09-25-new-hassio-build-system.markdown * Update 2019-09-25-new-hassio-build-system.markdown * Update 2019-09-25-new-hassio-build-system.markdown * Update 2019-09-25-new-hassio-build-system.markdown * 📚 Improved spelling & grammar in the documentation * 📚 Replaced blebla.com by example.com * Update blog post
This commit is contained in:
Pascal Vizeli
Paulus Schoutsen
parent
1e55848923
commit
a1a4ff28ee
6 changed files with 142 additions and 51 deletions
|
|
@ -26,26 +26,27 @@ As with every Docker container, you will need a script to run when the container
|
|||
When developing your script:
|
||||
|
||||
- `/data` is a volume for persistent storage.
|
||||
- `/data/options.json` contains the user configuration. You can use `jq` inside your shell script to parse this data. However you might have to install `jq` as a separate package in your container (see `Dockerfile` below).
|
||||
- `/data/options.json` contains the user configuration. You can use `jq` inside your shell script to parse this data. However, you might have to install `jq` as a separate package in your container (see `Dockerfile` below).
|
||||
|
||||
```bash
|
||||
CONFIG_PATH=/data/options.json
|
||||
|
||||
TARGET=$(jq --raw-output ".target" $CONFIG_PATH)
|
||||
TARGET="$(jq --raw-output '.target' $CONFIG_PATH)"
|
||||
```
|
||||
|
||||
So if your `options`contain
|
||||
So if your `options` contain
|
||||
```json
|
||||
{ "target": "beer" }
|
||||
```
|
||||
then there will be a variable `TARGET`containing `beer` in the environment of your bash file afterwards.
|
||||
then there will be a variable `TARGET` containing `beer` in the environment of your bash file afterwards.
|
||||
|
||||
## {% linkable_title Add-on Docker file %}
|
||||
|
||||
All add-ons are based on Alpine Linux 3.6. Hass.io will automatically substitute the right base image based on the machine architecture. Add `tzdata` if you need run in correct timezone, but that is already add in our base images.
|
||||
All add-ons are based on Alpine Linux 3.6. Hass.io 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.
|
||||
|
||||
```
|
||||
FROM %%BASE_IMAGE%%
|
||||
ARG BUILD_FROM
|
||||
FROM $BUILD_FROM
|
||||
|
||||
ENV LANG C.UTF-8
|
||||
|
||||
|
|
@ -64,15 +65,17 @@ 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 follow schema:
|
||||
```
|
||||
#amd64:FROM...
|
||||
#i386:FROM...
|
||||
#armhf:FROM...
|
||||
#aarch64:FROM...
|
||||
```
|
||||
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`.
|
||||
|
||||
Or if you not want to do a multi arch build/support you can also use a simle docker `FROM`.
|
||||
### {% linkable_title Build Args %}
|
||||
|
||||
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_ARCH | Hold current build arch inside.
|
||||
|
||||
## {% linkable_title Add-on config %}
|
||||
|
||||
|
|
@ -106,26 +109,26 @@ The config for an add-on is stored in `config.json`.
|
|||
| description | yes | Description of the add-on
|
||||
| arch | no | List of supported arch: `armhf`, `aarch64`, `amd64`, `i386`. Default all.
|
||||
| url | no | Homepage of the addon. Here you can explain the add-ons and options.
|
||||
| startup | yes | `initialize` will start addon on setup of hassio. `system` is for things like database and base not on other things. `services` will start before homeassistant. `application` is after homeassistant will start or `once` for application they don't run as deamon.
|
||||
| webui | no | A URL for webinterface of this add-on. Like `http://[HOST]:[PORT:2839]/dashboard`, the port need the internal port, we replace it later with the effective port.
|
||||
| startup | yes | `initialize` will start addon on setup of Hass.io. `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 | no | A URL for 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.
|
||||
| boot | yes | `auto` by system and manual or only `manual`
|
||||
| ports | no | Network ports to expose from the container. Format is `"container-port/type": host-port`.
|
||||
| host_network | no | If that is True, the add-on run on host network.
|
||||
| devices | no | Device list to map into add-on. Format is: `<path_on_host>:<path_in_container>:<cgroup_permissions>`. i.e. `/dev/ttyAMA0:/dev/ttyAMA0:rwm`
|
||||
| hassio_api | no | This add-on can access to hass.io REST API. It set the host alias `hassio`.
|
||||
| devices | no | Device list to map into the add-on. Format is: `<path_on_host>:<path_in_container>:<cgroup_permissions>`. i.e. `/dev/ttyAMA0:/dev/ttyAMA0:rwm`
|
||||
| hassio_api | no | This add-on can access to Hass.io REST API. It set the host alias `hassio`.
|
||||
| privileged | no | Privilege for access to hardware/system. Available access: `NET_ADMIN`, `SYS_ADMIN`, `SYS_RAWIO`
|
||||
| map | no | List of maps for additional hass.io folders. Possible values: `config`, `ssl`, `addons`, `backup`, `share`. Default it map it `ro`, you can change that if you add a ":rw" at the end of name.
|
||||
| map | no | List of maps for additional Hass.io folders. Possible values: `config`, `ssl`, `addons`, `backup`, `share`. Defaults to `ro`, which you can change by adding `:rw` to the end of the name.
|
||||
| environment | no | A dict of environment variable to run add-on.
|
||||
| audio | no | Mark this add-on to use internal audio system. Environment is `ALSA_INPUT` and `ALSA_OUTPUT` to access the internal information for alsa.
|
||||
| audio | no | Mark this add-on to use internal an audio system. The available environment variables are `ALSA_INPUT` and `ALSA_OUTPUT` which provide internal information to access alsa.
|
||||
| options | yes | Default options value of the add-on
|
||||
| schema | yes | Schema for options value of the add-on. It can be `False` to disable schema validation and use custom options.
|
||||
| image | no | For use dockerhub.
|
||||
| image | no | For use with Docker Hub.
|
||||
| timeout | no | Default 10 (second). The timeout to wait until the docker is done or will be killed.
|
||||
| tmpfs | no | Mount a tmpfs file system in `/tmpfs`. Valide format for this option is : `size=XXXu,uid=N,rw`. Size is mandatory, valid units (`u`) are `k`, `m` and `g` and `XXX` has to be replaced by a number. `uid=N` (with `N` the uid number) and `rw` are optional.
|
||||
|
||||
### {% linkable_title Options / Schema %}
|
||||
|
||||
The `options` dict 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. Only non-nested arrays and dictorys are supported.
|
||||
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. Only non-nested arrays and dictionaries are supported.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -135,7 +138,9 @@ The `options` dict contains all available options and their default value. Set t
|
|||
{ "username": "cheep", "password": "654321" }
|
||||
],
|
||||
"random": ["haha", "hihi", "huhu", "hghg"],
|
||||
"link": "http://blebla.com/"
|
||||
"link": "http://example.com/",
|
||||
"size": 15,
|
||||
"count": 1.2
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -147,8 +152,10 @@ The `schema` looks like `options` but describes how we should validate the user
|
|||
"logins": [
|
||||
{ "username": "str", "password": "str" }
|
||||
],
|
||||
"random": ["str"],
|
||||
"link": "url"
|
||||
"random": ["match(^\w*$)"],
|
||||
"link": "url",
|
||||
"size": "int(5,20)",
|
||||
"count": "float"
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -161,3 +168,25 @@ We support:
|
|||
- url
|
||||
- port
|
||||
- match(REGEX)
|
||||
|
||||
## {% linkable_title 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.
|
||||
|
||||
```json
|
||||
{
|
||||
"build_from": {
|
||||
"armhf": "homeassistant/armhf-base: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.
|
||||
| squash | no | Default `False`. Be carfully with this option, you can not use the image for caching stuff after that!
|
||||
| args | no | Allow to set additional Docker build arguments as a dictionary.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue