Tutorial: Run a test Docker image

Tutorials
1

Sometimes a developer wants to offer a “test” Docker image on the forum to allow users to test a new integration before it is deployed to production.

Unlike the “official” Docker image, which is hosted on the project account gladysassistant/gladys, a test image will be hosted on the developer’s Docker account. Example: jeanfrancois/gladys.

To run a test Docker image, it’s the same process as described on the Gladys installation page via Docker: Docker | Gladys Assistant.

The only difference is that you need to change the image name in the docker run to the test image, and modify some parameters of the command.

Before you begin

:warning: :warning: If you don’t know what you’re doing, avoid running your test image on the same machine as your production installation, as this could have consequences for your installation! :warning::warning:

Launching the test image

Let’s imagine we want to run a test image of the “zwave” integration, developed by “jeanfrancois”.

We’ll take the docker run command from the Gladys site, and modify several things:

  • The container name, for example « gladys-zwave-test » instead of « gladys »: --name gladys-zwave-test \\
  • The port on which Gladys runs, for example 8001 instead of 80: -e SERVER_PORT=8001 \\
  • The folder where all Gladys files will be stored (database, configuration): -v /var/lib/gladysassistant_zwave_test:/var/lib/gladysassistant \\
  • The name of the Docker image to run: jeanfrancois/gladys instead of gladysassistant/gladys

Which gives us this command :

docker run -d \
--log-driver json-file \
--log-opt max-size=10m \
--cgroupns=host \
--restart=always \
--privileged \
--network=host \
--name gladys-zwave-test \
-e NODE_ENV=production \
-e SERVER_PORT=8001 \
-e TZ=Europe/Paris \
-e SQLITE_FILE_PATH=/var/lib/gladysassistant/gladys-production.db \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /var/lib/gladysassistant_zwave_test:/var/lib/gladysassistant \
-v /dev:/dev \
-v /run/udev:/run/udev:ro \
jeanfrancois/gladys

To access Gladys:

http://IP_MACHINE:8001

To stop this container:

docker stop gladys-zwave-test

To remove this container:

docker rm gladys-zwave-test

To fetch a new version of the image

(if the dev has progressed on their integration):

docker pull jeanfrancois/gladys

Note that a Docker container is immutable: if you pull a new image, you must stop the container, remove the container, then docker run a new container :slight_smile:

Note:

Avoid connecting your Gladys Plus account to a test instance, as this will disconnect your production instance.

4

A few questions to understand how this works…

Can you run a test instance on the same machine as the production instance by installing the test image as described above and just changing the port?

The test instance is completely independent but will read from and write to the same database as the production image?

5

yes

yes if you leave EXACTLY the same path and file names as your production,
no because normally you change the data directory (in any case it’s better!).

If you want to run tests on the same host and you want to retrieve the existing information/configs, make a copy of the files (you rename with -test for example) and then you modify the file names in the docker run.
I hope I’m clear enough :face_with_raised_eyebrow:

6

Small remarks:

  • Following my last attempt, I was able to confirm that when Gladys is configured for the first time, an MQTT container is created/configured at the same time. This behavior causes a conflict when testing on a production machine because the configuration of the original container is overwritten by that of the new one. After stopping/deleting the test image, you need to re-register the MQTT server configuration in the production Gladys.
  • Similarly, when testing on your production machine (of course, a different database), a conflict arises with external integrations that go into a ‹ degraded › state on the production environment. Therefore, after stopping/deleting the test image, you need to restart each of the external integrations.
  • Regarding the command given by @pierre-gilles, I would not set the container to restart=always but rather to unless-stopped. This allows you to simply stop the test container without it restarting constantly…
7

OK, thanks for these details!

But if we install the test image on a test machine, for example an old Raspberry Pi, how do we communicate with the existing Zigbee network (without disrupting it)?

8

Ah, well, what you can do is go through the z2m of your original installation by configuring, in your test installation, an external ZigBee container (which will be the one for your production)…