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 Docker Image Discussionsopen in new window or join the community on ioBroker Forumopen in new window, Discordopen 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 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-composeopen in new window. Here is an example:

version: '2'
    restart: always
    image: buanet/iobroker:latest
    container_name: iobroker
    hostname: iobroker
      - "8081:8081"
      - 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.


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
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
OFFLINE_MODEnofalseSet true if your container has no or limited internet connection (!!! Use at your own risk !!!)
PACKAGESnononeInstalls additional Linux packages to your container, packages should be separated 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


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.


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 will run only at the very first start of a new container, while the 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.


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


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


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.



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.


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.


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


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


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


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


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.


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/.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, Facebookopen in new window or ioBroker Forumopen in new window.

Last Updated: