How to: Install and setup Jython with the official openHAB Debian Docker container on Ubuntu

This guide is outdated. If the following pull request is accepted then it will be as easy as adding two files to the /etc/cont.init.d/ directory and both Jython and the openHAB Helper Libraries will be installed for you automatically.

This topic describes how I have setup Jython with the official openHAB Debian Docker container. It is the result of 3 evenings crawling through various topics here on the forum, the information provided in the openHAB documentation, the OH-Jython-Scripters and docker-oh2-jsr223 Github repositories.

The main goal I had was to setup a development environment to experiment with writing openHAB rules in Python and I wanted to be able to destroy the container without destroying my Jython configuration and Python rules.

Please be aware that these instructions are based on Ubuntu Desktop 18.04 LTS. If you use a different distribution you may have to make some modifications to make it work for you.

Even though this is not a topic about how to setup Docker on Ubuntu I will provide the instructions on how to quickly setup it up. However, should you have any Docker related questions then please consult the Docker documentation, use Google or open new topic to get help. In this topic I would like to focus on getting Jython to run with the openHAB Docker container.

Install Docker

sudo apt -y install \
    software-properties-common \
    apt-transport-https \
    ca-certificates \

curl -fsSL | sudo apt-key add -

sudo add-apt-repository \
    "deb [arch=amd64] $(lsb_release -cs) stable"

sudo apt update

sudo apt --yes install docker-ce

sudo usermod --append --groups docker $USER

Start a new shell to enable the docker group without the need to logout/login first, or logout and login again and skip this step.

sudo su - $USER

Create the openhab user on the Docker host

sudo useradd -r -s /sbin/nologin openhab
sudo usermod -a -G openhab $USER

Create the directory structure

These directories will be mounted into the container during startup. Any files within these directories will not be lost when the container is destroyed.

sudo mkdir -p /opt/openhab/{addons,conf,lib/jsr223/jython,userdata}
sudo chown -R openhab:openhab /opt/openhab

Start the container

This command will pull (download) the container from Docker Hub and start it up. During the startup of the container, the openHAB startup script will initialize a default openHAB configuration.
Note that this command will run the openhab/openhab:2.4.0-snapshot-amd64-debian image. If you feel less adventurous you should also be able to use the latest milestone version which at the time of writing is openhab/openhab:2.4.0.M4-amd64-debian.

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/lib/jsr223/:/openhab/lib/jsr223/ \
        -v /opt/openhab/userdata:/openhab/userdata \
        -d \
	-e EXTRA_JAVA_OPTS="-Xbootclasspath/a:/openhab/lib/jsr223/jython/jython.jar -Dpython.home=/openhab/lib/jsr223/jython -Dpython.path=/openhab/lib/jsr223/jython/Lib:/openhab/conf/automation/lib/python" \
        -e USER_ID=`id -u openhab` \
        -e GROUP_ID=`id -g openhab` \

Please note the /openhab/conf/automation/lib/python directory in the python.path variable. In this directory you will place additional libraries such as e.g. openhab2-jython and/or lucid.

Select your preferred installation type

Open http://localhost:8080 in a webbrowser and select your preferred installation type (replace localhost by either the hostname or ip address of your openHAB server if you are not running the container on your local computer).

Create directories used by Jython

sudo mkdir -p /opt/openhab/conf/automation/{jsr223,lib/python}
sudo chown -R openhab:openhab /opt/openhab

Enter the container

The remaining commands in this guide will all be run from within the container. The following command will start a bash session inside the container:

docker exec -ti openhab /bin/bash

Install curl

Inside the container install curl so that you can call the openHAB REST API from the command line.

apt update && apt install -y curl

Install the Experimental Next-Gen Rules Engine

Alternatively you can also install the Experimental Next-Gen Rules Engine using Paper UI.

curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" "http://localhost:8080/rest/extensions/misc-ruleengine/install"

Create an item

At least one item must exist. If you already defined at least one item, then you can skip this step.

