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.

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:<tag>

Running with Docker Compose

services:
  meshcentral:
    image: ghcr.io/ylianst/meshcentral:<tag>
    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:
      - "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 --env-file .env up -d

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 .

README.md

MeshCentral Docker Configuration Guide