mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-15 21:36:52 +00:00
Revamp hass.io add-on docs
This commit is contained in:
Paulus Schoutsen
parent
834c02a232
commit
8fc1553eb7
@ -7,16 +7,18 @@
|
||||
<ul>
|
||||
<li>{% active_link /hassio/installation/ Installation %}</li>
|
||||
<li>{% active_link /addons/ Available add-ons %}</li>
|
||||
<li>{% active_link /hassio/architecture/ Architecture %}</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<ul class='divided sidebar-menu'>
|
||||
<li>
|
||||
{% active_link /hassio/development/ Development %}
|
||||
{% active_link /hassio/addon_development/ Add-on Development %}
|
||||
<ul>
|
||||
<li>{% active_link /hassio/architecture/ Architecture %}</li>
|
||||
<li>{% active_link /hassio/create_hassio_addon/ Creating add-ons %}</li>
|
||||
<li>{% active_link /hassio/create_hassio_addon_repository/ Creating add-on repositories %}</li>
|
||||
<li>{% active_link /hassio/addon_config/ Configuration %}</li>
|
||||
<li>{% active_link /hassio/addon_testing/ Local Testing %}</li>
|
||||
<li>{% active_link /hassio/addon_publishing/ Publishing %}</li>
|
||||
<li>{% active_link /hassio/addon_repository/ Repositories %}</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
@ -10,7 +10,7 @@ footer: true
|
||||
regenerate: true
|
||||
---
|
||||
|
||||
<p>Add-ons are extensions for your Home Assistant installation.</p>
|
||||
<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>
|
||||
|
||||
{% assign addons = site.addons | sort: 'title' %}
|
||||
|
||||
|
||||
111
source/hassio/addon_config.markdown
Normal file
111
source/hassio/addon_config.markdown
Normal file
@ -0,0 +1,111 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Add-On Configuration"
|
||||
description: "Steps on how-to create an add-on for Hass.io."
|
||||
date: 2017-04-30 13:28
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
Each add-on is stored in a folder. The file structure looks like this:
|
||||
|
||||
```
|
||||
addon_name/
|
||||
Dockerfile
|
||||
config.json
|
||||
run.sh
|
||||
```
|
||||
|
||||
## {% linkable_title Add-on script %}
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
```bash
|
||||
echo '{ "target": "beer" }' | jq -r ".target"
|
||||
```
|
||||
|
||||
## {% linkable_title Add-on Docker file %}
|
||||
|
||||
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.
|
||||
|
||||
```
|
||||
FROM %%BASE_IMAGE%%
|
||||
|
||||
ENV VERSION %%VERSION%%
|
||||
ENV LANG C.UTF-8
|
||||
|
||||
# Install requirements for add-on
|
||||
RUN apk add --no-cache jq
|
||||
|
||||
# Copy data for add-on
|
||||
COPY run.sh /
|
||||
RUN chmod a+x /run.sh
|
||||
|
||||
CMD [ "/run.sh" ]
|
||||
```
|
||||
|
||||
## {% linkable_title Add-on config %}
|
||||
|
||||
The config for an add-on is stored in `config.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "xy",
|
||||
"version": "1.2",
|
||||
"slug": "folder",
|
||||
"description": "long descripton",
|
||||
"startup": "before|after|once",
|
||||
"boot": "auto|manual",
|
||||
"ports": {
|
||||
"123/tcp": 123
|
||||
},
|
||||
"map": ["config", "ssl", "addons", "backup"],
|
||||
"options": {},
|
||||
"schema": {},
|
||||
"image": "repo/{arch}-my-custom-addon"
|
||||
}
|
||||
```
|
||||
|
||||
### {% 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 are supported.
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "custom things",
|
||||
"logins": [
|
||||
{ "username": "beer", "password": "123456" },
|
||||
{ "username": "cheep", "password": "654321" }
|
||||
],
|
||||
"random": ["haha", "hihi", "huhu", "hghg"],
|
||||
"link": "http://blebla.com/"
|
||||
}
|
||||
```
|
||||
|
||||
The `schema` looks like `options` but describes how we should validate the user input. For example:
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "str",
|
||||
"logins": [
|
||||
{ "username": "str", "password": "str" }
|
||||
],
|
||||
"random": ["str"],
|
||||
"link": "url"
|
||||
}
|
||||
```
|
||||
|
||||
We support:
|
||||
- str
|
||||
- bool
|
||||
- int
|
||||
- float
|
||||
- email
|
||||
- url
|
||||
14
source/hassio/addon_development.markdown
Normal file
14
source/hassio/addon_development.markdown
Normal file
@ -0,0 +1,14 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Developing an add-on"
|
||||
description: "Steps on how-to create an add-on for Hass.io."
|
||||
date: 2017-04-30 13:28
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
12
source/hassio/addon_publishing.markdown
Normal file
12
source/hassio/addon_publishing.markdown
Normal file
@ -0,0 +1,12 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Publishing your add-on"
|
||||
description: "Steps on how-to create an add-on for Hass.io."
|
||||
date: 2017-04-30 13:28
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
[placeholder]
|
||||
36
source/hassio/addon_repository.markdown
Normal file
36
source/hassio/addon_repository.markdown
Normal file
@ -0,0 +1,36 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Create an add-on repository"
|
||||
description: "Add-ons repositories."
|
||||
date: 2017-04-30 13:28
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
[Example add-on repository](https://github.com/home-assistant/hassio-addons-example).
|
||||
|
||||
## Installing a repository
|
||||
|
||||
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".
|
||||
|
||||
## Repository configuration
|
||||
|
||||
Each repository is required to contain `repository.json` at the root of the Git repository.
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Name of repository",
|
||||
"url": "http://www.example/addons",
|
||||
"maintainer": "HomeAssistant Team <info@home-assistant.io>"
|
||||
}
|
||||
```
|
||||
|
||||
| Key | Description |
|
||||
| --- | ----------- |
|
||||
| name | Name of the repository
|
||||
| url | Homepage of the repository. Here you can explain the various add-ons.
|
||||
| maintainer | Contact info of the maintainer.
|
||||
14
source/hassio/addon_testing.markdown
Normal file
14
source/hassio/addon_testing.markdown
Normal file
@ -0,0 +1,14 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Local add-on testing"
|
||||
description: "Instructions how to test your add-on locally."
|
||||
date: 2017-04-30 13:28
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
## {% 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.
|
||||
@ -1,94 +0,0 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Create an add-on for Hass.io"
|
||||
description: "Steps on how-to create an add-on for Hass.io."
|
||||
date: 2017-04-30 13:28
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
Add-ons are docker container they run a script and do some things. User are able to set a add-on specific options.
|
||||
|
||||
### {% linkable_title Add-on folder %}
|
||||
|
||||
```
|
||||
addon_name:
|
||||
Dockerfile
|
||||
config.json
|
||||
run.sh
|
||||
```
|
||||
|
||||
All add-ons are based on Alpine Linux 3.5. You can use `FROM %%BASE_IMAGE%%` inside your docker file to build the right arch or for automatic build with our scripts.
|
||||
|
||||
Your Docker need also a env variable `VERSION` with the version of the add-on. With our build system include this line:
|
||||
```
|
||||
ENV VERSION %%VERSION%%
|
||||
```
|
||||
|
||||
As a user might run many add-ons, it is encouraged to try to stick to Bash scripts if you're doing simple things.
|
||||
|
||||
### {% linkable_title Add-on config %}
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "xy",
|
||||
"version": "1.2",
|
||||
"slug": "folder",
|
||||
"description": "long descripton",
|
||||
"startup": "before|after|once",
|
||||
"boot": "auto|manual",
|
||||
"ports": {
|
||||
"123/tcp": 123
|
||||
},
|
||||
"map": ["config", "ssl", "addons", "backup"],
|
||||
"options": {},
|
||||
"schema": {},
|
||||
"image": "repo/{arch}-my-custom-addon"
|
||||
}
|
||||
```
|
||||
|
||||
### {% linkable_title Options / Schema %}
|
||||
|
||||
The `options` dict have all available options with default value. If you want to set a value to requered and need to be set from user before it start the addon, set it to null. We support arrays for single deeps.
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "custom things",
|
||||
"logins": [
|
||||
{ "username": "beer", "password": "123456" },
|
||||
{ "username": "cheep", "password": "654321" }
|
||||
],
|
||||
"random": ["haha", "hihi", "huhu", "hghg"],
|
||||
"link": "http://blebla.com/"
|
||||
}
|
||||
```
|
||||
|
||||
The `schmema` look like the `options` but describe how we should validate the user input. For example above:
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "str",
|
||||
"logins": [
|
||||
{ "username": "str", "password": "str" }
|
||||
],
|
||||
"random": ["str"],
|
||||
"link": "url"
|
||||
}
|
||||
```
|
||||
|
||||
We support:
|
||||
- str
|
||||
- bool
|
||||
- int
|
||||
- float
|
||||
- email
|
||||
- url
|
||||
|
||||
### {% linkable_title SSL %}
|
||||
|
||||
Default you can use `fullchain.pem` and `privkey.pem` from `/ssl` for you stuff. Your SSL addon should also create default this files.
|
||||
|
||||
### {% linkable_title Need to know %}
|
||||
`/data` is a volume with a persistant store. `/data/options.json` have the user config inside. You can use `jq` inside shell script to parse this data.
|
||||
@ -1,24 +0,0 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Create an add-on repository for Hass.io"
|
||||
description: "Add-ons repositories."
|
||||
date: 2017-04-30 13:28
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
Look to our example [repository](https://github.com/home-assistant/hassio-addons-example).
|
||||
|
||||
Add-ons repository can have multible add-ons with diferents folders or it can be a single add-on. It is importent that you add the json file to root.
|
||||
|
||||
Add a `repository.json` to the root of your git repository with:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Needed, Name of repository",
|
||||
"url": "http://www.example/addons",
|
||||
"maintainer": "HomeAssistant Team <info@home-assistant.io>"
|
||||
}
|
||||
```
|
||||
@ -1,18 +0,0 @@
|
||||
---
|
||||
layout: page
|
||||
title: "Hass.io development"
|
||||
description: "How to get started with Hass.io development."
|
||||
date: 2017-04-30 13:28
|
||||
sidebar: true
|
||||
comments: false
|
||||
sharing: true
|
||||
footer: true
|
||||
---
|
||||
|
||||
Seen all the Hass.io stuff and want to built on top of it? That's awesome.
|
||||
|
||||
Before you get started with development, get familiar with [the architecture][arch].
|
||||
|
||||
[Placeholder]
|
||||
|
||||
[arch]: /hassio/architecture/
|
||||
Loading…
x
Reference in New Issue
Block a user