Skip to content

Commit 8fc1553

Browse files
balloobballoob
committed
Revamp hass.io add-on docs
1 parent 834c02a commit 8fc1553

10 files changed

+194
-141
lines changed

‎source/_includes/asides/hassio_navigation.html

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,16 +7,18 @@ <h1 class="title delta">Topics</h1>
77
<ul>
88
<li>{% active_link /hassio/installation/ Installation %}</li>
99
<li>{% active_link /addons/ Available add-ons %}</li>
10+
<li>{% active_link /hassio/architecture/ Architecture %}</li>
1011
</ul>
1112
</li>
1213
</ul>
1314
<ul class='divided sidebar-menu'>
1415
<li>
15-
{% active_link /hassio/development/ Development %}
16+
{% active_link /hassio/addon_development/ Add-on Development %}
1617
<ul>
17-
<li>{% active_link /hassio/architecture/ Architecture %}</li>
18-
<li>{% active_link /hassio/create_hassio_addon/ Creating add-ons %}</li>
19-
<li>{% active_link /hassio/create_hassio_addon_repository/ Creating add-on repositories %}</li>
18+
<li>{% active_link /hassio/addon_config/ Configuration %}</li>
19+
<li>{% active_link /hassio/addon_testing/ Local Testing %}</li>
20+
<li>{% active_link /hassio/addon_publishing/ Publishing %}</li>
21+
<li>{% active_link /hassio/addon_repository/ Repositories %}</li>
2022
</ul>
2123
</li>
2224
</ul>

‎source/addons/index.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
regenerate: true
1111
---
1212

13-
<p>Add-ons are extensions for your Home Assistant installation.</p>
13+
<p>Add-ons for Hass.io allows the user to extend the functionality around Home Assistant. This can be running an application that Home Assistant can integrate with (like an MQTT broker) or to share the configuration via Samba for easy editing from other computers. Add-ons can be configured via the Hass.io panel in Home Assistant.</p>
1414

1515
{% assign addons = site.addons | sort: 'title' %}
1616

‎source/hassio/addon_config.markdown

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
layout: page
3+
title: "Add-On Configuration"
4+
description: "Steps on how-to create an add-on for Hass.io."
5+
date: 2017-04-30 13:28
6+
sidebar: true
7+
comments: false
8+
sharing: true
9+
footer: true
10+
---
11+
12+
Each add-on is stored in a folder. The file structure looks like this:
13+
14+
```
15+
addon_name/
16+
Dockerfile
17+
config.json
18+
run.sh
19+
```
20+
21+
## {% linkable_title Add-on script %}
22+
23+
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.
24+
25+
When developing your script:
26+
27+
- `/data` is a volume for persistent storage.
28+
- `/data/options.json` contains the user configuration. You can use `jq` inside your shell script to parse this data.
29+
30+
```bash
31+
echo '{ "target": "beer" }' | jq -r ".target"
32+
```
33+
34+
## {% linkable_title Add-on Docker file %}
35+
36+
All add-ons are based on Alpine Linux 3.5. Hass.io will automatically substitute the right base image based on the machine architecture. The Dockerfile is also required to have a VERSION environment variable which we will substitute with the version of the add-on.
37+
38+
```
39+
FROM %%BASE_IMAGE%%
40+
41+
ENV VERSION %%VERSION%%
42+
ENV LANG C.UTF-8
43+
44+
# Install requirements for add-on
45+
RUN apk add --no-cache jq
46+
47+
# Copy data for add-on
48+
COPY run.sh /
49+
RUN chmod a+x /run.sh
50+
51+
CMD [ "/run.sh" ]
52+
```
53+
54+
## {% linkable_title Add-on config %}
55+
56+
The config for an add-on is stored in `config.json`.
57+
58+
```json
59+
{
60+
"name": "xy",
61+
"version": "1.2",
62+
"slug": "folder",
63+
"description": "long descripton",
64+
"startup": "before|after|once",
65+
"boot": "auto|manual",
66+
"ports": {
67+
"123/tcp": 123
68+
},
69+
"map": ["config", "ssl", "addons", "backup"],
70+
"options": {},
71+
"schema": {},
72+
"image": "repo/{arch}-my-custom-addon"
73+
}
74+
```
75+
76+
### {% linkable_title Options / Schema %}
77+
78+
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 are supported.
79+
80+
```json
81+
{
82+
"message": "custom things",
83+
"logins": [
84+
{ "username": "beer", "password": "123456" },
85+
{ "username": "cheep", "password": "654321" }
86+
],
87+
"random": ["haha", "hihi", "huhu", "hghg"],
88+
"link": "http://blebla.com/"
89+
}
90+
```
91+
92+
The `schema` looks like `options` but describes how we should validate the user input. For example:
93+
94+
```json
95+
{
96+
"message": "str",
97+
"logins": [
98+
{ "username": "str", "password": "str" }
99+
],
100+
"random": ["str"],
101+
"link": "url"
102+
}
103+
```
104+
105+
We support:
106+
- str
107+
- bool
108+
- int
109+
- float
110+
- email
111+
- url

