MeshCentral Documentation

MeshCentral is a full computer management web site that allows you to run your own web server to remotely manage and control computers on a local network or anywhere on the internet.

Key capabilities include:

• Web-based remote desktop
• Terminal access
• File management
• Device grouping and agent deployment

Once the server is running, you create device groups, download and install the agent on target computers, and they will appear on the website for remote control.

MeshCentral includes an rdp folder containing a fork of node-rdpjs2. This fork provides support for Network Layer Authentication (NLA), which was ported from RDP-RS.

Note on Licensing: The rdp folder is licensed under GPL 3.0. If your project requirements are incompatible with GPL 3.0, you can delete the rdp folder; MeshCentral will continue to function normally, but RDP functionality will be unavailable.

To use an .env file with Docker Compose, create a .env file containing your environment variables, then run the following command:

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

You can add a runtime healthcheck to your compose.yaml to monitor the service. This example uses curl to check the /health.ashx endpoint. Note: If you change the internal port or the scheme (HTTP/HTTPS), you must update the healthcheck command accordingly.

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

You can customize the Docker image build process using several build arguments.

Available Build Arguments:

• DISABLE_MINIFY: Disable HTML/JS minification.
• DISABLE_TRANSLATE: Disable translation of strings.
• 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.

Example: Build with Minify and Translate Disabled Run this command from the root git location:

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

To ensure data persists across container restarts, you must use Docker volumes or Kubernetes PVCs. The following directories contain critical data:

• /opt/meshcentral/meshcentral-data: Most important. Contains server configurations, certificates, etc.
• /opt/meshcentral/meshcentral-backups: Backup files.
• /opt/meshcentral/meshcentral-files: User files.
• /opt/meshcentral/meshcentral-web: Custom themes (e.g., Stylish-UI).

MeshCentral provides several Docker image variants depending on your database requirements. You can target the master branch, the latest release, or a specific version (e.g., 1.1.53).

ghcr.io/ylianst/meshcentral:latest-mongodb

To contribute translations to MeshCentral, you must edit the translate.json file which contains English strings and their translations.

1. Download the Windows-based ResourceTranslator.zip tool from https://meshcentral.com/tools/ResourceTranslator.zip to open and edit the translate.json file.
2. After editing and saving the file, use the provided Node.js script to regenerate the translated web pages.
3. Submit your changes via a GitHub pull request or email the updated translate.json file to ylianst@gmail.com.

node translate.js translateall

For detailed administration and technical implementation, refer to the following resources:

• Searchable Documentation: Covers usage, server configuration, databases, TLS offloading, Let's Encrypt, IP Filtering, Email setup, embedding, server port aliasing, reverse proxy setup, multi-factor authentication, branding, HashiCorp Vault support, and SSO.
• Design and Architecture Guide: Provides information on design overview, dependencies, source code descriptions, certificates, TLS security, agent-to-server handshake, browser-to-agent relay, WebRTC, and the messenger service.
• User's Guide (PDF): Comprehensive guide for end-users.
• Installation Guide (PDF): Detailed instructions for setting up the server.

On Linux systems, you can install MeshCentral as a systemd background service using the --install flag. This creates a service file (typically in /etc/systemd/system/meshcentral.service) that manages the process, handles restarts, and sets appropriate user/group permissions.

To install:

node meshcentral.js --install

To manage the service:

• Start: node meshcentral.js --start
• Stop: node meshcentral.js --stop
• Restart: node meshcentral.js --restart
• Uninstall: node meshcentral.js --uninstall