ioBroker Docker Image Docs

This is the official documentation for the ioBroker Docker image. It covers everything you need to set up and configure a ioBroker Docker container.

If you got questions on how to configure your ioBroker and its adapters please refer to the Official ioBroker Docs.

Getting Started

For discussion and support please visit ioBroker Docker Image Discussions or join the community on ioBroker Forum, Discord or Facebook.

Please do not contact me directly for any support reasons. Every support question should be answered in a public place so all users can benefit from it . Thanks in advance.

If you think you found a bug or simply want to request a new feature please open an issue on Github so we can talk about.

The following ways to set up an ioBroker container are only examples and may vary from platform to platform. Maybe you have to change, add or replace parameters to configure ioBroker to fit your needs.

Running from command-line

For taking a first look at the iobroker docker container it would be enough to simply run the following, very basic docker run command:

docker run -p 8081:8081 --name iobroker -v iobrokerdata:/opt/iobroker buanet/iobroker:latest

Pro Tip

It is always a good choice to avoid using the "latest" tag for production. For more details see "Best practice".

Running with docker-compose

You can also run iobroker by using docker-compose. Here is an example:

version: '2'
services:
  iobroker:
    restart: always
    image: buanet/iobroker:latest
    container_name: iobroker
    hostname: iobroker
    ports:
      - "8081:8081"
    volumes:
      - iobrokerdata:/opt/iobroker

Pro Tip

It is always a good choice to avoid using the "latest" tag for production. For more details see "Best practice".

Persistent data

All configuration data of ioBroker is stored in /opt/iobroker. To make this data persistent it is recommended to mount an (empty) folder or Docker volume to /opt/iobroker during first startup of your container.
Since ioBroker Docker image v8.0.0, it will create a default volume when you do not mount any folder or volume to /opt/iobroker.

Note

If you use a shared storage oder external device mounted to your Docker host to store the iobroker folder make sure the mount point on your host does NOT have the noexec flag activated. Otherwise you will get problems executing ioBroker inside the container! For mor details please take a look at the corresponding Github issues.

Environment variables (ENV)

To configure your ioBroker container as you need, it is possible to set some ENVironment variables. Please only set variables you really need.
Variables you do not set and are marked as "Set by default = yes" in the following table, will be automatically set using their default values when your run a new container.

ENV	Set by default	Default Value	Description
AVAHI	no	false	Activates avahi-daemon for supporting yahka-adapter, can be true or false
DEBUG	no	false	Activates extended log output for your container, can be true or false (!!! Only set if you really need !!!)
IOB_ADMINPORT	no	8081	Sets ioBroker adminport on startup, must be a number
IOB_BACKITUP_EXTDB	no	false	Activates backing up external databases in ioBroker backitup adapter, can be true or false (!!! Make sure your have read this !!!)
IOB_MULTIHOST	no	none	Sets ioBroker instance as master or slave for multihost support
IOB_OBJECTSDB_TYPE	no	jsonl	Sets type of ioBroker objects db, could be jsonl, file (deprecated) or redis
IOB_OBJECTSDB_HOST	no	127.0.0.1	Sets host(s) for ioBroker objects db, can be a comma separated list when using Redis Sentinel
IOB_OBJECTSDB_PORT	no	9001	Sets port(s) for ioBroker objects db, can be a comma separated list when using Redis Sentinel
IOB_OBJECTSDB_PASS	no	none	Sets (optional) password for ioBroker objects db in Redis
IOB_OBJECTSDB_NAME	no	mymaster	Sets name of Redis Sentinel master
IOB_STATESDB_TYPE	no	jsonl	Sets type of ioBroker states db, could be jsonl, file (deprecated) or redis
IOB_STATESDB_HOST	no	127.0.0.1	Sets host(s) for ioBroker states db, can be a comma separated list when using Redis Sentinel
IOB_STATESDB_PORT	no	9000	Sets port(s) for ioBroker states db, can be a comma separated list when using Redis Sentinel
IOB_STATESDB_PASS	no	none	Sets (optional) password for ioBroker states db in Redis
IOB_STATESDB_NAME	no	mymaster	Sets name of Redis Sentinel master
LANG	yes	de_DE.UTF‑8	The following locales are pre-generated: de_DE.UTF-8, en_US.UTF-8
LANGUAGE	yes	de_DE:de	The following locales are pre-generated: de_DE:de, en_US:en
LC_ALL	yes	de_DE.UTF-8	The following locales are pre-generated: de_DE.UTF-8, en_US.UTF-8
OFFLINE_MODE	no	false	Set true if your container has no or limited internet connection (!!! Use at your own risk !!!)
PACKAGES	no	none	Installs additional Linux packages to your container, packages should be separated by whitespace like this: package1 package2 package3
PERMISSION_CHECK	no	true	Checks and corrects all relevant permissions on container startup, can be true or false (!!! Use at your own risk !!!)
SETGID	yes	1000	For some reasons it might be useful to specify the gid of the containers iobroker user to match an existing group on the docker host
SETUID	yes	1000	For some reasons it might be useful to specify the uid of the containers iobroker user to match an existing user on the docker host
TZ	yes	Europe/Berlin	Sets the containers timezone, all valid Linux-timezones are possible
USBDEVICES	no	none	Sets relevant permissions on mounted devices like /dev/ttyACM0, for more than one device separate with ; like this: /dev/ttyACM0;/dev/ttyACM1

