Self-Hosting m87 Server

The m87 server can be self-hosted for on-premise deployments, giving you complete control over your device management infrastructure.

Overview

m87-server handles device registration, authentication, and tunnel relay. It connects m87 runtimes on edge devices to m87 CLI users. Self-hosting allows you to:

Keep all device data within your infrastructure
Customize authentication and access control
Meet compliance requirements
Control updates and maintenance windows

Requirements

MongoDB: Version 8 or later (for device and user data storage)
Docker (recommended): For containerized deployment
TLS Certificate: For production deployments (Let’s Encrypt or custom)
Public IP/Domain: For device and client connectivity

Quick Start with Docker Compose

Clone the Repository

git clone https://github.com/make87/m87
cd m87/m87-server

Configure Environment

Create a .env file with your configuration:

cp .env.example .env

Edit the .env file with your settings (see Configuration below).

Start the Server

docker compose up -d

This will start:

m87-server (API and tunnel relay)
MongoDB (database)
Watchtower (optional auto-updates)

Verify Deployment

Check that services are running:

docker compose ps
docker compose logs -f m87-server

Configuration

The m87 server is configured via environment variables. Below are the key settings:

Core Database

string

required

MongoDB connection string used by m87-serverDefault: mongodb://mongo:27017

MONGO_URI=mongodb://mongo:27017

string

default:"m87-server"

Logical database name used by m87-server

MONGO_DB=m87-server

string

MongoDB root username (required for secured MongoDB setups)

MONGO_INITDB_ROOT_USERNAME=admin

string

MongoDB root password (required for secured MongoDB setups)

MONGO_INITDB_ROOT_PASSWORD=secure_password_here

Authentication & OAuth

string

required

OAuth/OIDC issuer URL used to validate access tokensDefault: https://auth.make87.com/

OAUTH_ISSUER=https://auth.make87.com/

For custom auth, use your Auth0 tenant or OIDC provider.

string

required

Expected OAuth audience for access tokens (must match the aud claim)Default: https://auth.make87.com

OAUTH_AUDIENCE=https://auth.make87.com

Server Networking

string

required

Public base address where this server is reachableDefault: localhost

PUBLIC_ADDRESS=m87.example.com

Used to check SNI of incoming requests for device ID prefixes.

string

default:"8084"

Port for the unified public interface (runtime connections and tunnel traffic)

UNIFIED_PORT=8084

This should be mapped to port 443 for TLS.

string

default:"8085"

Port for the REST API

REST_PORT=8085

Used for WebTransport endpoint for the web app (typically mapped to 8080).

Admin & Security

string

required

Static admin API key for privileged actions

ADMIN_KEY=your-secure-admin-key-here

Used for approving users, creating organizations, and bootstrapping admin access.

Change this from the default value in production!

string

Comma-separated list of email addresses that receive admin privileges

ADMIN_EMAILS=admin@example.com,ops@example.com

User Management

boolean

default:"false"

Whether newly registered users require manual approval

USERS_NEED_APPROVAL=false

true: User accounts start inactive until approved
false: Users are active immediately

string

Domains that are auto-approved on signup

USER_AUTO_ACCEPT_DOMAINS=make87.com,example.org

Comma-separated list (no spaces). If a user’s email domain matches, approval is skipped.

Whether devices can be shared across different organizations

ALLOW_CROSS_ORG_DEVICE_SHARING=false

true: Cross-org device sharing allowed
false: Devices are restricted to their organization

Data Retention

number

default:"30"

Number of days audit log entries are retained

AUDIT_RETENTION_DAYS=30

Older entries are automatically deleted.

number

default:"7"

Number of days deployment/report data is retained

REPORT_RETENTION_DAYS=7

Older reports are automatically deleted.

Other Settings

number

default:"1"

Whether the server runs in staging mode

STAGING=0

0: Production behavior
1: Staging mode with relaxed checks and verbose logging

string

default:"info"

Logging level

RUST_LOG=info

Options: error, warn, info, debug, trace

string

default:"/data/m87/certs/"

Path for TLS certificates

CERTIFICATE_PATH=/data/m87/certs/

Exposed Ports

The docker-compose configuration exposes:

443 → 8084 (TCP/UDP): Runtime connections and tunnel traffic (TLS)
8080 → 8085 (UDP): REST API and WebTransport endpoint

Example Configuration

Here’s a complete example .env file for production:

# Database
MONGO_URI=mongodb://admin:secure_password@mongo:27017/admin
MONGO_DB=m87-server
MONGO_INITDB_ROOT_USERNAME=admin
MONGO_INITDB_ROOT_PASSWORD=secure_password

# Auth (using make87 default auth)
OAUTH_ISSUER=https://auth.make87.com/
OAUTH_AUDIENCE=https://auth.make87.com

# Networking
PUBLIC_ADDRESS=m87.example.com
UNIFIED_PORT=8084
REST_PORT=8085

# Security
ADMIN_KEY=change-this-to-secure-random-string
ADMIN_EMAILS=admin@example.com

# User management
USERS_NEED_APPROVAL=true
USER_AUTO_ACCEPT_DOMAINS=example.com

