Add-On Configuration

Each add-on is stored in a folder. The file structure looks like this:

addon_name/
  build.json
  CHANGELOG.md
  config.json
  Dockerfile
  icon.png
  logo.png
  README.md
  run.sh

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. However, you might have to install jq as a separate package in your container (see Dockerfile below).

CONFIG_PATH=/data/options.json

TARGET="$(jq --raw-output '.target' $CONFIG_PATH)"

So if your options contain

{ "target": "beer" }

then there will be a variable TARGET containing beer in the environment of your bash file afterwards.

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 a different timezone. tzdata Is is already added to our base images.

ARG BUILD_FROM
FROM $BUILD_FROM

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" ]

If you don’t use local build on device or our build script, make sure that the Dockerfile have also a set of labels include:

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 build.json or if you do not need support for automatic multi-arch building you can also use a simple docker FROM.

Build Args

We support the following build arguments by default:

Add-on config

The config for an add-on is stored in config.json.

{
  "name": "xy",
  "version": "1.2",
  "slug": "folder",
  "description": "long description",
  "arch": ["amd64"],
  "url": "website with more information about add-on (ie a forum thread for support)",
  "startup": "application",
  "boot": "auto",
  "ports": {
    "123/tcp": 123
  },
  "map": ["config:rw", "ssl"],
  "options": {},
  "schema": {},
  "image": "repo/{arch}-my-custom-addon"
}

Options / Schema

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, and it show it inside default values. Only nested arrays and dictionaries are supported with a deep of two size. If you want make an option optional, put ? to the end of data type, otherwise it will be a required value.

{
  "message": "custom things",
  "logins": [
    { "username": "beer", "password": "123456" },
    { "username": "cheep", "password": "654321" }
  ],
  "random": ["haha", "hihi", "huhu", "hghg"],
  "link": "http://example.com/",
  "size": 15,
  "count": 1.2
}

The schema looks like options but describes how we should validate the user input. For example:

{
  "message": "str",
  "logins": [
    { "username": "str", "password": "str" }
  ],
  "random": ["match(^\w*$)"],
  "link": "url",
  "size": "int(5,20)",
  "count": "float",
  "not_need": "str?"
}

We support:

• str
• bool
• int / int(min,) / int(,max) / int(min,max)
• float / float(min,) / float(,max) / float(min,max)
• email
• url
• port
• match(REGEX)

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.

{
  "build_from": {
    "armhf": "homeassistant/armhf-base:latest"
  },
  "squash": false,
  "args": {
    "my_build_arg": "xy"
  }
}