Running openHAB 2 in Docker

I don’t really deal with docker compose (I probably should). But I can’t imagine docker create doing anything you can’t do in compose.

I’ve seen some hacky things to DHCP that I didn’t like that involved a busybox container for each app container, but other than that, I havent come across a way yet. I

I’m in the same boat as you though. OH+Plex+Unifi is a tough docker combination.

@christoph_wempe - no that’s the main goal as obbers pointed out. You gain the ability to treat the docker container as if it was it’s own host/ip address. The beauty here, is you can use normal firewalling capabilities to protect/open/expose different apps. It also eases things like UPnP (auto discovery) in apps. The main benefit I like of this vs using Host is twofold: 1 - you get separation from the actual host networking so someone can’t by default gain access to the host through this exposure, 2 - you don’t have as much concern about conflicting port assignments either - so if you have multiple apps trying to run on 443/80 - you don’t have to give them all oddball port numbers mapped to the standard port (81:80, 82:80, in docker create/compose).

@obbers - ya I know it must be possible, all compose does is call the create commands. For me, I love it because as I start building out each new service/app I run - it allows you to easily change the docker create command without having to through the usual docker stop, docker rm, docker volume rm, etc - just a simple docker-compose up -d name, and it re-creates the container with the modifications applied in tow. That and it makes it easy when I go through mucking around with things or when I change host later, etc. I encourage use of compose, it’s simplified many things for sure. I don’t want to bear all the “details” of the services, but I’ve got about 12 different containers running my apps, so UPnP and port conflicts are becoming more prevalent! :wink:

So just a followup - I can confirm that this successfully works and solves my issue with the conflicting UPnP port problems as well. Now my Plex container is running happily on the Bridge, while my OH container is running on the macvlan network. It has it’s own exposed ports and no need to even specify the ports anymore in the compose file.

2 Caveats to point out:

  • If you’re running ESXi and your Docker Host is a VM inside - you will need to enable Promiscuous mode on the Port Group. By default Forged Transmits and Mac Changes are allowed, but promiscuous mode allows the packets to get to the VM if the MAC doesn’t match the receiving VM (in this case the Docker Host).
  • I still haven’t identified or figured out how to create the macvlan network in the compose file, so for now I’ve followed the instructions on just creating a network outside of compose, then using the Networks top-level key to specify this network as an External, named it, then specified this network under the openhab Service key.
  • And if you’re looking to specify you’re own IP in the compose file, put a sub-key under the Networks section for ipv4_address and specify the IP. This will make sure you get a static mapping, and that you don’t conflict with DHCP ranges potentially on your production network.

Next up is to see if I can get OH to appear/work under the Muximux app so I can have all my apps viewable from one page!

Following up to help anyone else looking for the Compose formatting. I finally had a kind soul point out what I was missing in the formatting on Reddit, and was able to successfully get this network config into my Compose file. Formatting below as a sample - this will allow setting up a macvlan based network in your docker host, along with the ability to specify a manual IP address for the system - this will let you have less problems with your UPnP based integrations and potential port conflicts on said services.

    driver: macvlan
      parent: "ens160"
      - subnet:

You can then use the following in the individual Compose service section:

1 Like


If I do an update of the docker image as described here, rules and items are not working. I tried to force a reload using touch on the files, but it only says something like “Refreshing model ‘home.items’”. Nothing more. I really have to open every file in an editor, change it and save it again.
Is someone experiencing similar problems? Is there another solution to my problem?


I’m both new to docker and openhab so as you can imagine I’m hopelessly lost at this point. I’m very familiar with linux so I’m not a total loss. One thing that has frustrated me and is leading me to abandon this entire docker concept is how convoluted it seems to be. I want to be able to ssh into it and make changes and such, but I have not been able to do so. All of these things you are talking about doing in this thread are not available to me running a docker image in my freenas box. I’m thinking I will just set up individual VM’s for my needs and be done with this idea. Can someone shed light on how I can simply ssh into my docker container let alone make changes to the mqtt.conf so I can have openhab recognize my mqtt container? It’s escaping me at the moment despite my best efforts.

Docker is not designed to work that way. It is considered a bad practice to be able to ssh into a running container.

First of all realize there are two things of concern, Images and Containers. Think of the Image as the contents of a hard drive. That is where you make changes you want to persist. But just like a hard drive, Images are inert.

A Container is like a program that has been loaded into memory and is executing. A Container is ephemeral. And you can have more than one Container running from the same Image.