# Device sharing
ALLOW_CROSS_ORG_DEVICE_SHARING=false

# Retention
AUDIT_RETENTION_DAYS=90
REPORT_RETENTION_DAYS=14

# Environment
STAGING=0
RUST_LOG=info

Building from Source

If you prefer to build the server binary yourself:

Install Rust

Requires Rust 1.85 or later:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Clone and Build

git clone https://github.com/make87/m87
cd m87
cargo build --release -p m87-server

Binary will be at: target/release/m87-server

Run with MongoDB

Ensure MongoDB is running, then:

export MONGO_URI=mongodb://localhost:27017
export PUBLIC_ADDRESS=localhost
./target/release/m87-server

Using Prebuilt Docker Images

Pull the latest image from GitHub Container Registry:

docker pull ghcr.io/make87/m87-server:latest

Or specify a version:

docker pull ghcr.io/make87/m87-server:v1.2.3

Auto-Updates with Watchtower

The docker-compose file includes Watchtower for automatic updates:

# Enable auto-updates profile
docker compose --profile auto-update up -d

Watchtower will:

Check for new images every 5 minutes
Automatically pull and restart with latest version
Only update containers with the watchtower.enable label

Production Deployment Checklist

Secure MongoDB

Set strong MONGO_INITDB_ROOT_PASSWORD
Restrict MongoDB port access (only to m87-server)
Enable MongoDB authentication

Configure TLS

Obtain TLS certificate (Let’s Encrypt recommended)
Configure reverse proxy (nginx, Caddy) or mount certificates
Ensure port 443 routes to UNIFIED_PORT

Set Admin Credentials

Change ADMIN_KEY from default
Configure ADMIN_EMAILS
Set USERS_NEED_APPROVAL based on your requirements

Configure Authentication

If using custom OAuth:

Set up OAuth provider (Auth0, Keycloak, etc.)
Update OAUTH_ISSUER and OAUTH_AUDIENCE
Ensure tokens include required claims

Set Public Address

Update PUBLIC_ADDRESS to your domain
Ensure DNS points to your server
Verify firewall allows ports 443 and 8080

Configure Monitoring

Set appropriate RUST_LOG level
Set up log aggregation
Monitor container health

Backup Strategy

Configure MongoDB backups
Backup certificate files
Store .env configuration securely

Client Configuration

After deploying your server, configure clients to use it:

# Set the server URL (if using custom server)
export M87_SERVER_URL=https://m87.example.com

# Login
m87 login

Clients will need to authenticate against your OAuth provider.

Troubleshooting

Server not starting

Check logs:

docker compose logs -f m87-server

Common issues:

MongoDB connection failed (check MONGO_URI)
Invalid OAuth configuration
Port already in use

Devices can't connect

Verify:

PUBLIC_ADDRESS is correct and DNS resolves
Port 443 is accessible from internet
TLS certificate is valid
Firewall allows incoming connections

Authentication errors

Check:

OAUTH_ISSUER and OAUTH_AUDIENCE match your provider
OAuth provider is reachable
Tokens include required claims
Admin key is correct

Database connection issues

Verify MongoDB is running: docker compose ps mongo
Check MongoDB logs: docker compose logs mongo
Ensure credentials in .env match MongoDB config

Updating

Manual Update

# Pull latest image
docker compose pull

# Restart services
docker compose up -d

With Watchtower (Automatic)

If running with the auto-update profile, Watchtower handles updates automatically.

License

The m87 server is licensed under AGPL-3.0-or-later.

Support

For issues and questions:

Get Started

Core Concepts

CLI Commands

Guides

Advanced

Self-Hosting m87 Server

Overview

Requirements

Quick Start with Docker Compose

Configuration

Core Database

Authentication & OAuth

Server Networking

Admin & Security

User Management

Data Retention

Other Settings

Exposed Ports

Example Configuration

Building from Source

Using Prebuilt Docker Images

Auto-Updates with Watchtower

Production Deployment Checklist

Client Configuration

Troubleshooting

Updating

Manual Update

With Watchtower (Automatic)

License

Support

​Overview

​Requirements

​Quick Start with Docker Compose

​Configuration

​Core Database

​Authentication & OAuth

​Server Networking

​Admin & Security

​User Management

​Device Sharing

​Data Retention

​Other Settings

​Exposed Ports

​Example Configuration

​Building from Source

​Using Prebuilt Docker Images

​Auto-Updates with Watchtower

​Production Deployment Checklist

​Client Configuration

​Troubleshooting

​Updating

​Manual Update

​With Watchtower (Automatic)

​License

​Support

Overview

Requirements

Quick Start with Docker Compose

Configuration

Core Database

Authentication & OAuth

Server Networking

Admin & Security

User Management

Device Sharing

Data Retention

Other Settings

Exposed Ports

Example Configuration

Building from Source

Using Prebuilt Docker Images

Auto-Updates with Watchtower

Production Deployment Checklist

Client Configuration

Troubleshooting

Updating

Manual Update

With Watchtower (Automatic)

License

Support