Running openHAB with Rancher

Rancher greatly simplifies running containers on various hosts. It also has a template system which allows for easy container customization.

For those who want to use openHAB with the Rancher container management platform, it is nowadays part of the default Rancher Community catalog.

Here is a brief guide on how to get openHAB running with Rancher (assuming you have some Docker knowlegde and Docker is already installed on your machine).

With Rancher you run a Server container and per host (which connects to the server) an Agent container. On the Server you can create application Stacks that run on one or more agents. You can also run an Agent on the same host that the server runs on.

Running Rancher Server

  1. Run the Rancher server container and let it listen at port 4444:
    sudo docker run -d --restart=unless-stopped -p 4444:8080 --name rancher-server rancher/server:stable

  2. When the server container has fully started, open the Rancher UI in your browser (initial startup takes some time): e.g. browse to http://hostname:4444

Adding a Host for running Docker containers (Rancher Agent)

This host can either be the machine on which Rancher Server is running or a completely different host.

  1. Open the ‘Infrastructure -> Hosts’ page
  2. Check if “This site’s address” is an IP that other machines can use for connecting to Rancher
  3. When it is set to “http://localhost:4444” then choose the “Something else:” option and enter an IP which computers in your network can use to connect to Rancher, e.g. “
  4. Click the Save button
  5. At step (4) of the Wizard you should enter the external IP of the machine that is going to connect to the server, e.g. “” when it is the same machine
  6. Now copy the command at step (5) of the Wizard and run it at the machine you want to use for running your Docker containers
  7. Click the “Close” button and after some time the machine should show up in the “Hosts” view.

Creating an openHAB Stack

  1. Open the ‘Catalog -> Community’ page, and enter “openHAB” in the search field
  2. Click the View Details button
  3. You optionally can customize the template options which are based on those of the openHAB Docker Readme
  4. When you click the Launch button, a new Stack is created that is automatically deployed on the host running the Rancher Agent.

You should now be able to login at openHAB via the port you’ve configured in the template (8080 by default).


  • Make sure to enable Access Control via ‘Admin -> Access Control’!
  • When you connect multiple Rancher Hosts to the Server you can assign labels to the hosts and use the “Host Label” in the openHAB template to run openHAB on a specific host
  • The Rancher Catalog contains many templates that also simplify using other containerized applications


Catalog Template Logging

User Stacks Host Details

Container Details

See also


For the uneducated (like myself) how does this differ from running a normal openHAB docker container? What are the pros/cons?

Yes that is a good question!

Rancher uses exactly the same Docker container as you would normally run with a docker or docker-compose command. So when openHAB is the only Docker container you use there will not be much added value of also using Rancher.

It makes a lot of sense to start using a container management platform like Rancher once you start running a lot of containers on different hosts. It allows you to easily manage all your hosts from one graphical user interface. So you can deploy, check performance metrics and logging of all connected containers/hosts using a single UI.

You can also easily open a shell in any container of the connected hosts without first having to SSH to the host and then get into the container with docker exec.

It also allows you to define health checks on containers (see Container Details screenshot). The platform will for instance mark the openHAB container as unhealthy when connections to port 8080 fail several times. When containers become unhealthy you can either manually resolve this or define a strategy the platform uses to resolve this.

The user friendly GUI also helps with simplifying Docker technology so non-Developers (Operations) can easily deploy and support containers applications stacks. Installing/upgrading complete container stacks becomes clicking some buttons, checkboxes and entering some occasional text (see openHAB Template screenshot).

There is also access control using a local user directory/LDAP/etc. What people can do with containers is managed through a permissions system.

One of the biggest downsides is of course that you’ll need to learn how Rancher works and what its limitations are. It may be well worth your time when all of the functionality it provides solves more issues than you have with learning it.

Hey @wborn,
that’s a great addition! Did you think about adding your Rancher option to the official documentation under or in an addition article next to that one? Feel free to open a Pull Request against the docs repo!

Did you think about adding your Rancher option to the official documentation

I did not think about it yet. But now I do! I’ll first see in this thread what questions the documentation needs to answer. :slight_smile:

1 Like

This looks cool. I was able to start a container, but it’s unclear on how to manage to add volumes like /opt/openhab/conf so that I don’t have to configure each time.

Yes volume management may be a bit different than you are used to when using Rancher.

When you run a lot of containers it does not scale well to mount directories to specific host directories which are used in the openHAB Docker readme examples. It then starts to make sense to store data at dedicated storage machines. So that when a container stops due to a server crash/restart/upgrade another one can easily take over using the same data.

There is still the (default) “local” volume driver option that stores the data in volumes on the same machine running the container. You usually have direct access to this data on the host via /var/lib/docker/volumes.

If you still want to mount specific directories of the host you can ofcourse always fork the catalog and modify the volumes in docker-compose.yml.tpl. Rancher Compose uses the same syntax as Docker Compose but it also supports the Go Template Engine

When you delete the stack Rancher will also delete your volumes! So you should only delete the stack when you are really sure about this (e.g. after creating a backup).

Rancher does support upgrading a stack to a new version. E.g. when openHAB 2.2.0 is released:

  1. The catalog (hosted at GitHub) is updated
  2. Users click the refresh button (the circle at the top right in the Catalog screenshot)
  3. Rancher will show an “Upgrade” button for any stack that can be upgraded
  4. After clicking “Upgrade” on a stack, Rancher will download the new container and start it with the existing volumes

The only issue with step 4. is that there are still some manual steps involved when upgrading the openHAB containers. E.g. like cleaning /userdata/tmp and /userdata/cache and possibly manually migrating /userdata/etc

All Pull Requests got merged today so now all openHAB versions (including the new 2.2.0 and 2.3.0-SNAPSHOT) can be installed via the default Rancher Community catalog! :slight_smile:

The instructions for manually adding an openHAB catalog have been removed from the opening post.

If you’ve been using this catalog you can remove it from ‘Admin -> Settings’. After refreshing the Community Catalog you should now also find an openHAB catalog item after entering “openHAB” in the search field.

1 Like

This is the most complete and clean rancher community catalog contribution I’ve seen so far. The choice for different architectures and distributions is amazing and every important option is laid out nicely.

While every service except for openHAB and the SSH gateway are running on Rancher here, I will definitely give it a try the next weeks. I will probably need a USB hub for all the gateways, though. :wink:

Thank you very much for this!

Thanks @gersilex! Nice to know there are other Rancher users here as well. :slight_smile:

After using Rancher for other projects it was only natural to also create an openHAB catalog item. The existing community catalog items also serve as a good source of inspiration!

It should now be possible to upgrade existing containers in most cases without manual intervention by simply clicking the “Upgrade” button. :slight_smile:

When you manually edit files in /userdata/etc they may be overwritten during the upgrade. During the upgrade a backup of /userdata is made and stored in /userdata/backup.

See also: New Docker Upgrade Ability.

1 Like

Today openHAB 2.3.0 and 2.4.0-SNAPSHOT were added to the Rancher Community Catalog.

Other improvements are:

  • Links to official release notes
  • Template option to configure the Java cryptographic strength policy
  • Update links to new openHAB website layout