MeshCentral/docker

MeshCentral Docker Configuration Guide

Note

Out of precaution, DYNAMIC_CONFIG has been disabled by default.
The reason why is because when its enabled and a working config without corresponding environment variables gives,
Then the container will overwrite it to a incorrect, but working state - perhaps non-working for your environment.

Overview

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.

MeshCentral provides a couple different Docker container variants:
These variants are pulled through 3 main channels: master and latest.
If you want to target versions, you can also target individual versions; such as 1.1.53.

Variant	Image tag	Full path
All database backends	"" (empty)	ghcr.io/ylianst/meshcentral:<version>
No database backens (local only)	slim	ghcr.io/ylianst/meshcentral:<version>-slim
MongoDB backend included	mongodb	ghcr.io/ylianst/meshcentral:<version>-mongodb
PostgreSQL backend included	postgresql	ghcr.io/ylianst/meshcentral:<version>-postgresql
Mysql/MariaDB backend(s) included	mysql	ghcr.io/ylianst/meshcentral:<version>-mysql

So for a quick example: if you want to get the bleeding edge code with a PostgreSQL backend: ghcr.io/ylianst/meshcentral:master-postgresql
So for another quick example: if you want to get a complete image at the latest released version: ghcr.io/ylianst/meshcentral:latest
So for another quick example: if you want to get a released version with a MongoDB backend: ghcr.io/ylianst/meshcentral:latest-mongodb
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
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

Environment Variables

Below is a breakdown of environment variables used in this setup.

General MeshCentral Configuration

Variable	Default Value	Description
NODE_ENV	production	Specifies the Node.js environment.
CONFIG_FILE	/opt/meshcentral/meshcentral-data/config.json	Path to the configuration file.
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
ALLOW_PLUGINS	false	Enables/disables plugins.
ALLOW_NEW_ACCOUNTS	false	Enables/disables new account creation.
ALLOWED_ORIGIN	false	Enables/disables allowed origin policy.
ARGS	""	Additional arguments for MeshCentral.
HOSTNAME	localhost	Specifies the hostname.
IFRAME	false	Enables/disables embedding in an iframe.
LOCAL_SESSION_RECORDING	true	Enables session recording.
MINIFY	true	Minifies the JavaScript and HTML output.
REGEN_SESSIONKEY	false	Regenerates the session key on each restart of the container.
REVERSE_PROXY	""	Configures reverse proxy support through certUrl.
REVERSE_PROXY_TLS_PORT	"443"	Configures reverse proxy TLS port, will be combined with: REVERSE_PROXY.
WEBRTC	false	Enables/disables WebRTC support.

Database Configuration

MeshCentral Database Settings

Variable	Default Value	Description
USE_MONGODB	false	Enables MongoDB usage.
USE_POSTGRESQL	false	Enables PostgreSQL usage.
USE_MARIADB	false	Enables MariaDB usage.

MongoDB Configuration

Variable	Default Value	Description
MONGO_HOST	""	MongoDB server hostname.
MONGO_PORT	27017	MongoDB server port.
MONGO_USERNAME	""	MongoDB username.
MONGO_PASS	""	MongoDB password.
MONGO_URL	""	Overrides other MongoDB connection settings.

PostgreSQL Configuration

Variable	Default Value	Description
PSQL_HOST	""	PostgreSQL server hostname.
PSQL_PORT	5432	PostgreSQL server port.
PSQL_USER	""	PostgreSQL username.
PSQL_PASS	""	PostgreSQL password.
PSQL_DATABASE	""	PostgreSQL database name.

MariaDB Configuration

Variable	Default Value	Description
MARIADB_HOST	""	MariaDB server hostname.
MARIADB_PORT	3306	MariaDB server port.
MARIADB_USER	""	MariaDB username.
MARIADB_PASS	""	MariaDB password.
MARIADB_DATABASE	""	MariaDB database name.

Deployment Instructions

Running with Docker CLI

docker run -d \
  -e HOSTNAME=myserver.domain.com \
  -e ALLOW_NEW_ACCOUNTS=true \
  -e USE_MONGODB=true \
  -e MONGO_URL=mongodb://username:password@mongodb:27017/meshcentral \
  -v meshcentral-data:/opt/meshcentral/meshcentral-data \
  -p 443:443 \
  ghcr.io/ylianst/meshcentral:latest # or latest-mongodb

