feat: add docker healthcheck and expand documentation (#7375)
DaanSelen committed
Oct 25, 2025 at 17:31 UTC
6e2f9aad37a57ead0dd2a6157c1ec73bb124f890
2 files changed
+54
-6
docker/Dockerfile
+5
-2
@@ -126,7 +126,7 @@ WORKDIR /opt/meshcentral
126
RUN apk update && \
127
echo -e "----------\nINSTALLING ALPINE PACKAGES...\n----------"; \
128
apk add --no-cache --update \
129
- bash jq nodejs npm tzdata && \
129
+ bash curl jq nodejs npm tzdata && \
130
rm -rf /var/cache/* \
131
/tmp/* \
132
/usr/share/man/ \
@@ -203,7 +203,10 @@ VOLUME /opt/meshcentral/meshcentral-web
203
VOLUME /opt/meshcentral/meshcentral-backups
204
205
# Copy images from Git repo, place it before ending so recompilation can make good use of cache.
206
-COPY ./docker/entrypoint.sh ./entrypoint.sh
206
+COPY ./docker/entrypoint.sh /opt/meshcentral/entrypoint.sh
207
COPY ./docker/config.json.template /opt/meshcentral/config.json.template
208
209
+HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
210
+ CMD curl -k --fail https://localhost:443/health.ashx || exit 1
211
+
212
ENTRYPOINT ["bash", "/opt/meshcentral/entrypoint.sh"]
docker/README.md
+49
-4
@@ -6,7 +6,26 @@
6
> Then the container will overwrite it to a incorrect, but working state - perhaps non-working for your environment.
7
8
## Overview
9
-This document provides a comprehensive guide to setting up and configuring MeshCentral in a Docker environment. It includes available options, security measures, and deployment instructions.
9
+This document provides a comprehensive guide to setting up and configuring MeshCentral in a Docker environment.<br>
10
+It includes available options, security measures, and deployment instructions.
11
+
12
+MeshCentral provides a couple different Docker container variants:<br>
13
+These variants are pulled through 3 main channels: `master` and `latest`.<br>
14
+If you want to target versions, you can also target individual versions; such as `1.1.53`.
15
+
16
+| Variant | Image tag | Full path |
17
+|---------|-----------|-----------|
18
+| All database backends | "" (empty) | ghcr.io/ylianst/meshcentral:\<version\> |
19
+| No database backens (local only) | slim | ghcr.io/ylianst/meshcentral:\<version\>-slim |
20
+| [MongoDB](https://www.mongodb.com/) backend included | mongodb | ghcr.io/ylianst/meshcentral:\<version\>-mongodb |
21
+| [PostgreSQL](https://www.postgresql.org/) backend included | postgresql | ghcr.io/ylianst/meshcentral:\<version\>-postgresql |
22
+| [Mysql](https://www.mysql.com/)/[MariaDB](https://mariadb.org/) backend(s) included | mysql | ghcr.io/ylianst/meshcentral:\<version\>-mysql |
23
+
24
+So for a quick example: if you want to get the bleeding edge code with a PostgreSQL backend: `ghcr.io/ylianst/meshcentral:master-postgresql`<br>
25
+So for another quick example: if you want to get a complete image at the latest released version: `ghcr.io/ylianst/meshcentral:latest`<br>
26
+So for another quick example: if you want to get a released version with a MongoDB backend: `ghcr.io/ylianst/meshcentral:latest-mongodb`<br>
27
+So for another quick example: if you want a very slim image with the latest code and only a local database: `ghcr.io/ylianst/meshcentral:master-slim`<br>
28
+So as a last example: if you want to get a MariaDB/MySQL backend with MeshCentral version 1.1.53: `ghcr.io/ylianst/meshcentral:1.1.53-mysql`
29
30
## Environment Variables
31
Below is a breakdown of environment variables used in this setup.
@@ -77,14 +96,14 @@ docker run -d \
96
-e MONGO_URL=mongodb://username:password@mongodb:27017/meshcentral \
97
-v meshcentral-data:/opt/meshcentral/meshcentral-data \
98
-p 443:443 \
80
- ghcr.io/ylianst/meshcentral:<tag>
99
+ ghcr.io/ylianst/meshcentral:latest # or latest-mongodb
100
```
101
102
### Running with Docker Compose
103
```yaml
104
services:
105
meshcentral:
87
- image: ghcr.io/ylianst/meshcentral:<tag>
106
+ image: ghcr.io/ylianst/meshcentral:latest
107
environment:
108
- HOSTNAME=myserver.domain.com
109
- ALLOW_NEW_ACCOUNTS=false
@@ -96,6 +115,7 @@ services:
115
- meshcentral-web:/opt/meshcentral/meshcentral-web
116
- meshcentral-backups:/opt/meshcentral/meshcentral-backups
117
ports:
118
+ # You can add additional ports here in the same format. Such as for AMT or HTTP
119
- "443:443"
120
volumes:
121
meshcentral-data:
@@ -158,9 +178,34 @@ PREINSTALL_LIBS=false
178
```
179
Then run Docker Compose:
180
```sh
161
-docker-compose --env-file .env up -d
181
+docker compose -f ./docker/compose.yaml --env-file .env up -d
182
```
183
184
+# Custom healthchecks at runtime
185
+
186
+If you want to add a custom healthcheck post-compilation/with precompiled images, then do the following:<br>
187
+This all is based on [Docker documentation](https://docs.docker.com/reference/compose-file/services/).
188
+
189
+Add the following lines to your compose.yaml:
190
+```yaml
191
+services:
192
+ meshcentral:
193
+ image: ghcr.io/ylianst/meshcentral:latest
194
+ ...
195
+ <the rest of the compose.yaml>
196
+ ...
197
+
198
+ healthcheck:
199
+ test: ["CMD", "curl", "-k", "--fail", "https://localhost:443/health.ashx"]
200
+ interval: 30s
201
+ timeout: 5s
202
+ start_period: 5s
203
+ retries: 3
204
+```
205
+
206
+And if you ever change the port on which MeshCentral *INTERNALLY* runs on please also change the healthcheck either in your compose or self-compiled Dockerfile.<br>
207
+Also relevant if you change scheme, such as HTTP to HTTPS or vice versa.
208
+
209
# MeshCentral Docker Build Process
210
211
This document explains the build process for the MeshCentral Docker image, along with details on various build arguments and how to use them.