mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-14 12:56:54 +00:00
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
@ -16,5 +16,19 @@ Setting up to contribute to documentation and the process for submitting pull re
|
||||
In order to make the preview available on [http://127.0.0.1:4000](http://127.0.0.1:4000), use the command as follows:
|
||||
|
||||
```bash
|
||||
$ rake preview
|
||||
bundle exec rake preview
|
||||
```
|
||||
|
||||
## Speeding up site generation
|
||||
|
||||
Every release we post long changelogs to the website. This slows down generation of the website significantly! We include some tools to temporarily exclude the blog posts that you're not working on out of the way.
|
||||
|
||||
```bash
|
||||
bundle exec rake isolate[filename-of-blogpost]
|
||||
```
|
||||
|
||||
When you're done working on the site, run the following command to move the posts back again:
|
||||
|
||||
```bash
|
||||
bundle exec rake integrate
|
||||
```
|
||||
|
||||
57
source/_posts/2019-09-25-new-hassio-build-system.markdown
Normal file
57
source/_posts/2019-09-25-new-hassio-build-system.markdown
Normal file
@ -0,0 +1,57 @@
|
||||
---
|
||||
layout: post
|
||||
title: "Improved Hass.io build system"
|
||||
description: "We're introducing a new and improved Hass.io build system for Hass.io and add-ons."
|
||||
date: 2017-09-26 04:00:00 +0100
|
||||
date_formatted: "September 26, 2017"
|
||||
author: Pascal Vizeli
|
||||
comments: true
|
||||
categories: Technology
|
||||
---
|
||||
|
||||
<p class='note'>
|
||||
This is going to be a technical post for Hass.io add-on developers and people that run locally build add-ons (not the default).
|
||||
</p>
|
||||
|
||||
Two months ago we [introduced Hass.io][intro], allowing our users to easily install, update and manage their Home Assistant installation. In this short time we've seen great adoption from the community. Around 20% of our users are choosing Hass.io as their method of running Home Assistant today. We've also seen many add-ons being made available on [the forums][addon-repos]. There are currently 14 reposities full of add-ons being shared!
|
||||
|
||||
Hass.io is built on top of Docker, a container runtime. One thing that Docker did not support was dynamic build environements. That was annoying for Hass.io because by supporting multiple CPU architectures, that was exactly what we needed! Luckily this feature has been added in Docker 17.05. By moving to Docker 17.05 as the minimum supported version we will be able to replace our templated Dockerfile approach with standard Dockerfiles that work out of the box. Thanks to [Frenck][frenck] for notifying us of this new build feature.
|
||||
|
||||
This change only impacts people that build add-ons or use add-ons that are built locally. You can check if your add-on is building locally on the detail page of add-ons.
|
||||
|
||||
<p class='note'>
|
||||
If you are an add-on developer, read [the documentation][publishing-addons] on how to publish your add-ons to Docker Hub. This will greatly improve the user experience.
|
||||
</p>
|
||||
|
||||
### {% linkable_title Template changes %}
|
||||
|
||||
As an add-on developer, you will only have to change one line in your template to make it compatible with the new system. If you wish, you can also change the default build options for your image using the new [`build.json`][build-file] file.
|
||||
|
||||
Old:
|
||||
|
||||
```
|
||||
FROM %%BASE_IMAGE%%
|
||||
```
|
||||
|
||||
New:
|
||||
|
||||
```
|
||||
ARG BUILD_FROM
|
||||
FROM $BUILD_FROM
|
||||
```
|
||||
|
||||
### {% linkable_title When %}
|
||||
|
||||
The new system will become active with Hass.io 0.64 and Host OS 1.1. Host OS 1.1 is available today. Navigate to Advanced Settings in the Hass.io panel to start the OTA update.
|
||||
|
||||
We have also updated our build scripts and replaced it with a [builder docker engine][builder]. This builder makes deploying Hass.io components very easy. All basic functionality is supported. If you want more functionality, check out [the builder by the Community Hass.io Add-ons project][community-builder].
|
||||
|
||||
[hassio-hardware-image-release]: https://github.com/home-assistant/hassio-build/releases/tag/1.1
|
||||
[install]: /hassio/installation/
|
||||
[builder]: https://github.com/home-assistant/hassio-build/tree/master/builder
|
||||
[frenck]: https://github.com/frenck
|
||||
[build-file]: /developers/hassio/addon_config/#add-on-extended-build
|
||||
[addon-repos]: https://community.home-assistant.io/tags/hassio-repository
|
||||
[community-builder]: https://github.com/hassio-addons/build-env
|
||||
[intro]: /blog/2017/07/25/introducing-hassio/
|
||||
[publishing-addons]: /developers/hassio/addon_publishing/#custom-add-ons
|
||||
@ -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.
|
||||
|
||||
@ -38,35 +38,24 @@ All add-ons are simple docker containers. Inside your add-on `config.json` you s
|
||||
}
|
||||
```
|
||||
|
||||
You can use `{arch}` inside the image name to support multiple architectures with 1 configuration file. It will be replaced with the architecture of the user when we load the image.
|
||||
You can use `{arch}` inside the image name to support multiple architectures with 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.
|
||||
|
||||
Hass.io assumes that the `master` 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`. After you push the add-on to [Docker Hub](https://hub.docker.com/), you can merge this branch to master.
|
||||
Hass.io assumes that the `master` 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.
|
||||
|
||||
## {% linkable_title Custom Add-ons %}
|
||||
|
||||
You need a Docker Hub account to make your own add-ons. Download our [build script][builder] and run one of the following commands.
|
||||
You need a Docker Hub account to make your own add-ons. You can build your docker images with docker `build` command or use our script that make it simple. Pull our [builder docker engine][builder] and run one of the following commands.
|
||||
|
||||
For a git repository:
|
||||
|
||||
```bash
|
||||
# Test only:
|
||||
./create_hassio_addon.sh -a amd64 -s addon-slug -r https://github.com/xy/addons -b branchname
|
||||
|
||||
# push to docker hub:
|
||||
./create_hassio_addon.sh -a amd64 -s addon-slug -r https://github.com/xy/addons -b branchname -p
|
||||
|
||||
# create for all supported arch:
|
||||
./create_addon_all.sh -s addon-slug -r https://github.com/xy/addons -b branchname -p
|
||||
docker run --rm --privileged -v ~/.docker:/root/docker homeassistant/amd64-builder --all -t addon-folder -r https://github.com/xy/addons -b branchname
|
||||
```
|
||||
|
||||
For a local repository:
|
||||
|
||||
```bash
|
||||
# Test only:
|
||||
./create_hassio_addon.sh -a amd64 -s addon-slug -l /home/xy/my_local_repo
|
||||
|
||||
# push to docker hub:
|
||||
./create_hassio_addon.sh -a amd64 -s addon-slug -l /home/xy/my_local_repo -p
|
||||
docker run --rm --privileged -v ~/.docker:/root/docker -v /my_addon:/data homeassistant/amd64-builder --all -t /data
|
||||
```
|
||||
|
||||
[builder]: https://github.com/home-assistant/hassio-build/tree/master/build-scripts/addons
|
||||
[builder]: https://github.com/home-assistant/hassio-build/tree/master/builder
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Local add-on testing"
|
||||
description: "Instructions how to test your add-on locally."
|
||||
description: "Instructions on how to test your add-on locally."
|
||||
date: 2017-04-30 13:28
|
||||
sidebar: true
|
||||
comments: false
|
||||
@ -14,23 +14,24 @@ The fastest way to develop add-ons is by adding them to your local add-on reposi
|
||||
|
||||
Right now add-ons will work with images that are stored on Docker Hub (using `image` from add-on config). Without `image` inside local add-ons repository it to be built on the device.
|
||||
|
||||
## {% linkable_title Local run %}
|
||||
## {% linkable_title Local build %}
|
||||
|
||||
You can build an try the addon on your developer machine also. Move all addon stuff into a temp folder. Replace in the Dockerfile `%%BASE_IMAGE%%` with:
|
||||
You can build an try the addon on your developer machine also. Move all addon stuff into a temp folder. If you use `FROM $BUILD_FROM` you need set a base image with build args. Normally you can use follow base images:
|
||||
|
||||
- armhf: `homeassistant/armhf-base:latest`
|
||||
- aarch64: `homeassistant/aarch64-base:latest`
|
||||
- amd64: `homeassistant/amd64-base:latest`
|
||||
- i386: `homeassistant/i386-base:latest`
|
||||
|
||||
Add also a `LABEL io.hass.version="xy"` into your dockerfile.
|
||||
Use `docker` to build the test addon: `docker build -t local/my-test-addon .`
|
||||
Use `docker` to build the test addon: `docker build --build-arg BUILD_FROM="homeassistant/amd64-base:latest" -t local/my-test-addon .`
|
||||
|
||||
## {% linkable_title Local run %}
|
||||
|
||||
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 local/my-test-addon`
|
||||
|
||||
## {% linkable_title Logs %}
|
||||
|
||||
All stdout and stderr is redirected to the Docker logs. The logs can be fetched from the add-on page inside the Hass.io panel in Home Assistant.
|
||||
All stdout and stderr are redirected to the Docker logs. The logs can be fetched from the add-on page inside the Hass.io panel in Home Assistant.
|
||||
|
||||
[Samba add-on]: /addons/samba/
|
||||
[SSH add-on]: /addons/ssh/
|
||||
|
||||
@ -41,7 +41,8 @@ Once you have located your add-on directory, it's time to get started!
|
||||
|
||||
`Dockerfile`:
|
||||
```
|
||||
FROM %%BASE_IMAGE%%
|
||||
ARG BUILD_FROM
|
||||
FROM $BUILD_FROM
|
||||
|
||||
ENV LANG C.UTF-8
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user