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:
- Create a new ioBroker Backup
- Create a new and empty folder for your ioBroker data
- Copy the latest backup file from the old ioBroker data folder to the new one
- Stop and delete your old container
- Create a new ioBroker Docker container from the latest ioBroker image with the same config, but mount the new ioBroker data folder
- Take a look at the container logs while the container is starting
- Restore the backup file from command line or with the help of iobroker.backitup adapter
- 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.