openHAB Docker Containers
Table of Contents
- openHAB Docker Containers
- Image Variants
- Environment variables
- Building the image
Repository for building Docker containers for openHAB (Home Automation Server). Comments, suggestions and contributions are welcome!
1.8.3Stable openHAB 1.8 version
2.0.0Stable openHAB 2.0 version
2.1.0Stable openHAB 2.1 version
2.2.0Stable openHAB 2.2 version
2.3.0Stable openHAB 2.3 version
2.4.0-snapshotExperimental openHAB 2.4 SNAPSHOT version
amd64for most desktop computer (e.g. x64, x86-64, x86_64)
armhffor ARMv7 devices 32 Bit (e.g. most RaspberryPi 1/2/3)
arm64for ARMv8 devices 64 Bit (not RaspberryPi 3)
debianfor debian stretch
alpinefor alpine 3.7
The alpine images are substantially smaller than the debian images but may be less compatible because OpenJDK is used (see Prerequisites for known disadvantages).
If you are unsure about what your needs are, you probably want to use
Prebuilt Docker Images can be found here: Docker Images
Important: To be able to use UPnP for discovery the container needs to be started with
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 -it --name openhab --net=host openhab/openhab:2.3.0-amd64-debian
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.
Starting with Docker named volumes (for beginners)
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:
Running from command line
docker run \ --name openhab \ --net=host \ --tty \ -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 \ -d \ --restart=always \ openhab/openhab:2.3.0-amd64-debian
Running from compose-file.yml
Create the following
docker-compose.yml and start the container with
docker-compose up -d
version: '2.2' services: openhab: image: "openhab/openhab:2.3.0-amd64-debian" restart: always network_mode: host tty: true volumes: - "/etc/localtime:/etc/localtime:ro" - "/etc/timezone:/etc/timezone:ro" - "openhab_addons:/openhab/addons" - "openhab_conf:/openhab/conf" - "openhab_userdata:/openhab/userdata" environment: OPENHAB_HTTP_PORT: "8080" OPENHAB_HTTPS_PORT: "8443"
Running openHAB with libpcap support
You can run all openHAB images with libpcap support. This enables you to use the Amazon Dashbutton Binding in the Docker container. For that feature to work correctly, you need to run the image as root user. 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:2.3.0-amd64-debian" restart: always tty: true network_mode: host cap_add: - NET_ADMIN - NET_RAW volumes: - "/etc/localtime:/etc/localtime:ro" - "/etc/timezone:/etc/timezone:ro" - "openhab_conf:/openhab/conf" - "openhab_userdata:/openhab/userdata" - "openhab_addons:/openhab/addons" # The command node is very important. It overrides # the "gosu openhab ./start.sh" command from Dockerfile and runs as root! command: "./start.sh"
If you could provide a method to run libpcap support in user mode please open a pull request.
Starting with Docker mounting a host directory (for advanced user)
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 \ --tty \ -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 \ openhab/openhab:2.3.0-amd64-debian
Accessing the console
You can connect to a console of an already running openHAB container with following command:
docker ps- lists all your currently running container
docker exec -it openhab /openhab/runtime/bin/client- connect to openHAB container by name
docker exec -it c4ad98f24423 /openhab/runtime/bin/client- connect to openHAB container by id
docker attach openhab- attach to openHAB container by name, input only works when starting the container with
stdin_open: truewith docker compose)
The default password for the login is
You can run a new container with the command
docker run -it openhab/openhab:2.3.0-amd64-debian ./start_debug.sh to get into the debug shell.
User and group identifiers
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
You create the same user with the same uid and gid on your docker host system
groupadd -g 9001 openhab useradd -u 9001 -g openhab -r -s /sbin/nologin openhab usermod -a -G openhab myownuser
Or run the docker container with your own user AND passing the userid to openHAB through env
docker run \ (...) --user <myownuserid> \ -e USER_ID=<myownuserid>
Java cryptographic strength policy
Due to local laws and export restrictions the containers use Java with a limited cryptographic strength policy. Some openHAB functionality (e.g. KM200 binding) may depend on unlimited strength which can be enabled by configuring the environment variable
Before enabling this make sure this is allowed by local laws and you agree with the applicable license and terms:
-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 container
Upgrading OH 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
userdata.dist/etc/version.properties in the Docker image. The steps performed are:
- Create a
userdata/backupfolder if one does not exist.
- Create a full backup of userdata as a dated tar file saved to
userdata/backupfolder is excluded from this backup.
- Copy over the relevant files from
- Delete the contents of
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.
Building the image
Checkout the github repository and then run these commands:
$ docker build -t openhab/openhab . $ docker run -it openhab/openhab server