‎source/hassio/addon_development.markdown

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
layout: page
3+
title: "Developing an add-on"
4+
description: "Steps on how-to create an add-on for Hass.io."
5+
date: 2017-04-30 13:28
6+
sidebar: true
7+
comments: false
8+
sharing: true
9+
footer: true
10+
---
11+
12+
Add-ons for Hass.io allows the user to extend the functionality around Home Assistant. This can be running an application that Home Assistant can integrate with (like an MQTT broker) or to share the configuration via Samba for easy editing from other computers. Add-ons can be configured via the Hass.io panel in Home Assistant.
13+
14+
Under the hood, add-ons are Docker images published in Docker hub. Developers can create GitHub repositories that contain multiple references to add-ons for easy sharing with the community.

‎source/hassio/addon_publishing.markdown

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
layout: page
3+
title: "Publishing your add-on"
4+
description: "Steps on how-to create an add-on for Hass.io."
5+
date: 2017-04-30 13:28
6+
sidebar: true
7+
comments: false
8+
sharing: true
9+
footer: true
10+
---
11+
12+
[placeholder]

‎source/hassio/addon_repository.markdown

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
layout: page
3+
title: "Create an add-on repository"
4+
description: "Add-ons repositories."
5+
date: 2017-04-30 13:28
6+
sidebar: true
7+
comments: false
8+
sharing: true
9+
footer: true
10+
---
11+
12+
Add-ons repository can contain one or more add-ons. Each add-on is stored in it's own unique folder. For it to be indentified as a repository, a repository contains a configuration file.
13+
14+
[Example add-on repository](https://github.com/home-assistant/hassio-addons-example).
15+
16+
## Installing a repository
17+
18+
A user can add a repository by going to the Hass.io panel in Home Assistant, clicking on the store icon in the top right, copy/paste the url of your repostory into the repository textarea and click on "Save".
19+
20+
## Repository configuration
21+
22+
Each repository is required to contain `repository.json` at the root of the Git repository.
23+
24+
```json
25+
{
26+
"name": "Name of repository",
27+
"url": "http://www.example/addons",
28+
"maintainer": "HomeAssistant Team <info@home-assistant.io>"
29+
}
30+
```
31+
32+
| Key | Description |
33+
| --- | ----------- |
34+
| name | Name of the repository
35+
| url | Homepage of the repository. Here you can explain the various add-ons.
36+
| maintainer | Contact info of the maintainer.

‎source/hassio/addon_testing.markdown

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
layout: page
3+
title: "Local add-on testing"
4+
description: "Instructions how to test your add-on locally."
5+
date: 2017-04-30 13:28
6+
sidebar: true
7+
comments: false
8+
sharing: true
9+
footer: true
10+
---
11+
12+
## {% linkable_title Logs %}
13+
14+
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.

‎source/hassio/create_hassio_addon.markdown

Lines changed: 0 additions & 94 deletions
This file was deleted.

‎source/hassio/create_hassio_addon_repository.markdown

Lines changed: 0 additions & 24 deletions
This file was deleted.

‎source/hassio/development.markdown

Lines changed: 0 additions & 18 deletions
This file was deleted.

0 commit comments

Comments
 (0)