Docker

Introduction

You can also install Domoticz as a Docker container. Using a Docker container gives you ease in the configuration and requirements of your system. No dependencies on libraries, Python versions etc.

Also some frequently used hardware gateways like Zigbee2MQTT and Zwave-JS-UI (and their interface Mosquitto MQTT) can run in separate Docker containers.

Using Docker with Domoticz will require some general knowledge how to use and maintain Docker environments. See for example https://docs.docker.com/get-started/docker-concepts/running-containers/publishing-ports/

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!

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.

Update the Domoticz Docker Container

Docker-Compose: Use the following command in a terminal session in the directory where the docker-compose.yml is located:

docker compose pull && docker compose up --force-recreate --build -d && docker image prune -f

Docker -run: Use the following command in a terminal session (change <container name> in the real container name):

  docker pull <container name>
  docker stop <container name>
  docker rm <container name>
  docker run -d -p 8080:8080 -p 8443:443 -v <path for config files>:/opt/domoticz/userdata -e TZ=Europe/Amsterdam  --device=<device_id> --name=<container name> domoticz/domoticz:stable

Serial Port

If you need to access 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"

Ports

If you use ssl and or Device Sharing make sure those ports (eg default 443 and 6144) are enabled in your docker config

Docker Compose:

ports:   
 - "8080:8080"
 - "8443:443"
 - "6144:6144"

or with docker run: docker run -d -p 8080:8080 -p 8443:443 -p 6144:6144

Note: First port value is outside port, second value is inside container port (as configured in Domoticz). So for example the Domoticz configured ssl port 443 is accessible outside the container through port 8443.

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.