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 Docsopen in new window.

Getting Started

For discussion and support please visit ioBroker forum threadopen in new window or join the ioBroker Community on Discordopen in new window, Telegramopen in new window or Facebookopen in new window.

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 issueopen in new window 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 for fitting 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 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 Docker 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 issuesopen in new window.

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.

ENVSet by
default
Default
Value
Description
AVAHInofalseActivates avahi-daemon for supporting yahka-adapter, can be true or false
DEBUGnofalseActivates extended log output for your container, can be true or false
(!!! Only set if you really need !!!)
IOB_ADMINPORTno8081Sets ioBroker adminport on startup, must be a number
IOB_BACKITUP_EXTDBnofalseActivates backing up external databases in ioBroker backitup adapter, can be true or false (!!! Make sure your have read this !!!)
IOB_MULTIHOSTnononeSets ioBroker instance as master or slave for multihost support
IOB_OBJECTSDB_TYPEnojsonlSets type of ioBroker objects db, could be jsonl, file (deprecated) or redis
IOB_OBJECTSDB_HOSTno127.0.0.1Sets host(s) for ioBroker objects db, can be a comma separated list when using Redis Sentinel
IOB_OBJECTSDB_PORTno9001Sets port(s) for ioBroker objects db, can be a comma separated list when using Redis Sentinel
IOB_OBJECTSDB_PASSnononeSets (optional) password for ioBroker objects db in Redis
IOB_OBJECTSDB_NAMEnomymasterSets name of Redis Sentinel master
IOB_STATESDB_TYPEnojsonlSets type of ioBroker states db, could be jsonl, file (deprecated) or redis
IOB_STATESDB_HOSTno127.0.0.1Sets host(s) for ioBroker states db, can be a comma separated list when using Redis Sentinel
IOB_STATESDB_PORTno9000Sets port(s) for ioBroker states db, can be a comma separated list when using Redis Sentinel
IOB_STATESDB_PASSnononeSets (optional) password for ioBroker states db in Redis
IOB_STATESDB_NAMEnomymasterSets name of Redis Sentinel master
LANGyesde_DE.UTF‑8The following locales are pre-generated: de_DE.UTF-8, en_US.UTF-8
LANGUAGEyesde_DE:deThe following locales are pre-generated: de_DE:de, en_US:en
LC_ALLyesde_DE.UTF-8The following locales are pre-generated: de_DE.UTF-8, en_US.UTF-8
PACKAGESnononeInstalls additional linux packages to your container, packages should be seperated by whitespace like this: package1 package2 package3
PERMISSION_CHECKnotrueChecks and corrects all relevant permissions on container startup, can be true or false (!!! Use at your own risk !!!)
SETGIDyes1000For some reasons it might be useful to specify the gid of the containers iobroker user to match an existing group on the docker host
SETUIDyes1000For some reasons it might be useful to specify the uid of the containers iobroker user to match an existing user on the docker host
TZyesEurope/BerlinSets the containers timezone, all valid Linux-timezones are possible
USBDEVICESnononeSets relevant permissions on mounted devices like /dev/ttyACM0, for more than one device separate with ; like this: /dev/ttyACM0;/dev/ttyACM1
ZWAVEnofalseInstalls openzwave to support zwave-adapter, can be true or false

Networks

The examples above have no specific networking configuration. In this case Docker is using its default bridge network. In general there are some reasonsopen in new window 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 Multicastopen in new window or Broadcastopen in new window for automatic detection of IoT devices and other features. In this case it may be useful to switch your network to hostopen in new window or MACVLANopen in new window.

For more information about networking with Docker please refer to the official Docker docsopen in new window.

Advanced configuration

Mounting USB devices

If you want to use an USB device within ioBroker inside your container don´t forget to mount the deviceopen in new window 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 userscripts 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 execute only at the very first start of a new container, while the userscript_everystart.sh will execute 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 userscripts.

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 ìobroker 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 Docsopen in new window.

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.

For some basic information about using Redis with ioBroker please see this ioBroker Forum Post by apollon77open in new window.

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 commandopen in new window or the iobroker.backitup adapteropen in new window.

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 commandopen in new window or the iobroker.backitup adapteropen in new window as described at the Official ioBroker Docsopen in new window.

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.

But the easiest way is always pulling the newest image and/ or simply recreate your 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 Docsopen in new window for details.

ioBroker js-controller (core) updates

You will be notified about js-controller updates in the ioBroker admin interface. As ioBroker has to be stopped to apply these updates it is not able to install it from the admin interface. You have to do it manually on the containers command line.

pkill -u iobroker
iobroker update
iobroker upgrade self

After this you have to restart your container.

Pro Tip

To easily apply js-controller updates you can also use the built in maintenance script. This is recommended if you have some kind of watchdog monitoring your containers health status. For more details on how to use the script see Best practice.

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 might include some "breaking changes" and the need of performing some additional steps.
So if you are planning to upgrade your Docker Container to a new major version make sure you checked the release notesopen in new window of the latest release first.

WARNING

Make sure to have a valid backup of your ioBroker installation and your js-controller is up to date before performing an upgrade!

In general it is possible to upgrade to a new major version of the ioBroker Docker image by simply recreating your container from the new ioBroker Docker image as you do it in the normal update process. In most cases the js-controller will detect the new node version and tries to fix adapters which having problems with the change. But in some rare cases the "recompiling" will fail and you got some additional steps to do like rebuilding or simply reinstalling the adapter. In case you have a valid backup, you should simply give it a try.

In case the above don't work, or you simply want to void the described problems it is always a smooth option to use the backup and restore procedure whenever switching an existing ioBroker Docker installation to a new major version of the ioBroker Docker image.

So your upgrade might be done like this, for example:

  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 Healthcheck

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

The healthcheck 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 oneopen in new window 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 ioBrocker 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.

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 Docsopen in new window.

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 releasesopen in new window and/ or join our discussion on ioBroker Discord > Beta Testing & Feedback > docker-imageopen in new window.
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/scripts/.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 issueopen in new window or edit itopen in new window by yourself and create a pull request.

If you got any unanswered questions please join the ioBroker community on Discordopen in new window, Telegramopen in new window, Facebookopen in new window or ioBroker Forumopen in new window.

Last Updated: