Tutorial: Move Linuxserver.io Image to addon

[TheBinaryLoop]

Hey there,

i was thinking about cnverting some images from linuxserver to home assistant addons myself, but i don't know how. Maybe it would be a good idea if you write up a tutorial so that more people can port images and contribute them to this repo.

[alexbelgium]

Good idea, I'll write a bit when I'll have time, thanks.

[alexbelgium]

Here is something I wrote in the past, I'll write a guide when I'll have more time :

Actually once you've understood the principle it's quite easy. The easiest is to start from a good quality standalone dockerhub image that supports all architectures. Linuxserver.io is a good provider of such images. Then you create the docker image to reference it and symlink its data file in a place not overwritten at reboot (so /data within the addon, or an external folder) , and you create the config.json to let it show in HA. In theory, these two files alone can create an addon... I suggest that you take a look at my simplest addon, such as https://github.com/alexbelgium/hassio-addons/tree/master/grav. The official documentation is also a great help : https://developers.home-assistant.io/docs/add-ons/tutorial/

Good luck!

[alexbelgium]

This tutorial is based on a linuxserver image, but the basic principle are transposable to other high quality images from Dockerhub.
It supposes you have read all the official documentation here.

For this example, we'll use this container : https://hub.docker.com/r/linuxserver/piwigo.
The addon built upon it is here : https://github.com/alexbelgium/hassio-addons/tree/master/piwigo

1. Build the base addon structure

Create a repository on github based on HA provided example

2. Identify a suitable already published image

• Look on dockerhub for a well maintained image containing preferably s6 supervision that supports multiple architectures (at least aarch64 and amd64)
• Linuxserver.io images are usually recognized as the best quality.

3. Adapt for HA usage

3.1. Define the fixed parameters for your addon

By looking at the docker-compose provided by the addon, you can see the most important information to run the addon.

You can get several information from the docker-compose :

• the base image you'll need to build your addon (you'll need to set that in the build.json file ; example)
• the environment variables needed (All environment options need to be defined in a fixed manner either in the Dockerfile (through ENV command ; example) or in the config.json environment key ; example.)
• the volumes where dynamic data is stored -> see point after for remanent data
• the port (will need to go in config.json) ; example

3.1. Define the variables parameters for your addon

HA does not support passing environment variables dynamically. All environment options need to be defined in a fixed manner either in the Dockerfile (through ENV command) or in the config.json environment key.

This can be done in two ways. For example, linuxserver images have a dynamic env variable for setting PUID and GUID.

• Using sed to modify the scripts in the Dockerfile
  Example :

RUN \
    # Allow UID and GID setting
    sed -i 's/bash/bashio/g' /etc/cont-init.d/10-adduser \
    && sed -i 's/{PUID:-911}/(bashio::config "PUID")/g' /etc/cont-init.d/10-adduser \
    && sed -i 's/{PGID:-911}/(bashio::config "PGID")/g' /etc/cont-init.d/10-adduser

• Pushing the variables directly through the export variable (usually done through a script).

export ALLOWED_HOSTS=$(bashio::config 'ALLOWED_HOSTS') && bashio::log.blue "ALLOWED_HOSTS=$ALLOWED_HOSTS"
export SECRET_KEY=$(bashio::config 'SECRET_KEY') && bashio::log.blue "SECRET_KEY=$SECRET_KEY"

This code must be added in the same bash session as where the app is run. For example, either you have a run.sh file where you export variables, then you execute the app, or more probably you have a separate script (in /etc/cont-init.d probably) and services (in /etc/services.d). What you can do is therefore put the export in those files, for example with :

sed -i "1a export ALLOWED_HOSTS=$(bashio::config 'ALLOWED_HOSTS')" /etc/services.d/*/run

3.3. Create your Dockerfile

Follow the official guide. Ensure to add instructions to modify files for dynamic environment setting, and add apps if needed.
In particular, the Bashio library needs to be installed as it facilitates many HA functions.

Add label.

3.4. Ensure data remanence

Create folders on your local system, and use symlink so that the app will use these folders instead of its default ones. Script example

3.5. Add any other scripts

S6 based images get any scripts in /etc/cont-initi.d and /etc/services.d and execute them (if they have execute access).
You can therefore add your scripts there through your Dockerfile.

4. Add codenotary signature

Optional, see here for documentation : https://developers.home-assistant.io/docs/add-ons/security?_highlight=codenotary#codenotary-cas

5. Add auto build images

Optional, see here for documentation : https://github.com/home-assistant/builder

[alexbelgium]

Actually I knew nothing 2 years ago, I just started by copying and adapting someone's Addon, and spent lots of time in trials and errors...

[ch4d1]

Thank you for the instructions. I tried the whole thing for linuxserver/filezilla and linuxserver/syncthing. However, I'm having some problems saving "/config" outside the container. I also don't get along with Ingress yet... Do you have any tips? :D

[alexbelgium]

Do like me, spend HOURS doing trial and errors ;-) Or just copy my stuff (recommended) :-)

For the /config thing, you need two things :

• Allow the addon to access the folder outside the container by mapping it in config.json : example here
  

  hassio-addons/calibre/config.json

  Line 58 in 0096566

  "config:rw",

• Modify the existing container links to use your own custom folder : example here
  

  hassio-addons/calibre/Dockerfile

  Lines 45 to 46 in 0096566

  	# Correct config location
  	&& for file in $(grep -Esril "/config[ '\"/]|/config\$" /etc /defaults); do sed -Ei "s=(/config)+(/| |$|\"|\')=$CONFIGLOCATION\2=g" $file; done \

For ingress it's super complex and depends on each app

Btw for syncthing Poeschl (great dev) has an addon here : https://github.com/Poeschl/Hassio-Addons

[bilogic]

@alexbelgium

I'm trying to make my own add-on.

When I create the config.json in the add-on's folder, add-on does not show in HA. However, it was ok when I used config.yaml. I prefer to use JSON, what am I missing here?

[bilogic]

nevermind, found it right after I left a message. I was missing arch because I couldn't find an example for it. Thanks.