Repository for building Docker containers for openHAB (Home Automation Server). Comments, suggestions and contributions are welcome!
The openHAB Docker images are available in the openhab/openhab repository on Docker Hub.
For specific versions use:
openhab/openhab:<version>
openhab/openhab:<version>-<distribution>
For the latest stable release use:
openhab/openhab
openhab/openhab:latest
openhab/openhab:latest-<distribution>
For the latest release that has a milestone or stable maturity use:
openhab/openhab:milestone
openhab/openhab:milestone-<distribution>
For the latest snapshot release use:
openhab/openhab:snapshot
openhab/openhab:snapshot-<distribution>
Versions:
4.2.1
(Release notes)4.1.3
(Release notes)4.3.0-snapshot
Distributions:
debian
for Debian 11 "bullseye" (default when not specified in tag) (Dockerfile)alpine
for Alpine 3.20 (Dockerfile)The Alpine images are substantially smaller than the Debian images but may be less compatible because OpenJDK is used (see Prerequisites for known disadvantages). Older container images may use older versions of the Debian and Alpine base images.
If you are unsure about what your needs are, you probably want to use openhab/openhab:4.2.1
.
Platforms:
The following Docker platforms are supported (automatically determined):
linux/amd64
linux/arm64
linux/arm/v7
There is no linux/arm/v7
Alpine image for openHAB 3 (or newer) because the required openjdk package is unavailable for this platform.
Important: To be able to use UPnP for discovery the container needs to be started with --net=host
.
Important: In the container openHAB runs with user "openhab" (id 9001) by default. See user configuration section below!
The following will run openHAB in demo mode on the host machine:
docker run --name openhab --net=host openhab/openhab:4.2.1
NOTE: Although this is the simplest method to getting openHAB up and running, but it is not the preferred method. To properly run the container, please specify a host volume for the directories.
The following configuration uses Docker named data volumes.
These volumes will survive, if you delete or upgrade your container.
It is a good starting point for beginners.
The volumes are created in the Docker volume directory.
You can use docker inspect openhab
to locate the directories (e.g. /var/lib/docker/volumes) on your host system.
For more information visit Manage data in containers.
docker run \
--name openhab \
--net=host \
-v /etc/localtime:/etc/localtime:ro \
-v /etc/timezone:/etc/timezone:ro \
-v openhab_addons:/openhab/addons \
-v openhab_conf:/openhab/conf \
-v openhab_userdata:/openhab/userdata \
-e "CRYPTO_POLICY=unlimited" \
-e "EXTRA_JAVA_OPTS=-Duser.timezone=Europe/Berlin" \
-d \
--restart=always \
openhab/openhab:4.2.1
Create the following docker-compose.yml
for use of local directories and start the container with docker compose up -d
version: '2.2'
services:
openhab:
image: "openhab/openhab:4.2.1"
restart: always
network_mode: host
volumes:
- "/etc/localtime:/etc/localtime:ro"
- "/etc/timezone:/etc/timezone:ro"
- "./openhab_addons:/openhab/addons"
- "./openhab_conf:/openhab/conf"
- "./openhab_userdata:/openhab/userdata"
environment:
CRYPTO_POLICY: "unlimited"
EXTRA_JAVA_OPTS: "-Duser.timezone=Europe/Berlin"
OPENHAB_HTTP_PORT: "8080"
OPENHAB_HTTPS_PORT: "8443"
Create the following docker-compose.yml
for use of Docker volumes and start the container with docker compose up -d
version: '2.2'
services:
openhab:
image: "openhab/openhab:4.2.1"
restart: always
network_mode: host
volumes:
- "/etc/localtime:/etc/localtime:ro"
- "/etc/timezone:/etc/timezone:ro"
- "openhab_addons:/openhab/addons"
- "openhab_conf:/openhab/conf"
- "openhab_userdata:/openhab/userdata"
environment:
CRYPTO_POLICY: "unlimited"
EXTRA_JAVA_OPTS: "-Duser.timezone=Europe/Berlin"
OPENHAB_HTTP_PORT: "8080"
OPENHAB_HTTPS_PORT: "8443"
volumes:
openhab_addons:
driver: local
openhab_conf:
driver: local
openhab_userdata:
driver: local
You can run all openHAB images with libpcap support by configuring additional capabilities.
This allows for using the Amazon Dash Button Binding in the Docker container.
Create the following docker-compose.yml
and start the container with docker compose up -d
version: '2.2'
services:
openhab:
container_name: openhab
image: "openhab/openhab:4.2.1"
restart: always
network_mode: host
cap_add:
- NET_ADMIN
- NET_RAW
volumes:
- "/etc/localtime:/etc/localtime:ro"
- "/etc/timezone:/etc/timezone:ro"
- "./openhab_addons:/openhab/addons"
- "./openhab_conf:/openhab/conf"
- "./openhab_userdata:/openhab/userdata"
The host
networking driver only works on Linux hosts, and is not supported by Docker on Windows and macOS.
On Windows and macOS ports should be exposed by adding port options to commands (-p 8080
) or by adding a ports section to docker-compose.yml
.
version: '2.2'
services:
openhab:
image: "openhab/openhab:4.2.1"
restart: always
ports:
- "8080:8080"
- "8443:8443"
volumes:
- "./openhab_addons:/openhab/addons"
- "./openhab_conf:/openhab/conf"
- "./openhab_userdata:/openhab/userdata"
environment:
CRYPTO_POLICY: "unlimited"
EXTRA_JAVA_OPTS: "-Duser.timezone=Europe/Berlin"
OPENHAB_HTTP_PORT: "8080"
OPENHAB_HTTPS_PORT: "8443"
You can mount a local host directory to store your configuration files.
If you followed the beginners guide, you do not need to read this section.
The following run
command will create the folders and copy the initial configuration files for you.
docker run \
--name openhab \
--net=host \
-v /etc/localtime:/etc/localtime:ro \
-v /etc/timezone:/etc/timezone:ro \
-v /opt/openhab/addons:/openhab/addons \
-v /opt/openhab/conf:/openhab/conf \
-v /opt/openhab/userdata:/openhab/userdata \
-e "CRYPTO_POLICY=unlimited" \
-e "EXTRA_JAVA_OPTS=-Duser.timezone=Europe/Berlin" \
openhab/openhab:4.2.1
Here is an example playbook in case you control your environment with Ansible.
You can test it by running ansible-playbook -i mycontainerhost, -t openhab run-containers.yml
.
The :Z
at the end of volume lines is for SELinux systems.
If run elsewhere, replace it with ro.
- name: ensure containers are running
hosts: all
tasks:
- name: ensure openhab is up
tags: openhab
docker_container:
name: openhab
image: openhab/openhab:4.2.1
state: started
detach: yes
ports:
- 8080:8080
- 8101:8101
- 5007:5007
volumes:
- "/etc/localtime:/etc/localtime:ro"
- "/etc/timezone:/etc/timezone:ro"
- "/opt/openhab/addons:/openhab/addons:Z"
- "/opt/openhab/conf:/openhab/conf:Z"
- "/opt/openhab/userdata:/openhab/userdata:Z"
keep_volumes: yes
hostname: openhab.localnet
memory: 512m
pull: true
restart_policy: unless-stopped
env:
CRYPTO_POLICY="unlimited"
EXTRA_JAVA_OPTS="-Duser.timezone=Europe/Berlin"
You can connect to a console of an already running openHAB container with the following command:
docker exec -it openhab /openhab/runtime/bin/client
The default password for the login is: habopen
The container starts openHAB in server mode when no TTY is provided, example:
docker run --detach --name openhab openhab/openhab:4.2.1
When the container runs in server mode you can also add a console logger so it prints logging to stdout so you can check the logging of a container named "openhab" with:
docker logs openhab
To use a console logger with openHAB 3 (or newer), edit userdata/etc/log4j2.xml
and add the following appender to the "Root logger" and "openhab.event" logger configurations: <AppenderRef ref="STDOUT"/>
To use a console logger with openHAB 2, edit userdata/etc/org.ops4j.pax.logging.cfg
and then:
log4j2.rootLogger.appenderRefs = out, osgi, console
log4j2.rootLogger.appenderRef.console.ref = STDOUT
When a TTY is provided openHAB is started with an interactive console, e.g.:
docker run -it openhab/openhab:4.2.1
The debug mode is started with the command:
docker run -it openhab/openhab:4.2.1 ./start_debug.sh
CRYPTO_POLICY
=limitedEXTRA_JAVA_OPTS
=""EXTRA_SHELL_OPTS
=""LC_ALL
=en_US.UTF-8LANG
=en_US.UTF-8LANGUAGE
=en_US.UTF-8OPENHAB_HTTP_PORT
=8080OPENHAB_HTTPS_PORT
=8443USER_ID
=9001GROUP_ID
=9001The group ID will default to the same value as the user ID. By default the openHAB user in the container is running with:
uid=9001(openhab) gid=9001(openhab) groups=9001(openhab)
Make sure that either
groupadd -g 9001 openhab
useradd -u 9001 -g openhab -r -s /sbin/nologin openhab
usermod -a -G openhab myownuser
docker run \
(...)
-e USER_ID=<myownuserid> \
-e GROUP_ID=<myowngroupid> \
(...)
You can obtain your user and group ID by executing the id --user
and id --group
commands.
Due to local laws and export restrictions the containers use Java with a limited cryptographic strength policy.
Some openHAB functionality may depend on unlimited strength which can be enabled by configuring the environment variable CRYPTO_POLICY
=unlimited
Before enabling this make sure this is allowed by local laws and you agree with the applicable license and terms (see OpenJDK (Cryptographic Cautions)).
The following functionality depends on the unlimited cryptographic strength policy:
-it
- starts openHAB with an interactive console (since openHAB 2.0.0)-p 8080
- the HTTP port of the web interface-p 8443
- the HTTPS port of the web interface-p 8101
- the SSH port of the Console (since openHAB 2.0.0)-p 5007
- the LSP port for validating rules (since openHAB 2.2.0)-v /openhab/addons
- custom openHAB addons-v /openhab/conf
- openHAB configs-v /openhab/userdata
- openHAB userdata directory--device=/dev/ttyUSB0
- attach your devices like RFXCOM or Z-Wave Sticks to the containerOn Linux, if you pass a device with a symlink or any non standard name (e.g. /dev/ttyZWave), some addons require the device name to follow the Linux serial port naming rules (e.g. "ttyACM0", "ttyUSB0" or "ttyUSB-9999") or will otherwise fail to discover the device.
This can be achieved by mapping the devices to a compliant name like this:
docker run \
(...)
--device=/dev/ttyZWave:/dev/ttyACM0
--device=/dev/ttyZigbee:/dev/ttyACM1
(...)
More information about serial ports and symlinks can be found here.
It is sometimes useful to run shell scripts after the "userdata" directory is created, but before Karaf itself is launched. One such case is creating SSH host keys, and allowing access to the system from the outside via SSH. Exemplary scripts can be found in the contrib/cont-init.d directory
To use this, create a directory called
/etc/cont-init.d
and add a volume mount to your startup:
...
-v /etc/cont-init.d:/etc/cont-init.d \
...
and put your scripts into that directory. This can be done by either using a volume mount (see the examples above) or creating your own images which inherit from the official ones.
Upgrading openHAB requires changes to the user mapped in userdata folder.
The container will perform these steps automatically when it detects that the userdata/etc/version.properties
is different from the version in dist/userdata/etc/version.properties
in the Docker image.
The steps performed are:
userdata/backup
folder if one does not exist.userdata/backup
. The userdata/backup
folder is excluded from this backup.dist/userdata/etc
to userdata/etc
.addons
.userdata/cache
and userdata/tmp
.The steps performed are the same as those performed by running the upgrade script that comes with OH, except the backup is performed differently and the latest openHAB runtime is not downloaded.
All messages shown during the update are also logged to userdata/logs/update.log
.
This error message indicates that the data in the volumes is not properly initialized.
The error is usually the result of a permissions issue or already putting files into volumes without the volumes having been initialized by the container first.
When mounting directories into the container, check that these directories exist, are completely empty and are owned by the same USER_ID
and GROUP_ID
as configured in the container ENV variables.
Docker containers are kept as small as possible intentionally to decrease download times and the number of potential vulnerabilities for everyone. If you want additional packages installed, create your own container based on this container. Another option is to install the package by executing a shell script before openHAB is started.
By default this will always be the last logged message. A console logger can be configured for more detailed logging.
This error message may occur when running a recent openHAB container image on a Docker host with an outdated version of libseccomp2. The issue can be fixed by upgrading libseccomp2 on your Docker host to a more recent version. For more details see this community thread.
The default filesystem mount flags of OpenMediaVault contain the noexec
flag which interferes with the serial library used by openHAB.
To be able to use serial devices with openHAB, make sure the userdata
volume mounted by the container is not backed by a filesystem having the noexec
flag.
See the OMV documentation on how to remove the noexec
flag from an existing filesystem.
The default values of ENV variables are always stored by Portainer (see portainer/portainer#2952). This causes issues such as endless restart loops when upgrading the container with Portainer. To resolve this issue when upgrading openHAB, first remove all default (non-overridden) ENV variables before starting the new container.
When using the container on a Linux distribution with SELinux enabled (CentOS/Fedora/RHEL), add the :z
or :Z
option to volumes to give the container write permissions.
For more information on this see the Docker documentation.
Checkout the GitHub repository, change to a directory containing a Dockerfile (e.g. /debian
) and then run these commands to build and run a Docker image for your current platform:
$ docker build --build-arg JAVA_VERSION=17 --build-arg OPENHAB_VERSION=4.2.1 --tag openhab/openhab .
$ docker run openhab/openhab
To be able to build the same image for other platforms (e.g. arm/v7, arm64 on amd64) Docker CE with BuildKit support can be used.
First configure QEMU binary formats and a builder using:
$ docker run --privileged --rm tonistiigi/binfmt:qemu-v8.0.4 --install all
$ docker buildx create --name builder --use
Change to a directory containing a Dockerfile (e.g. /debian
) and then use the following command to build an ARMv7 image:
$ docker buildx build --build-arg JAVA_VERSION=17 --build-arg OPENHAB_VERSION=4.2.1 --platform linux/arm/v7 --tag openhab/openhab --load .
The build
script in the root of the repository helps to simplify building the openHAB images with BuildKit.
It can be used to build the images of multiple openHAB versions and correctly tag and push them to a Docker registry.
Execute ./build -h
for usage instructions and examples.