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
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository \
"deb [arch=amd64] https://download.docker.com/linux/ubuntu $(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` \
openhab/openhab:2.4.0-snapshot-amd64-debian
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 http://central.maven.org/maven2/org/python/jython-installer/2.7.0/jython-installer-2.7.0.jar -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/helloworld-vanilla.py
from org.slf4j import LoggerFactory
LoggerFactory.getLogger("org.eclipse.smarthome.automation.examples").info("Hello world!")
EOF
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 https://github.com/OH-Jython-Scripters/openhab2-jython/archive/master.zip -O /tmp/openhab2-jython.zip
unzip /tmp/openhab2-jython.zip -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/000_burntime.py
# Wait till for the AutomationManager to become available
# https://community.openhab.org/t/solved-workaround-jython-jsr223-not-properly-initialised-during-startup/46031/6
import time
from org.slf4j import Logger, LoggerFactory
log = LoggerFactory.getLogger("org.eclipse.smarthome.automation")
log.info("jsr223: checking for initialised context")
while True:
try:
scriptExtension.importPreset("RuleSupport")
if automationManager != None:
break;
except:
pass
log.info("jsr223: context not initialised yet. waiting 10 sec before checking again")
time.sleep(10)
log.info("jsr223: done")
EOF
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
exit
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.
