In the previous post in the series I described the process of externalizing you HA (Home Assistant) using my custom addon. Make sure to check that out if you haven’t already. This time I’ll share the details of the add-on development process.
When building the add-on my first steps obviously went towards the existing online resources. The first thing I’ve found was the extensive tutorial on https://developers.home-assistant.io/docs/add-ons/tutorial, but there seems to be an easier hands-on approach. Instead of following the tutorial we’ll use the official template from https://github.com/home-assistant/addons-example.
Anatomy of an addon
Each addon in HA is basically a docker container that can have an access to some of the HA resources. Installing an addon means running a docker container. This means that to build an addon we need to create a repository, build a Dockerfile and publish the built file.
From the HA point of view, to add a custom addon you need to add a repository. This directly relates to a git repository like this one https://github.com/majk-p/home-assistant-addons
The structure of the repository is simple, you put a
repository.yaml like this one:
name: Home Assistant add-on repository by majk-p url: 'https://github.com/majk-p/home-assistant-addons' maintainer: Michał Pawlik <firstname.lastname@example.org>
And then each addon you create gets it’s own sub-directory in the repository. The complete directory structure looks like this:
├── LICENSE ├── README.md ├── repository.yaml └── reverse-ssh-tunnel ├── build.yaml ├── CHANGELOG.md ├── config.yaml ├── Dockerfile ├── DOCS.md ├── icon.png ├── README.md ├── run.sh └── translations └── en.yaml
The simplest addon we can make consists of:
- A bunch of markdown files like
Dockerfiledescribing how to build the addon
run.shfor the main logic
config.yamldescribing the addon metadata, required permissions and configuration schema. The detailed guide on how to configure the plugin can be found in https://developers.home-assistant.io/docs/add-ons/configuration
build.yamlmainly for a list of base images to build from
translations/en.yaml(and similar for other languages) for configuration parameters description
Docker images for addons are based on
ghcr.io/home-assistant base image. To be able to build against different architectures, a typical addon Dockerfile would start with
ARG BUILD_FROM FROM $BUILD_FROM
When designing a docker image you usually assume there is just one process running in the container. It’s not always true for the addons, so the base image comes with the process supervisor S6 using s6-overlay. If you just want your main script, make sure to go with
init: false in the config file. Then make sure to run your script as the
The complete dockerfile might look like this:
ARG BUILD_FROM FROM $BUILD_FROM USER root RUN \ set -x \ && apk add --no-cache \ openssh \ autossh # add whatever dependencies you need COPY run.sh / RUN chmod a+x /run.sh CMD ["/run.sh"]
Now that the dockerfile is ready, let’s discuss the contents of the main script. In this place you might want to interact with the Home assistant to write logs, read config etc. The base image comes with built in utility called bashio. This is your interface for HA. To make sure it works in your script start it with the following shebang:
This is how your
run.sh might look like when interacting with the api.
#!/usr/bin/with-contenv bashio bashio::log.info "Reverse tunnel initializing." username=$(bashio::config 'username') host=$(bashio::config 'server.host') bashio::log.info "Reverse tunnel configured for $username@$host"
Please refer to https://github.com/hassio-addons/bashio/ for more detailed usage instructions.
If your plugin config has
advanced: true, you need to enable advanced mode in your user profile.
To enable the plugin navigate to
Settings -> Add-ons. Then on the bottom right select
add-on store. Now on the top right launch three dot menu press
repositories and paste in your git repository link. Make sure the link points to the repository root.
If everything is set up properly, your repository should now be visible and you’ll be able to configure your addon. In case something goes wrong, make sure to have a look into
Settings -> System -> Logs and select
Supervisor on the top right, the error message is usually helpful enough to sort out the problem.