Networks

The examples above have no specific networking configuration. In this case Docker is using its default bridge network. In general there are some reasons why it might be a better choice to use a user-defined bridge network.

Running ioBroker with a Docker bridge network works fine with most of the ioBroker adapters (make sure to map all ports your adapters need!), and may be perfect for taking a first look into ioBroker. But some ioBroker adapters are using techniques like Multicast or Broadcast for automatic detection of IoT devices and other features. In this case it may be useful to switch your network to host or MACVLAN.

For more information about networking with Docker please refer to the official Docker docs.

Advanced configuration

Mounting USB devices

If you want to use an USB device within ioBroker inside your container don´t forget to mount the device on container startup AND use the ENV USBDEVICES to give ioBroker access to it.

Note

This is an AND condition. You have to do both. Just setting the ENV USBDEVICES will not work.

Startup scripts

It is possible to add some script code to container startup with the help of the user scripts feature. You can get this to work by mounting an additional folder or volume to /opt/userscripts.

When you mount an empty folder the startup script will restore two example scripts in there. To activate the scripts you have to remove the _example part of the filename. The userscript_firststart.sh will run only at the very first start of a new container, while the userscript_everystart.sh will run on every container start.

Feel free to test it with my example code. Take a look at the log. In Step 4 of 5: Applying special settings you will see the messages generated by the example user scripts.

Multihost

With the help of ENV IOB_MULTIHOST and the ENVs for objects and states db connections it is possible to run a container as standalone (default), multihost master or multihost slave. This is more or less a feature for advanced users. Please make sure you know how ioBroker multihost is working and what iobroker setup custom does.

Further there is no need for executing iobroker multihost enable or iobroker multihost connect inside the container. Just configure the mentioned ENVs. The startup script will do all the magic.

For general information about iobroker multihost feature please see Official ioBroker Docs.

Redis

In ioBroker Docker image v8.0.0 the implementation of using Redis as objects and/ or states db was completely rebuild. In general the configuration is still done by setting the ENVs for db TYPE, HOST and PORT. But there are some more features available now like authentification and the support of Redis Sentinel cluster.

For some basic information about using Redis with ioBroker please see this ioBroker Forum Post by apollon77.

Authentification

With the ENVs IOB_OBJECTSDB_PASSand IOB_STATESDB_PASS it is possible to use a password authentication when connecting to a Redis db. To make this work authentication must be also enabled in redis.conf.

Redis Sentinel Cluster

It is now also possible to use a Redis Sentinel cluster as objects/ states db in ioBroker. This feature will be automatically configured when you set a comma separated list of IOB_OBJECTSDB_HOSTand/or IOB_STATESDB_HOST. If you want to use different ports for your Redis Sentinel nodes, you are also able so use a comma separated list in IOB_OBJECTSDB_PORTand/or IOB_STATESDB_PORT.
The use of ENVs for IOB_OBJECTSDB_NAME and IOB_STATESDB_NAME is optional. If nothing is set, ioBroker will use the Redis default mymaster as name for Redis Sentinel master db.

Maintenance

Backup

The easiest way to backup your ioBroker config is to use the builtin iobroker backup command or the iobroker.backitup adapter.

Another option is to simply tar or copy the whole directory you mounted into your ioBroker container on the Docker host. Make sure ioBroker container is stopped when backing up the directory.

Note

When copying the ioBroker directory, always take care of preserving the correct permissions.

Backup remote databases with iobroker.backitup in Docker

There are some limitations in backing up remote databases (Redis, InfluxDB, PostgresSQL, MySQL) with iobroker.backitup adapter when running inside a Docker container. This small guide will help you to understand why options are grayed out by default and how to change it.

Restore

Restoring your Data can be done by using the builtin iobroker restore command or the iobroker.backitup adapter as described at the Official ioBroker Docs.

Updates & Upgrades

WARNING

Be sure to have a valid backup of your ioBroker installation before applying any updates!

Linux system (package) updates

These updates are usually coming through the systems package manager. In case of the ioBroker Docker container it is apt. So you will be able to install these updates using the command line of your container.

Note that the recommended way is always to simply pull the newest image and recreate your ioBroker Docker container.

ioBroker Adapter updates

You will be notified about available adapter updates in the ioBroker admin interface. You can find an option to install it there too. See Official ioBroker Docs for details.

ioBroker js-controller (core) updates