Running with Docker Compose

services:
  meshcentral:
    image: ghcr.io/ylianst/meshcentral:latest
    environment:
      - HOSTNAME=myserver.domain.com
      - ALLOW_NEW_ACCOUNTS=false
      - USE_MONGODB=true
      - MONGO_URL=mongodb://username:password@mongodb:27017/meshcentral
    volumes:
      - meshcentral-data:/opt/meshcentral/meshcentral-data
      - meshcentral-files:/opt/meshcentral/meshcentral-files
      - meshcentral-web:/opt/meshcentral/meshcentral-web
      - meshcentral-backups:/opt/meshcentral/meshcentral-backups
    ports:
    # You can add additional ports here in the same format. Such as for AMT or HTTP
      - "443:443"
volumes:
  meshcentral-data:
  meshcentral-files:
  meshcentral-web:
  meshcentral-backups:

Using an .env File

Create a .env file:

# Environment variables
NODE_ENV=production
CONFIG_FILE=/opt/meshcentral/meshcentral-data/config.json
DYNAMIC_CONFIG=true

# MeshCentral Configuration
ALLOW_PLUGINS=false
ALLOW_NEW_ACCOUNTS=false
ALLOWED_ORIGIN=false
ARGS=
HOSTNAME=localhost
IFRAME=false
LOCAL_SESSION_RECORDING=true
MINIFY=true
REGEN_SESSIONKEY=false
REVERSE_PROXY=
REVERSE_PROXY_TLS_PORT=
WEBRTC=false

# MongoDB Configuration
USE_MONGODB=false
MONGO_HOST=
MONGO_PORT=27017
MONGO_USERNAME=
MONGO_PASS=
MONGO_URL=

# PostgreSQL Configuration
USE_POSTGRESQL=false
PSQL_HOST=
PSQL_PORT=5432
PSQL_USER=
PSQL_PASS=
PSQL_DATABASE=

# MariaDB/MySQL Configuration
USE_MARIADB=false
MARIADB_HOST=
MARIADB_PORT=3306
MARIADB_USER=
MARIADB_PASS=
MARIADB_DATABASE=

# Build options
INCLUDE_MONGODB_TOOLS=false
INCLUDE_POSTGRESQL_TOOLS=false
INCLUDE_MARIADB_TOOLS=false
PREINSTALL_LIBS=false

Then run Docker Compose:

docker compose -f ./docker/compose.yaml --env-file .env up -d

Custom healthchecks at runtime

If you want to add a custom healthcheck post-compilation/with precompiled images, then do the following:
This all is based on Docker documentation.

Add the following lines to your compose.yaml:

services:
  meshcentral:
    image: ghcr.io/ylianst/meshcentral:latest
    ...
    <the rest of the compose.yaml>
    ...
    
    healthcheck:
      test: ["CMD", "curl", "-k", "--fail", "https://localhost:443/health.ashx"]
      interval: 30s
      timeout: 5s
      start_period: 5s
      retries: 3

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.
Also relevant if you change scheme, such as HTTP to HTTPS or vice versa.

MeshCentral Docker Build Process

This document explains the build process for the MeshCentral Docker image, along with details on various build arguments and how to use them.

Build Arguments

The following build arguments are available for customizing the build process:

• DISABLE_MINIFY: Disable HTML/JS minification during the build.
• DISABLE_TRANSLATE: Disable translation of strings in MeshCentral.
• INCLUDE_MONGODB_TOOLS: Include MongoDB client and related tools.
• INCLUDE_POSTGRESQL_TOOLS: Include PostgreSQL client tools.
• INCLUDE_MARIADB_TOOLS: Include MariaDB/MySQL client tools.
• PREINSTALL_LIBS: Pre-install specific libraries like ssh2, nodemailer, etc.

Build Commands with Arguments

Here are the shell commands to build the Docker image with different configurations.

1. Build with Minify and Translate Disabled

If you want to disable both HTML/JS minification and translation during the build process, use the following command:

While in the root git location.

docker build -f docker/Dockerfile --build-arg DISABLE_MINIFY=no --build-arg DISABLE_TRANSLATE=no -t meshcentral .