# MeshCentral Remote Management

> Full-featured remote computer management and remote desktop solution.

- Category: Home Lab & Self-Hosting
- Difficulty: intermediate
- Components: meshcentral, mongodb, nginx
- Tags: remote-management, remote-desktop, meshcentral, it-management
- Source: https://docker.recipes/homelab/meshcentral-complete

## Overview

MeshCentral is a full-featured, open-source remote computer management solution developed by Intel's Ylian Saint-Hilaire. Originally designed for enterprise IT management, MeshCentral provides comprehensive remote desktop access, file transfer capabilities, and device management through a web-based interface. It supports Intel AMT (Active Management Technology) for out-of-band management while also offering in-band management through lightweight agents installed on target systems.

This deployment stack combines MeshCentral with MongoDB for persistent storage of device information, user accounts, and session data, while NGINX serves as a reverse proxy to handle SSL termination and load balancing. MongoDB stores all configuration data, user sessions, device certificates, and audit logs, while NGINX provides secure HTTPS access and can handle multiple concurrent connections efficiently. The architecture separates concerns effectively, with MeshCentral focusing on device management logic, MongoDB handling data persistence, and NGINX managing web traffic and security.

This configuration is ideal for IT administrators managing distributed teams, homelab enthusiasts running multiple systems, and small to medium businesses needing centralized remote management without expensive commercial solutions. The stack provides enterprise-grade features like two-factor authentication, device grouping, policy management, and comprehensive audit logging, making it valuable for organizations requiring secure remote access with detailed compliance tracking.

## Features

- Web-based remote desktop with HTML5 canvas rendering requiring no client-side plugins
- Intel AMT integration for out-of-band management and power control of compatible hardware
- Multi-platform agent support for Windows, Linux, macOS with automatic reconnection capabilities
- MongoDB-backed device certificate management and user session persistence
- NGINX SSL termination with configurable cipher suites and HTTP/2 support
- Real-time device status monitoring with MongoDB change streams for instant updates
- Built-in file transfer system with drag-and-drop functionality and transfer resumption
- Device grouping and policy inheritance with MongoDB-stored configuration templates

## Use cases

- IT support teams providing remote assistance to employees working from distributed locations
- Homelab administrators managing multiple servers, workstations, and IoT devices from a central interface
- Small business owners maintaining point-of-sale systems and office computers across multiple locations
- System administrators requiring out-of-band management for Intel vPro enabled hardware
- Educational institutions managing computer labs and student devices remotely
- Managed service providers offering remote IT support to multiple client organizations
- Development teams accessing and managing build servers and testing environments

## Prerequisites

- Minimum 2GB RAM recommended for MongoDB data storage and indexing operations
- Valid SSL certificates for NGINX or knowledge of Let's Encrypt certificate generation
- Domain name or static IP address for MESH_HOSTNAME environment variable configuration
- Ports 80 and 443 available and forwarded through firewall for external agent connections
- Understanding of MeshCentral agent deployment methods for target operating systems
- Basic familiarity with MongoDB backup procedures for device and user data protection

## docker-compose.yml

```yaml
services:
  meshcentral:
    image: ghcr.io/ylianst/meshcentral:latest
    container_name: meshcentral
    environment:
      - HOSTNAME=${MESH_HOSTNAME}
      - REVERSE_PROXY=nginx
      - REVERSE_PROXY_TLS_PORT=443
      - IFRAME=false
      - ALLOW_NEW_ACCOUNTS=true
      - WEBRTC=false
      - NODE_ENV=production
      - MONGO_URL=mongodb://mongodb:27017/meshcentral
    volumes:
      - meshcentral-data:/opt/meshcentral/meshcentral-data
      - meshcentral-files:/opt/meshcentral/meshcentral-files
    depends_on:
      - mongodb
    networks:
      - meshcentral-network
    restart: unless-stopped

  mongodb:
    image: mongo:6
    container_name: meshcentral-mongo
    volumes:
      - mongo-data:/data/db
    networks:
      - meshcentral-network
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    container_name: meshcentral-nginx
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - meshcentral
    networks:
      - meshcentral-network
    restart: unless-stopped

volumes:
  meshcentral-data:
  meshcentral-files:
  mongo-data:

networks:
  meshcentral-network:
    driver: bridge
```

## .env

```bash
# MeshCentral
MESH_HOSTNAME=mesh.example.com
```

## Usage notes

- Web UI at https://localhost
- Create admin account on first visit
- Download agents for Windows/Linux/Mac
- Supports remote desktop, file transfer
- Built-in device grouping and policies

## Troubleshooting

- MeshCentral agents showing offline status: Verify MESH_HOSTNAME matches the actual domain/IP agents use to connect and check firewall rules for ports 80/443
- MongoDB connection refused errors: Ensure MongoDB container is fully started before MeshCentral attempts connection, add health checks or increase depends_on conditions
- NGINX 502 Bad Gateway errors: Check that MeshCentral container is responding on internal port and verify nginx.conf proxy_pass directives point to correct container names
- SSL certificate errors in browser: Ensure certificate files in ./certs directory match the MESH_HOSTNAME and include proper certificate chain
- Intel AMT devices not appearing: Verify network discovery is enabled and AMT devices are on same subnet, check that Intel ME firmware is properly configured
- File transfer failures: Increase NGINX client_max_body_size directive and proxy timeout values to handle large file uploads through the reverse proxy

