Docker

Running Domoticz inside Docker

Introduction

Using Domoticz from within a docker container has several advantages.

Your system stays clean, easy backup and transfer.

It is important to understand that docker containers work with volumes. Volumes are the folders/files that needs to be persistent. (Like the configuration)

Everything else is 'virtual'. Also understand that a docker is not a virtual machine, It does not emulate, meaning, the performance is as fast as running this natively!

First get yourself familiar with Docker. Make sure you have already installed both Docker Engine and Docker Compose.

We highly recommend using 'docker-compose' as maintaining the configuration will be much easier

Install docker on a linux system

sudo apt-get update && sudo apt-get upgrade

sudo apt-get install -y make git

curl -fsSL test.docker.com -o get-docker.sh && sh get-docker.sh

sudo usermod -aG docker ${USER}

sudo systemctl enable docker

sudo reboot

Platforms

The official docker image of Domoticz supports the following platforms

• 32 and 64 Arm
• 64 bit Linux

This should cover most platforms.

Default installation

The Docker image can be found here:

https://hub.docker.com/r/domoticz/domoticz

This website also gives the detailed instructions how to install and update the docker image based on docker compose.

docker image tags

docker pull domoticz/domoticz:stable

It is possible to use stable (preferred!) and beta images: https://hub.docker.com/r/domoticz/domoticz/tags

docker pull domoticz/domoticz:beta (will pull latest beta version)

docker pull domoticz/domoticz:stable (will pull latest stable version)

docker pull domoticz/domoticz:2022.1 (will pull latest stable version 2022.1)

docker pull domoticz/domoticz:2022-beta.12345 (will pull beta with build number 12345)

tag latest or no tag will pull the latest uploaded image, so could be a beta or stable image.

Serial Port

If you need to acces a USB dongle connected to your system, we need to identify this serial device.

We do this by issuing the following command

ls /dev/serial/by-id

You should see one or multiple serial devices, find out which one is your RF stick, for example it's: usb-0658_0200-if00-port0

You need to add this device to the docker container in the docker-compose.yml like

devices:

- "/dev/serial/by-id/usb-0658_0200-if00-port0:/dev/ttyUSB0"

or in the docker startup line with

--device="/dev/serial/by-id/usb-0658_0200-if00-port0:/dev/ttyUSB0"

custom startup script for the container

The container supports running a custom bash script (customstart.sh in userdata) before the domoticz process starts. This way, you can customise anything in the container that you need:

• install incremental apt packages (don't forget to apt update before you apt install)
• install incremental python functions (pip3 install)
• and so on

The container calls a script named customstart.sh in userdata, if that script exists. Please note that the script gets called on EVERY start of the container, not just at creation time. If you want the script to run only once, you need to build that in your script (e.g. test for a file you create in the script).

Example script

#!/bin/bash

if [ -f /opt/domoticz/FIRSTRUN ]; then
true
else
echo 'updating packages'
apt-get -qq update
echo 'installing mosquitto clients'
apt-get -y install mosquitto-clients
echo 'installing iputils-ping'
apt-get -y install iputils-ping
echo 'creating FIRSTRUN file so script can check on next run'
touch /opt/domoticz/FIRSTRUN
echo 'copying event script templates to external mapped storage /volume1/domoticz/scripts/templates
cp -r /opt/domoticz/scripts/templates  /opt/domoticz/userdata/scripts
cd /opt/domoticz || return
fi

Python Plugins

When launching the docker container for the first time, a plugin folder is created in the mounted /opt/domoticz/userdata folder You need to place your python plugins in this folder.

This container runs Python 3.9.2

When plugins need extra python modules you need to install those in the Docker container! You can use the custom startup script (mentioned above) for this.

Docker and dzVents

Make sure you have created the following script subfolders manually in your mounted /opt/domoticz/userdata folder if you get errors complaining about these folders:

• scripts/dzVents/generated_scripts (so from within container /opt/domoticz/userdata/scripts/dzVents/generated_scripts)
• scripts/dzVents/scripts

Latest beta 2023.1 should have these folders create at starrtup

If you have no DzVents templates in event system you have to copy the templates to the volume.

In customstart.sh add the following line (to be modified to your environment):

echo 'copying event script templates to external mapped storage /volume1/domoticz/scripts/templates

cp -r /opt/domoticz/scripts/templates /opt/domoticz/userdata/scripts

Debugging

Switch on Domoticz logging to OS

Switch on logging to an OS file with Docker environment parameter LOG_PATH=/opt/domoticz/userdata/domoticz.log

With the Docker environment parameter EXTRA_CMD_ARG (see the page https://hub.docker.com/r/domoticz/domoticz) you can set additional command line parameters (see also page Command Line Parameters) for extra debugging. For example:

EXTRA_CMD_ARG= -loglevel normal,status,error,debug -debuglevel normal,hardware,received,webserver,eventsystem,python,thread_id

Shell access while the container is running

To get into the docker container to check config files or install extra software use command

docker exec -it domoticz 

Monitor the logs of the container

docker logs -f domoticz

Questions:

If you have questions about this new official Docker container, please go to the following forum topic: https://www.domoticz.com/forum/viewtopic.php?f=4&t=35454

In case you want to install a Domoticz Docker container on a Synology, please read Domoticz on a Synology NAS.