@cryptotaxi247 / MeshCentral
Code Commits Issues Pulls Sessions CI/CD
master
master
md 251 lines 9.79 KB
Rendered Raw
1 # MeshCentral Docker Configuration Guide
2
3 > [!NOTE]
4 > Out of precaution, DYNAMIC_CONFIG has been disabled by default.<br>
5 > The reason why is because when its enabled and a working config without corresponding environment variables gives,<br>
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.<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 ## Persistency
31
32 The Docker image has since recently removed its default creation of volumes. It might not be what you want.<br>
33 If you still want to use volumes to make data persist across containers use Docker volumes (or Kubernetes PVCs).<br>
34 For examples of how to use these volumes, see the examples below. Most data resides inside:
35
36 - /opt/meshcentral/meshcentral-backups
37 - /opt/meshcentral/meshcentral-data (most important! Server configurations, certificates, etc... reside here.)
38 - /opt/meshcentral/meshcentral-files
39 - /opt/meshcentral/meshcentral-web (relevant if you use a custom theme, such as [Stylish-UI](https://github.com/melo-professional/Meshcentral-Stylish-UI))
40
41 ## Environment Variables
42 Below is a breakdown of environment variables used in this setup.
43
44 ### General MeshCentral Configuration
45 | Variable | Default Value | Description |
46 |----------|--------------|-------------|
47 | NODE_ENV | production | Specifies the Node.js environment. |
48 | CONFIG_FILE | /opt/meshcentral/meshcentral-data/config.json | Path to the configuration file. |
49 | DYNAMIC_CONFIG | false | Enables/disables dynamic configuration. This means config is being rechecked every container restart. False if you want to use your own `config.json` |
50 | ALLOW_PLUGINS | false | Enables/disables plugins. |
51 | ALLOW_NEW_ACCOUNTS | false | Enables/disables new account creation. |
52 | ALLOWED_ORIGIN | false | Enables/disables allowed origin policy. |
53 | ARGS | "" | Additional arguments for MeshCentral. |
54 | HOSTNAME | localhost | Specifies the hostname. |
55 | PORT | 443 | Specifies the port. |
56 | REDIR_PORT | 80 | Specifies the redirection port. |
57 | IFRAME | false | Enables/disables embedding in an iframe. |
58 | LOCAL_SESSION_RECORDING | true | Enables session recording. |
59 | MINIFY | true | Minifies the JavaScript and HTML output. |
60 | REGEN_SESSIONKEY | false | Regenerates the session key on each restart of the container. |
61 | REVERSE_PROXY | "" | Configures reverse proxy support through `certUrl`. |
62 | REVERSE_PROXY_TLS_PORT | "443" | Configures reverse proxy TLS port, will be combined with: `REVERSE_PROXY`. |
63 | WEBRTC | false | Enables/disables WebRTC support. |
64 | TRUSTED_PROXY | "" | Trust forwarded headers from these IPs or domains. |
65 | TLS_OFFLOAD | false | When set to true, indicate that TLS is being performed by a device in front of MeshCentral. |
66
67 ### Database Configuration
68
69 #### MeshCentral Database Settings
70 | Variable | Default Value | Description |
71 |----------|--------------|-------------|
72 | USE_MONGODB | false | Enables MongoDB usage. |
73 | USE_POSTGRESQL | false | Enables PostgreSQL usage. |
74 | USE_MARIADB | false | Enables MariaDB usage. |
75
76 #### MongoDB Configuration
77 | Variable | Default Value | Description |
78 |----------|--------------|-------------|
79 | MONGO_HOST | "" | MongoDB server hostname. |
80 | MONGO_PORT | 27017 | MongoDB server port. |
81 | MONGO_USERNAME | "" | MongoDB username. |
82 | MONGO_PASS | "" | MongoDB password. |
83 | MONGO_URL | "" | Overrides other MongoDB connection settings. |
84
85 #### PostgreSQL Configuration
86 | Variable | Default Value | Description |
87 |----------|--------------|-------------|
88 | PSQL_HOST | "" | PostgreSQL server hostname. |
89 | PSQL_PORT | 5432 | PostgreSQL server port. |
90 | PSQL_USER | "" | PostgreSQL username. |
91 | PSQL_PASS | "" | PostgreSQL password. |
92 | PSQL_DATABASE | "" | PostgreSQL database name. |
93
94 #### MariaDB Configuration
95 | Variable | Default Value | Description |
96 |----------|--------------|-------------|
97 | MARIADB_HOST | "" | MariaDB server hostname. |
98 | MARIADB_PORT | 3306 | MariaDB server port. |
99 | MARIADB_USER | "" | MariaDB username. |
100 | MARIADB_PASS | "" | MariaDB password. |
101 | MARIADB_DATABASE | "" | MariaDB database name. |
102
103 ## Deployment Instructions
104
105 ### Running with Docker CLI
106 ```sh
107 docker run -d \
108 -e HOSTNAME=myserver.domain.com \
109 -e ALLOW_NEW_ACCOUNTS=true \
110 -e USE_MONGODB=true \
111 -e MONGO_URL=mongodb://username:password@mongodb:27017/meshcentral \
112 -v meshcentral-data:/opt/meshcentral/meshcentral-data \
113 -p 443:443 \
114 ghcr.io/ylianst/meshcentral:latest # or latest-mongodb
115 ```
116
117 ### Running with Docker Compose
118 ```yaml
119 services:
120 meshcentral:
121 image: ghcr.io/ylianst/meshcentral:latest
122 environment:
123 - HOSTNAME=myserver.domain.com
124 - ALLOW_NEW_ACCOUNTS=false
125 - USE_MONGODB=true
126 - MONGO_URL=mongodb://username:password@mongodb:27017/meshcentral
127 volumes:
128 - meshcentral-data:/opt/meshcentral/meshcentral-data
129 - meshcentral-files:/opt/meshcentral/meshcentral-files
130 - meshcentral-web:/opt/meshcentral/meshcentral-web
131 - meshcentral-backups:/opt/meshcentral/meshcentral-backups
132 ports:
133 # You can add additional ports here in the same format. Such as for AMT or HTTP
134 - "443:443"
135 volumes:
136 meshcentral-data:
137 meshcentral-files:
138 meshcentral-web:
139 meshcentral-backups:
140 ```
141
142 ### Using an `.env` File
143 Create a `.env` file:
144 ```ini
145 # Environment variables
146 NODE_ENV=production
147 CONFIG_FILE=/opt/meshcentral/meshcentral-data/config.json
148 DYNAMIC_CONFIG=true
149
150 # MeshCentral Configuration
151 ALLOW_PLUGINS=false
152 ALLOW_NEW_ACCOUNTS=false
153 ALLOWED_ORIGIN=false
154 ARGS=
155 HOSTNAME=localhost
156 PORT=443
157 REDIR_PORT=80
158 IFRAME=false
159 LOCAL_SESSION_RECORDING=true
160 MINIFY=true
161 REGEN_SESSIONKEY=false
162 REVERSE_PROXY=
163 REVERSE_PROXY_TLS_PORT=
164 WEBRTC=false
165
166 # MongoDB Configuration
167 USE_MONGODB=false
168 MONGO_HOST=
169 MONGO_PORT=27017
170 MONGO_USERNAME=
171 MONGO_PASS=
172 MONGO_URL=
173
174 # PostgreSQL Configuration
175 USE_POSTGRESQL=false
176 PSQL_HOST=
177 PSQL_PORT=5432
178 PSQL_USER=
179 PSQL_PASS=
180 PSQL_DATABASE=
181
182 # MariaDB/MySQL Configuration
183 USE_MARIADB=false
184 MARIADB_HOST=
185 MARIADB_PORT=3306
186 MARIADB_USER=
187 MARIADB_PASS=
188 MARIADB_DATABASE=
189
190 # Build options
191 INCLUDE_MONGODB_TOOLS=false
192 INCLUDE_POSTGRESQL_TOOLS=false
193 INCLUDE_MARIADB_TOOLS=false
194 PREINSTALL_LIBS=false
195 ```
196 Then run Docker Compose:
197 ```sh
198 docker compose -f ./docker/compose.yaml --env-file .env up -d
199 ```
200
201 # Custom healthchecks at runtime
202
203 If you want to add a custom healthcheck post-compilation/with precompiled images, then do the following:<br>
204 This all is based on [Docker documentation](https://docs.docker.com/reference/compose-file/services/).
205
206 Add the following lines to your compose.yaml:
207 ```yaml
208 services:
209 meshcentral:
210 image: ghcr.io/ylianst/meshcentral:latest
211 ...
212 <the rest of the compose.yaml>
213 ...
214
215 healthcheck:
216 test: ["CMD", "curl", "-k", "--fail", "https://localhost:443/health.ashx"]
217 interval: 30s
218 timeout: 5s
219 start_period: 5s
220 retries: 3
221 ```
222
223 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>
224 Also relevant if you change scheme, such as HTTP to HTTPS or vice versa.
225
226 # MeshCentral Docker Build Process
227
228 This document explains the build process for the MeshCentral Docker image, along with details on various build arguments and how to use them.
229
230 ## Build Arguments
231
232 The following build arguments are available for customizing the build process:
233
234 - **DISABLE_MINIFY**: Disable HTML/JS minification during the build.
235 - **DISABLE_TRANSLATE**: Disable translation of strings in MeshCentral.
236 - **INCLUDE_MONGODB_TOOLS**: Include MongoDB client and related tools.
237 - **INCLUDE_POSTGRESQL_TOOLS**: Include PostgreSQL client tools.
238 - **INCLUDE_MARIADB_TOOLS**: Include MariaDB/MySQL client tools.
239 - **PREINSTALL_LIBS**: Pre-install specific libraries like `ssh2`, `nodemailer`, etc.
240
241 ### Build Commands with Arguments
242
243 Here are the shell commands to build the Docker image with different configurations.
244
245 #### 1. Build with Minify and Translate Disabled
246 If you want to disable both HTML/JS minification and translation during the build process, use the following command:
247 > While in the root git location.
248
249 ```sh
250 docker build -f docker/Dockerfile --build-arg DISABLE_MINIFY=no --build-arg DISABLE_TRANSLATE=no -t meshcentral .
251 ```