Skip to content

Installation and Setup

Jump to bottom
Tyler Hatfield edited this page Nov 12, 2026 · 3 revisions

Installation & Setup Guide (v2.5.1)

This guide covers deploying Vitrine RMM in production as either a containerized multi-arch Docker Compose stack (linux/amd64 & linux/arm64) or a bare-metal systemd daemon on Linux.

1. System Requirements

Hardware Prerequisites

  • Architecture: x86_64 (amd64) or aarch64 (arm64 — AWS Graviton, Ampere, Apple Silicon Docker hosts, Raspberry Pi 5).
  • CPU: 2 Cores minimum (4+ Cores recommended for fleets > 500 endpoints).
  • RAM: 2 GB minimum (4 GB+ recommended).
  • Disk: 20 GB+ free SSD/NVMe storage (for SQLite WAL telemetry, session metadata, and encrypted .vrmm-backup.gz snapshots).
  • Network Ports:
    • 8080/tcp — Vitrine RMM Control Plane & SPA (designed to sit behind Nginx, Caddy, Traefik, or Cloudflare Tunnel on 443/tcp).
    • 443/tcp (or 4430/tcp) — MeshCentral 2 agent WebSocket & WebRTC relay port.

Software Prerequisites

  • Bare-Metal: Debian 12+, Ubuntu 22.04 / 24.04 LTS, Node.js 20+ (Node 22 LTS recommended), npm, git, python3, make, g++ (for native better-sqlite3 compilation).
  • Containerized: Docker Engine 24.0+ & Docker Compose v2+.

Neighboring MeshCentral Safety Guarantee: If your server already hosts a production MeshCentral 2 instance (such as /opt/meshcentral), install.sh, uninstall.sh, and the Vitrine runtime detect its systemd unit in strictly read-only mode and never modify, copy into, or delete anything under /opt/meshcentral.

2. Multi-Arch Docker Compose Deployment (Recommended — amd64 & arm64)

Official Docker Hub images (tylerhats/vitrine-rmm:latest and tylerhats/vitrine-rmm:2.5.1) include native builds for both linux/amd64 and linux/arm64:

services:
  vitrine-rmm:
    image: tylerhats/vitrine-rmm:latest
    container_name: vitrine-rmm
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
      - ./branding:/app/branding
    environment:
      - PORT=8080
      - DATA_DIR=/app/data
      - BRANDING_DIR=/app/branding
      - NODE_ENV=production
      - VITRINE_DOCKER=true
      # Optional: provide an explicit 64-hex-char (32-byte) vault master key
      # (LAPS_MASTER_SECRET is also accepted as an environment alias)
      # - VITRINE_MASTER_KEY=your_64_char_hex_key
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:8080/api/health').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 15s
    restart: unless-stopped

Launch the stack:

docker compose up -d
  • /app/data persists vitrine.db (SQLite WAL, Schema v16), .vault-key.json (0600 master AES-256-GCM key), and /app/data/backups.
  • /app/branding persists custom white-label logos (logo.png) and automatically seeds the default Vitrine logo on first boot if the mounted directory is empty.

3. Automated Bare-Metal Installation (install.sh)

git clone https://github.com/TylerHats/Vitrine-RMM.git
cd Vitrine-RMM
chmod +x install.sh
./install.sh

What install.sh Performs:

  1. Enforces set -euo pipefail and verifies Node.js >= 20 and npm.
  2. Creates ./data with hardened chmod 700 permissions so database and vault key files are restricted to the service user.
  3. Installs dependencies and compiles frontend/dist and backend/dist.
  4. Optionally installs (or cleanly restarts on upgrade) /etc/systemd/system/vitrine-rmm.service with NODE_ENV=production and VITRINE_ENABLE_GIT_SELF_PULL=true (enabling the built-in bare-metal Git self-updater & auto-rollback pipeline).

Manage the systemd daemon:

sudo systemctl status vitrine-rmm
sudo journalctl -u vitrine-rmm -f
sudo systemctl restart vitrine-rmm

4. First-Run Super Admin Bootstrap & OOBE Wizard

On a fresh database, Vitrine RMM boots with zero demo tenants, zero mock endpoints, and zero default credentials:

  1. Initial MSP Super Admin Bootstrap:
    • Navigate to http://localhost:8080/.
    • Create your primary super_admin account (minimum 10-character password, hashed via memory-hard scrypt).
    • Scan the generated RFC 6238 TOTP QR URI / Base32 Secret in your authenticator app and store your 8 single-use emergency recovery codes. Once initialized, /api/auth/setup-initial-admin permanently locks (HTTP 409).
  2. Guided Setup & Reverse Proxy Wizard:
    • Branding & Glassmorphism: Set MSP name, logo, accent color, and theme mode.
    • Domain, Reverse Proxy & TLS: Choose Nginx + Certbot, Caddy (Automatic Let's Encrypt), Traefik, or Cloudflare Tunnel, copy the auto-generated WebSocket-ready proxy configuration snippet, and run live DNS/HTTPS/TLS reachability checks (POST /api/proxy-tls/test).
    • MeshCentral 2 Federation & Enterprise OIDC SSO: Connect your primary MeshCentral 2 server and optionally configure OpenID Connect (S256 PKCE) SSO (POST /api/auth/oidc/test).
    • SMTP, PSA & Backup Key Escrow: Configure outbound TLS SMTP alerts, optional two-way ITFlow PSA sync, and escrow your Backup Encryption Recovery Key offline.
    • (Optional Evaluation Seed): If testing in a lab, Super Admins can explicitly load sample evaluation data via POST /api/demo/seed.

5. Clean Uninstallation

./uninstall.sh

Stops and removes vitrine-rmm.service, cleans build artifacts, and interactively prompts before touching ./data (never modifying /opt/meshcentral).

Clone this wiki locally