curl -X PUT --header "Content-Type: application/json" --header "Accept: application/json" -d "{\"type\":\"String\",\"name\":\"jsr223DummyItem\",\"label\":\"This item can be removed when at least one more item exists\"}" "http://localhost:8080/rest/items/jsr223DummyItem"

Download and install Jython

Instead of using the standalone version of Jython, I have opted to use the installer package. The installer package also installs pip which should make it easy to install additional Python packages from within the container should there be a need (I have not tested this yet).

Please be careful when using Jython 2.7.1. There seem to be issues with that version.

wget -O /tmp/jython-installer-2.7.0.jar
java -jar /tmp/jython-installer-2.7.0.jar -s -d /openhab/lib/jsr223/jython/ -t standard -e demo doc src

Create a Hello World rule

Create a Hello World rule which doesn’t depend on any libraries (e.g. openhab2-jython or lucid).

cat <<EOF > /openhab/conf/automation/jsr223/
from org.slf4j import LoggerFactory

LoggerFactory.getLogger("org.eclipse.smarthome.automation.examples").info("Hello world!")

After restarting the container (which you will do at the end of this guide) you should find the “Hello world!” message in the openhab.log file.

Download and install the openhab2-jython library

The openhab2-jython library makes creating rules easier hence we install it here. Note that currently the lucid library is not compatible with openHAB 2.4.0-snapshot nor with openHAB 2.4.0 Milestone 4. Hopefully this will change in the near future.

wget -O /tmp/
unzip /tmp/ -d /tmp

Create a script to wait for the AutomationManager to become available before executing other scripts

This is currently a workaround which in the future hopefully won’t be necessary anymore. For more background information please check the following topic.

cat <<EOF > /tmp/openhab2-jython-master/automation/jsr223/000_components/
# Wait till for the AutomationManager to become available
import time

from org.slf4j import Logger, LoggerFactory

log = LoggerFactory.getLogger("org.eclipse.smarthome.automation")"jsr223: checking for initialised context")

while True:
        if automationManager != None:
        pass"jsr223: context not initialised yet. waiting 10 sec before checking again")
        time.sleep(10)"jsr223: done")

Assign proper permissions

chown -R openhab:openhab /tmp/openhab2-jython-master

Move the files in place

mv /tmp/openhab2-jython-master/automation/lib/python/esper /openhab/conf/automation/lib/python/
mv /tmp/openhab2-jython-master/automation/lib/python/openhab /openhab/conf/automation/lib/python/
mv /tmp/openhab2-jython-master/automation/jsr223/000_components /openhab/conf/automation/jsr223/

Exit the container


Restart the container

docker restart openhab

All done

If all went well and I didn’t make any mistakes when taking these notes (I had to go back and forth many times) then you should now have a working openHAB installation with the ability to write rules in Python.


Bookmarked this one for my next tear down and re-install. Next time I will use docker. So your post is a god send. Thanks.

Awesome! We should add this to the openhab2-Jython readme. The only thing that concerns me, is that you’ve used different paths in EXTRA_JAVA_OPTS, which may confuse people.

The problem is, everybody seems to be using different paths in EXTRA_JAVA_OPTS.

When I was trying to figure out all this stuff it was driving me nuts. Some people even install the jython.jar in the linux /etc directory (/etc is for config files, not libraries) :wink:

At a certain moment I used /openhab/lib/jsr223/python which I think is the cleanest. Not sure why I changed that, but possibly because you use /opt/openhab2/conf/automation/lib/python. I guess I then just modified the openhab2 to openhab to stay inline with the openhab docs.

I need to test to see if there was a technical reason not to use /openhab/lib/jsr223/python, if not, then I will probably go back to that path because libraries don’t belong in the /openhab/conf path in my opinion.

Anyway, very nice to be able to finally put the DSL aside and write rules in a real programming language. It has given me back my joy for home automation and writing rules (my production system is still a Frankenstein build of an 1.8 snapshot release with 1.9 bindings…).

Thanks for posting. This is much more thorough than the quick tutorial I posted previously.