Now a completely ephemeral container is not much good to anyone. This is what Volumes are for. A volume is a way to mount a folder from the host into the container. This is where you put your configs and databases and such. Because the data gets saved to the host, it gets persisted even when the Image changes and new Containers are created. So, for openHAB 2 one mounts the conf and user data folders into the container. For Mosquito, one mounts /etc/mosquito into the container.

There might be times when you want to make a change to a Container, for example when debugging a problem or adding new features, but your changes will not persist unless you create a new Image from that container, or even better, modify the Dockerfile to make the changes to the Image that gets built.

You can do this by running:

docker exec mosquito /bin/bash

Assuming the name of your container is “mosquito”.

By, like I said above, the proper way to configure mosquito would be to mount a volume to conf. Then you edit the mqtt.cfg file on the host.

Please see the basic tutorial on Docker’s website, review the op above again, paying attention to where it talks about volumes. And review the readme for the openHAB Docker Image on dockerhub and/or the GitHub repo for the docker image.


Appreciate the insight, but I have an additional problem in that I’m using freenas to host the docker containers and there is very little documentation on there middleware so a lot of the volume stuff is managed by that middleware. I think I need to figure that out before I’m going to make it through to actually getting this to work.


so to be clear, we either should create an openhab:openhab user & group with id 9001 on the host system:

groupadd -g 9001 openhab
useradd -u 9001 -g openhab -r -s /sbin/nologin openhab
usermod -a -G openhab openhab
usermod -a -G openhab dominikkv

or we create our own openhab:openhab user with our own UID/GID, and have to pass the UID to the container and run the container with the openhab user (--user <openhabuserid> and -e "USER_ID=<openhabuserid>"), is that correct?

Someone should fix the documentation on and and in the beginning of this tutorial :slight_smile:


It would be great if you created an issue on the openhab-docs repo.

It is already covered in the docs on dockerhub:

Environment variables
By default the openHAB user in the container is running with:

uid=9001(openhab) gid=9001(openhab) groups=9001(openhab)

I’ve created another community topic with details on how to run the openHAB Docker containers with Rancher (container management platform). :cowboy_hat_face:

1 Like

Hi, new to openhab but not to docker. I noticed that when following the tutorial and using the --user switch the container fails to start with the following error:

  • NEW_USER_ID=1008
  • NEW_GROUP_ID=1008
  • echo 'Starting with openhab user id: 1008 and group id: 1008’
    Starting with openhab user id: 1008 and group id: 1008
  • id -u openhab
    Create group openhab with id 1008
  • echo ‘Create group openhab with id 1008’
  • groupadd -g 1008 openhab
    groupadd: Permission denied.
    groupadd: cannot lock /etc/group; try again later.

The container started with when only using the environment variable switches (-e USER_ID & -e GROUP_ID) and it also created the files on the host with the correct user id. Did I miss anything obvious? I couldn’t find any further mentions of the issue on the forum.

Thank you. Would you please file an issue on the openhab-docs repo. When the tutorial was written I don’t think the container yet supported the user and group environment variables. Or, if you think the container should support the --user flag file an issue with openhab-docker.


1 Like


I have already opened a pull request with those changes.


While I’ve got someone who knows their way around the OH Docker image…

Does @Benjy’s suggestion on this thread make sense?

It has been on my list to try my hand at implementing this but I’m nowhere near a Docker expert and am not sure what the side effects of the above would be.

But if we can come up with a way to upgrade without all but wiping out the userdata folder that would all kinds of awesomeness.

I have a question how to proceed if I want to test a new binding in a docker container environment. To be more specific, I have a running stable docker container based on the final OH2 2.2 image and I am happy with that. Now I want to test the beta version of a binding which is currently only on GitHub. So I would clone the docker image and clone my personal user data directories (conf, addons, … etc.) and have then a clone of my existing docker environment.

My question is: How do I proceed now to replace an existing binding of a docker image with the beta version from GitHub?

Would I simply put the new bindings file into the addons folder?
Would OH2 be smart enough to see that there is a newer version of the binding and activate the one from the addons folder instead of the one coming in the container?
Or do I need to deinstall/remove/deconfigure the existing binding before OH2 detects the new binding in the addons folder?

I would kindly appreciate your tipps and tricks.



And I guess the best way is to do this via Paper UI oder HABmin, right?

Depends on how you install the add-ons in the first place. If you use the UIs then yes. If you use the karaf console you should uninstall them from there. If you use addons.cfg you should remove the binding from there.