make healthchecks optional

CHANGELOG.md

@@ -8,7 +8,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ## [Unreleased]
 ### Added
 * klipper & moonraker: generate version file during build to correctly display versions
-* klipper, moonraker & ustreamer: add healthchecks to container images
+* klipper, moonraker & ustreamer: add health check scripts to container images
+* docs: health check examples
 ### Fixed
 ### Changed
 ### Removed

README.md

@@ -330,6 +330,30 @@ Update the `image:` name and add a `build` config:
       target: run
 ```
 
+### Healthchecks
+Klipper, Moonraker and Ustreamer images contain scripts that can be used to determine the overall health of the application.  
+Healthchecks have not been added to the Dockerfiles of these images, as they consume a considerable amount of CPU cycles and may lead to unwanted behaviour on low powered machines.   
+In tests, cpu usage of containers was **doubled** when executing the healtch check every 30s and increased **sixfold** when executing every 5s.  
+
+You can enable health checks by adding them to your `docker-compose.override.yaml`.  
+Reference the [compose file docs](https://docs.docker.com/reference/compose-file/services/#healthcheck) on how to further tweak these checks.
+
+```yaml
+services:
+  klipper:
+    healthcheck:
+      test: ["python3", "/opt/health.py"]
+      interval: 30s
+  moonraker:
+    healthcheck:
+      test: ["bash", "/opt/health.sh"]
+      interval: 30s
+  webcam:
+    healthcheck:
+      test: ["bash", "/opt/health.sh"]
+      interval: 30s
+```
+
 ### Enable Mainsail remoteMode
 In case Moonraker is not situated on the same Host as Mainsail, you'll have to enable remoteMode in Mainsail to set up a remote Printer. This mirrors the behaviour of https://my.mainsail.xyz.
 

docker/klipper/Dockerfile

@@ -40,7 +40,6 @@ RUN mkdir -p printer_data/run printer_data/gcodes printer_data/logs printer_data
  && chown -R klipper:klipper /opt/*
 
 COPY --chown=klipper:klipper health.py ./
-HEALTHCHECK --interval=5s CMD ["python3", "/opt/health.py"]
 
 COPY --chown=klipper:klipper --from=build /opt/klipper ./klipper
 COPY --chown=klipper:klipper --from=build /opt/venv ./venv

docker/klipper/README.md

@@ -121,8 +121,22 @@ none
 |`hostmcu`|Runtime Image for the klipper_mcu binary|Yes|
 
 ## Healthcheck
-`/opt/health.py` gets executed every 5s inside the container.  
+`/opt/health.py` is available to check the health of the container.  
+
+> Be aware that enabling health checks in docker may increase CPU usage drastically.  
+> In tests, cpu usage of the container was doubled when executing the healtch check every 30s and increased sixfold when executing every 5s.  
+> This may lead to resource shortages on low powered host and unwanted behaviour  
+
 The script does the following:
 * queries klippers `info` endpoint via its unix socket
 * Checks if state is `ready`
-* If one of the above requirements is not `ready`, the script exits with a failure state to indicate the container is unhealthy
+* If one of the above requirements is not `ready`, the script exits with a failure state to indicate the container is unhealthy
+
+Compose example:
+```yaml
+services:
+  klipper:
+    healthcheck:
+      test: ["python3", "/opt/health.py"]
+      interval: 30s
+```

docker/moonraker/Dockerfile

@@ -50,7 +50,6 @@ RUN mkdir -p printer_data/run printer_data/gcodes printer_data/logs printer_data
  && chown -R moonraker:moonraker /opt/*
 
 COPY --chown=moonraker:moonraker health.sh ./
-HEALTHCHECK --interval=5s CMD ["bash", "/opt/health.sh"]
 
 COPY --chown=moonraker:moonraker --from=build /opt/moonraker ./moonraker
 COPY --chown=moonraker:moonraker --from=build /opt/venv ./venv

docker/moonraker/README.md

@@ -88,10 +88,24 @@ services:
 
 ## Healthcheck
 `/opt/health.sh` gets executed every 5s inside the container.  
+
+> Be aware that enabling health checks in docker may increase CPU usage drastically.  
+> In tests, cpu usage of the container was doubled when executing the healtch check every 30s and increased sixfold when executing every 5s.  
+> This may lead to resource shortages on low powered host and unwanted behaviour  
+
 The script does the following:
 * queries the `/server/info` endpoint of moonraker
 * Performs the following checks
   * Number of failed moonraker_components = 0
   * klippy_connected is `true`
   * klippy_state is `ready`
-* If one of the above requirements is not met, the script exits with a failure state to indicate the container is unhealthy
+* If one of the above requirements is not met, the script exits with a failure state to indicate the container is unhealthy
+
+Compose example:
+```yaml
+services:
+  moonraker:
+    healthcheck:
+      test: ["bash", "/opt/health.sh"]
+      interval: 30s
+```

docker/ustreamer/Dockerfile

@@ -49,7 +49,6 @@ RUN groupadd ustreamer --gid 1000 \
  && usermod ustreamer --append --groups video
 
 COPY --chown=ustreamer:ustreamer health.sh ./
-HEALTHCHECK --interval=5s CMD ["bash", "/opt/health.sh"]
 
 COPY --chown=ustreamer:ustreamer --from=build /opt/ustreamer/src/ustreamer.bin ./ustreamer
 

docker/ustreamer/README.md

@@ -55,9 +55,23 @@ none
 
 ## Healthcheck
 `/opt/health.sh` gets executed every 5s inside the container.  
+
+> Be aware that enabling health checks in docker may increase CPU usage drastically.  
+> In tests, cpu usage of the container was doubled when executing the healtch check every 30s and increased sixfold when executing every 5s.  
+> This may lead to resource shortages on low powered host and unwanted behaviour  
+
 The script does the following:
 * gets the JSON structure with the state of the server
 * Checks the following values
   * `.ok` is set to `true`, which indicates ustreamer is working
   * `.result.source.online` is set to `true`, which indicates the source (webcam) is returning an image rather than `NO SIGNAL`
-* If one of the above requirements is not met, the script exits with a failure state to indicate the container is unhealthy
+* If one of the above requirements is not met, the script exits with a failure state to indicate the container is unhealthy
+
+Compose example:
+```yaml
+services:
+  ustreamer:
+    healthcheck:
+      test: ["bash", "/opt/health.sh"]
+      interval: 30s
+```