You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This is the source for the [Home-Assistant.io website](https://home-assistant.io).
9
9
@@ -16,5 +16,19 @@ Setting up to contribute to documentation and the process for submitting pull re
16
16
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:
17
17
18
18
```bash
19
-
$ rake preview
19
+
bundle exec rake preview
20
+
```
21
+
22
+
## Speeding up site generation
23
+
24
+
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.
25
+
26
+
```bash
27
+
bundle exec rake isolate[filename-of-blogpost]
28
+
```
29
+
30
+
When you're done working on the site, run the following command to move the posts back again:
description: "We're introducing a new and improved Hass.io build system for Hass.io and add-ons."
5
+
date: 2017-09-26 04:00:00 +0100
6
+
date_formatted: "September 26, 2017"
7
+
author: Pascal Vizeli
8
+
comments: true
9
+
categories: Technology
10
+
---
11
+
12
+
<pclass='note'>
13
+
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).
14
+
</p>
15
+
16
+
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!
17
+
18
+
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.
19
+
20
+
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.
21
+
22
+
<pclass='note'>
23
+
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.
24
+
</p>
25
+
26
+
### {% linkable_title Template changes %}
27
+
28
+
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.
29
+
30
+
Old:
31
+
32
+
```
33
+
FROM %%BASE_IMAGE%%
34
+
```
35
+
36
+
New:
37
+
38
+
```
39
+
ARG BUILD_FROM
40
+
FROM $BUILD_FROM
41
+
```
42
+
43
+
### {% linkable_title When %}
44
+
45
+
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.
46
+
47
+
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].
Copy file name to clipboardExpand all lines: source/developers/hassio/addon_config.markdown
+54-25Lines changed: 54 additions & 25 deletions
Original file line number
Diff line number
Diff line change
@@ -26,26 +26,27 @@ As with every Docker container, you will need a script to run when the container
26
26
When developing your script:
27
27
28
28
-`/data` is a volume for persistent storage.
29
-
-`/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).
29
+
-`/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).
30
30
31
31
```bash
32
32
CONFIG_PATH=/data/options.json
33
33
34
-
TARGET=$(jq --raw-output ".target"$CONFIG_PATH)
34
+
TARGET="$(jq --raw-output '.target'$CONFIG_PATH)"
35
35
```
36
36
37
-
So if your `options`contain
37
+
So if your `options`contain
38
38
```json
39
39
{ "target": "beer" }
40
40
```
41
-
then there will be a variable `TARGET`containing `beer` in the environment of your bash file afterwards.
41
+
then there will be a variable `TARGET`containing `beer` in the environment of your bash file afterwards.
42
42
43
43
## {% linkable_title Add-on Docker file %}
44
44
45
-
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.
45
+
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.
46
46
47
47
```
48
-
FROM %%BASE_IMAGE%%
48
+
ARG BUILD_FROM
49
+
FROM $BUILD_FROM
49
50
50
51
ENV LANG C.UTF-8
51
52
@@ -64,15 +65,17 @@ If you don't use local build on device or our build script, make sure that the D
It is possible to use own base image with follow schema:
68
-
```
69
-
#amd64:FROM...
70
-
#i386:FROM...
71
-
#armhf:FROM...
72
-
#aarch64:FROM...
73
-
```
68
+
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`.
69
+
70
+
### {% linkable_title Build Args %}
71
+
72
+
We support the following build arguments by default:
74
73
75
-
Or if you not want to do a multi arch build/support you can also use a simle docker `FROM`.
74
+
| ARG | Description |
75
+
|-----|-------------|
76
+
| BUILD_FROM | Hold image for dynamic builds or buildings over our systems.
77
+
| BUILD_VERSION | Add-on version (read from `config.json`).
78
+
| BUILD_ARCH | Hold current build arch inside.
76
79
77
80
## {% linkable_title Add-on config %}
78
81
@@ -106,26 +109,26 @@ The config for an add-on is stored in `config.json`.
106
109
| description | yes | Description of the add-on
107
110
| arch | no | List of supported arch: `armhf`, `aarch64`, `amd64`, `i386`. Default all.
108
111
| url | no | Homepage of the addon. Here you can explain the add-ons and options.
109
-
| 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.
110
-
| 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.
112
+
| 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.
113
+
| 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.
111
114
| boot | yes | `auto` by system and manual or only `manual`
112
115
| ports | no | Network ports to expose from the container. Format is `"container-port/type": host-port`.
113
116
| host_network | no | If that is True, the add-on run on host network.
114
-
| 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`
115
-
| hassio_api | no | This add-on can access to hass.io REST API. It set the host alias `hassio`.
117
+
| 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`
118
+
| hassio_api | no | This add-on can access to Hass.io REST API. It set the host alias `hassio`.
116
119
| privileged | no | Privilege for access to hardware/system. Available access: `NET_ADMIN`, `SYS_ADMIN`, `SYS_RAWIO`
117
-
| 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.
120
+
| 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.
118
121
| environment | no | A dict of environment variable to run add-on.
119
-
| 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.
122
+
| 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.
120
123
| options | yes | Default options value of the add-on
121
124
| schema | yes | Schema for options value of the add-on. It can be `False` to disable schema validation and use custom options.
122
-
| image | no | For use dockerhub.
125
+
| image | no | For use with Docker Hub.
123
126
| timeout | no | Default 10 (second). The timeout to wait until the docker is done or will be killed.
124
127
| 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.
125
128
126
129
### {% linkable_title Options / Schema %}
127
130
128
-
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.
131
+
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.
129
132
130
133
```json
131
134
{
@@ -135,7 +138,9 @@ The `options` dict contains all available options and their default value. Set t
135
138
{ "username": "cheep", "password": "654321" }
136
139
],
137
140
"random": ["haha", "hihi", "huhu", "hghg"],
138
-
"link": "http://blebla.com/"
141
+
"link": "http://example.com/",
142
+
"size": 15,
143
+
"count": 1.2
139
144
}
140
145
```
141
146
@@ -147,8 +152,10 @@ The `schema` looks like `options` but describes how we should validate the user
147
152
"logins": [
148
153
{ "username": "str", "password": "str" }
149
154
],
150
-
"random": ["str"],
151
-
"link": "url"
155
+
"random": ["match(^\w*$)"],
156
+
"link": "url",
157
+
"size": "int(5,20)",
158
+
"count": "float"
152
159
}
153
160
```
154
161
@@ -161,3 +168,25 @@ We support:
161
168
- url
162
169
- port
163
170
- match(REGEX)
171
+
172
+
## {% linkable_title Add-on extended build %}
173
+
174
+
Additional build options for an add-on is stored in `build.json`. This file will be read from our build systems.
175
+
176
+
```json
177
+
{
178
+
"build_from": {
179
+
"armhf": "homeassistant/armhf-base:latest"
180
+
},
181
+
"squash": false,
182
+
"args": {
183
+
"my_build_arg": "xy"
184
+
}
185
+
}
186
+
```
187
+
188
+
| Key | Required | Description |
189
+
| --- | -------- | ----------- |
190
+
| build_from | no | A dictionary with the hardware architecture as the key and the base Docker image as value.
191
+
| squash | no | Default `False`. Be carfully with this option, you can not use the image for caching stuff after that!
192
+
| args | no | Allow to set additional Docker build arguments as a dictionary.
Copy file name to clipboardExpand all lines: source/developers/hassio/addon_publishing.markdown
+6-17Lines changed: 6 additions & 17 deletions
Original file line number
Diff line number
Diff line change
@@ -38,35 +38,24 @@ All add-ons are simple docker containers. Inside your add-on `config.json` you s
38
38
}
39
39
```
40
40
41
-
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.
41
+
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.
42
42
43
-
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.
43
+
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.
44
44
45
45
## {% linkable_title Custom Add-ons %}
46
46
47
-
You need a Docker Hub account to make your own add-ons. Download our [build script][builder] and run one of the following commands.
47
+
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.
48
48
49
49
For a git repository:
50
50
51
51
```bash
52
-
# Test only:
53
-
./create_hassio_addon.sh -a amd64 -s addon-slug -r https://github.com/xy/addons -b branchname
54
-
55
-
# push to docker hub:
56
-
./create_hassio_addon.sh -a amd64 -s addon-slug -r https://github.com/xy/addons -b branchname -p
description: "Instructions how to test your add-on locally."
4
+
description: "Instructions on how to test your add-on locally."
5
5
date: 2017-04-30 13:28
6
6
sidebar: true
7
7
comments: false
@@ -14,23 +14,24 @@ The fastest way to develop add-ons is by adding them to your local add-on reposi
14
14
15
15
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.
16
16
17
-
## {% linkable_title Local run %}
17
+
## {% linkable_title Local build %}
18
18
19
-
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:
19
+
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:
20
20
21
21
- armhf: `homeassistant/armhf-base:latest`
22
22
- aarch64: `homeassistant/aarch64-base:latest`
23
23
- amd64: `homeassistant/amd64-base:latest`
24
24
- i386: `homeassistant/i386-base:latest`
25
25
26
-
Add also a `LABEL io.hass.version="xy"` into your dockerfile.
27
-
Use `docker` to build the test addon: `docker build -t local/my-test-addon .`
26
+
Use `docker` to build the test addon: `docker build --build-arg BUILD_FROM="homeassistant/amd64-base:latest" -t local/my-test-addon .`
27
+
28
+
## {% linkable_title Local run %}
28
29
29
30
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`
30
31
31
32
## {% linkable_title Logs %}
32
33
33
-
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.
34
+
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.
0 commit comments