With a minimum of ioBroker Docker Image v8.1.0, js-controller v5.0.10 und admin v6.9.1 it is now possible to upgrade js-controller from the admin ui directly by simply clicking the update button at the "Hosts" tab.

Of course you still will be able to perform the js-controller upgrade from command line.

Without the help of maintenance script aka "the hacky way"

pkill -u iobroker
iobroker update
iobroker upgrade self

After this you have to restart your container.

With the help of maintenance script aka "the recommended way"

maintenance on
maintenance upgrade
maintenance off

Depending on your containers restart policy the container will stop/ restart automatically.

Upgrades

When bringing your ioBroker to an new major version of the ioBroker Docker Image (e.g. from v7.x.x to v8.x.x) you are going to perform an upgrade. While updates should normally have no impact to the function of your ioBroker, upgrades may include some "breaking changes" and the need of performing some additional steps.
If you are planning to upgrade your Docker container to a new major version, make sure you read the release notes.

WARNING

There is always a small risk of failure when upgrading to a new major version. To minimize this risk make sure your js-controller and adapters are up to date an again make sure you have a valid backup of your ioBroker!

In general the upgrade to a new major version is done like any other Docker image update, by simply recreating your container from the new ioBroker Docker image.

There are some rare cases, when the new major version of the Docker image contains a new major version of node, where the js-controller is not able to recompile some adapters successfully. If this happens, please try to reinstall the affected adapters and take a look at the internal ioBroker log.

In case you want to avoid possible upgrade problems or start with a clean ioBroker directory, it is always a smooth option to use the backup and restore procedure to upgrade to a new major image version. You can do this by following these simple steps:

1. Create a new ioBroker Backup
2. Create a new and empty folder for your ioBroker data
3. Copy the latest backup file from the old ioBroker data folder to the new one
4. Stop and delete your old container
5. Create a new ioBroker Docker container from the latest ioBroker image with the same config, but mount the new ioBroker data folder
6. Take a look at the container logs while the container is starting
7. Restore the backup file from command line or with the help of iobroker.backitup adapter
8. Watch progress of reinstalling your adapters at the iobroker log

Docker Health Check

Since v5.1.0 the image contains a Docker health check. It simply checks if js-controller is running inside the container and reports the container as healthy or unhealthy to the Docker daemon.

The health check itself is configured to 5 retries in an 15s interval with a timeout of 5s. So a container needs a minimum of one minute to get unhealthy after the js-controller was killed.

Pro Tip

As the Docker daemon itself gives no opportunity to automatically restart an unhealthy container you might want to setup some kind of "watchdog container". Check out this one I build some time ago.

Best practice

Avoid using latest tag

The Docker tag latest (buanet/iobroker:latest) will always pull the latest available version of the ioBroker Docker image. This might cause some trouble when it switches to a new major version of the Docker image and performing an upgrade of your ioBroker. To avoid this you always should use a single version tag (e.g. buanet/iobroker:v7.2.0) or the major versions latest tag (e.g. buanet/iobroker:latest-v7) when creating an ioBroker Docker container for production.

Use maintenance script

The ioBroker Docker image includes a small maintenance script which helps you to manage your ioBroker Docker container. For example you can use this script to set your container into maintenance mode (stops ioBroker but keeps container healthy) and apply js-controller updates. Simply type maintenance --help at the containers command line to see what the script can do for you.

With Docker image v9.0.0 there were made some security changes to the maintenance script. It is now no longer possible to call the script as user root. As using root is very common on a containers command line, this was fixed by including the maintenance command into the iobroker command. For example:

iobroker maintenance on
iob maint on
iob m on

This will make sure the command is always executed as user iobroker.

Migrating to Redis

If you want to migrate an existing ioBroker installation to Redis as objects and/ or states db, it is recommended to do the migration first from inside the container before setting the needed ENVs to the container. This could be done by running iobroker setup custom at the containers command line. The wizard will guide you through the process and also asks for the migration of existing objects and/ or states. For more details on how to configure ioBroker to connect to Redis, please refer to the Official ioBroker Docs.

NOTE

For running iob setup custom ioBroker has to be stopped inside the container. It is recommended to use the maintenance script to set the container in maintenance mode and stop iobroker gracefully.

Miscellaneous

Beta testing

If you want to get the newest features and fixes feel free to use/ test the beta version of the Docker image. For more information take a look at the Docker image releases and/ or join our discussion on ioBroker Discord > Beta Testing & Feedback > docker-image.
Thank you.

Notes for developers

Detecting Docker environment

For adapter developers it is now possible to easily detect if ioBroker is running inside the official docker container. Please simply check if the file /opt/.docker_config/.thisisdocker exists. The content of the file will always tell the image version.

---

⚠️ Work In Progress ⚠️

This documentation is still work in progress. If you got any improvements simply let me know by opening an issue or edit it by yourself and create a pull request.

If you got any unanswered questions please join the ioBroker community on Discord, Facebook or ioBroker Forum.