From aa417274a5bd8a127e1d62da6cf738eab74a183e Mon Sep 17 00:00:00 2001
From: Phill Kelley <34226495+Paraphraser@users.noreply.github.com>
Date: Tue, 23 Apr 2024 16:29:47 +1000
Subject: [PATCH] 2024-04-23 Domoticz - master branch - PR 1 of 2

Updates service definition:

- Change image to `domoticz/domoticz:stable`
- Adopt IOTstack convention for `TZ=`
- Support [documented](https://hub.docker.com/r/domoticz/domoticz)
environment variables
- Remove mapping for port 6144 (no longer in use)
- Change internal TLS port to 443
- Remove redundant `data` subdirectory from left hand side of volume
mapping
- Adopt new image's convention for right hand side of volume mapping

Adds some documentation centred on these changes.

Signed-off-by: Phill Kelley <34226495+Paraphraser@users.noreply.github.com>
---
 .templates/domoticz/service.yml | 21 +++++-----
 docs/Containers/Domoticz.md     | 73 ++++++++++++++++++++++++++++++++-
 2 files changed, 82 insertions(+), 12 deletions(-)

diff --git a/.templates/domoticz/service.yml b/.templates/domoticz/service.yml
index 86419b604..931ae2db0 100644
--- a/.templates/domoticz/service.yml
+++ b/.templates/domoticz/service.yml
@@ -1,16 +1,15 @@
 domoticz:
   container_name: domoticz
-  image: lscr.io/linuxserver/domoticz:latest
+  image: domoticz/domoticz:stable
+  restart: unless-stopped
+  environment:
+    - TZ=${TZ:-Etc/UTC}
+    # - LOG_PATH=/opt/domoticz/userdata/domoticz.log
+    # - EXTRA_CMD_ARG=
   ports:
     - "8083:8080"
-    - "6144:6144"
-    - "1443:1443"
+    - "1443:443"
   volumes:
-    - ./volumes/domoticz/data:/config
-  restart: unless-stopped
-  environment:
-    - PUID=1000
-    - PGID=1000
-    # - TZ=Etc/UTC
-    # - WEBROOT=domoticz
-
+    - ./volumes/domoticz:/opt/domoticz/userdata
+  x-devices:
+    - "/dev/serial/by-id/usb-0658_0200-if00-port0:/dev/ttyACM0"
diff --git a/docs/Containers/Domoticz.md b/docs/Containers/Domoticz.md
index d4648961a..291786d2a 100644
--- a/docs/Containers/Domoticz.md
+++ b/docs/Containers/Domoticz.md
@@ -7,10 +7,81 @@
 	- [User Guide](https://www.domoticz.com/DomoticzManual.pdf) (pdf)
 
 - [GitHub: domoticz/domoticz](https://github.com/domoticz/domoticz)
-- [DockerHub: linuxserver/domoticz](https://hub.docker.com/r/linuxserver/domoticz)
+- [DockerHub: domoticz/domoticz](https://hub.docker.com/r/domoticz/domoticz)
 
 ## Invitation
 
 There is no IOTstack documentation for Domoticz.
 
 This is a standing invitation to anyone who is familiar with this container to submit a Pull Request to provide some documentation.
+
+## Environment Variables
+
+* `TZ=${TZ:-Etc/UTC}`
+
+	If `TZ` is defined in `~/IOTstack/.env` then the value there is applied, otherwise the default of `Etc/UTC` is used. You can initialise `.env` like this:
+	
+	``` console
+	$ cd ~/IOTstack
+	$ [ $(grep -c "^TZ=" .env) -eq 0 ] && echo "TZ=$(cat /etc/timezone)" >>.env
+	```
+
+* `LOG_PATH=/opt/domoticz/userdata/domoticz.log`
+
+	This is disabled by default. If you enable it, Domoticz will write a log to that *internal* path. The path corresponds with the *external* path:
+	
+	```
+	~/IOTstack/volumes/domoticz/domoticz.log
+	```
+
+	Note that this log is persistent. In other words, it will survive container restarts. This means you are responsible for pruning it from time to time. The Unix tradition for pruning logs is:
+	
+	``` console
+	$ cd ~/IOTstack/volumes/domoticz/
+	$ cat /dev/null | sudo tee domoticz.log
+	```
+	
+	If, instead, you decide to delete the log file, you should stop the container first:
+	
+	``` console
+	$ cd ~/IOTstack
+	$ docker-compose down domoticz
+	$ sudo rm ./volumes/domoticz/domoticz.log
+	$ docker-compose up -d domoticz
+	```
+
+* `EXTRA_CMD_ARG=`
+
+	This is disabled by default. It can be enabled and used to override the default parameters and pass [command-line parameters](https://www.domoticz.com/wiki/Command_line_parameters) of your choosing to Domoticz.
+
+## Devices
+
+The service definition includes an `x-devices:` clause. The `x-` prefix has the same effect as commenting-out the entire clause. If you wish to map an external device into the container:
+
+1. Adjust the left-hand-side of the example path to point to the device as it appears on your Raspberry Pi;
+2. Remove the `x-` prefix.
+3. Recreate the container:
+
+	```
+	$ cd ~/IOTstack
+	$ docker-compose up -d domoticz
+	```
+
+## Migration Notes
+
+1. Older IOTstack service definitions for Domoticz used the `lscr.io/linuxserver/domoticz:latest` image. The current service definition uses the `domoticz/domoticz:stable` image.
+2. The location of the persistent store has changed, as has its relationship to the internal path:
+	
+	service definition | persistent store                 | internal path
+	-------------------|----------------------------------|--------------
+	older              | ~/IOTstack/volumes/domoticz/data | config
+	current            | ~/IOTstack/volumes/domoticz      | /opt/domoticz/userdata
+
+	If you have have been using the older service definition and wish to upgrade to the current service definition, you  can try migrating like this:
+	
+	``` console
+	$ cd ~/IOTstack/volumes
+	$ sudo mv domoticz domoticz.old
+	$ sudo cp -a domoticz.old/data domoticz
+	```
+