Self-Hosted Docker Installation Guide

Overview

ManageLM is published as managelm/portal on Docker Hub with two variants:

ManageLM Only (Recommended)

The ManageLM Only image (managelm/portal:latest) contains only the ManageLM application. You provide your own PostgreSQL and Redis instances — either as separate Docker containers (included in the default compose file) or as external/managed services. This gives you full control over database configuration, backups, scaling, and upgrades independently of the portal.

All-in-One (with DB)

The All-in-One (with DB) image (managelm/portal:allinone) bundles the portal, PostgreSQL, and Redis into a single container. It is the fastest way to try ManageLM — one container, no external dependencies — but it is not recommended for production because database and cache lifecycle are tied to the container, making independent scaling, backups, and upgrades harder.

Requirements

• Docker Engine 20+ or Docker Desktop
• 2 GB RAM minimum
• 1 GB RAM minimum (+ PostgreSQL 16+ and Redis 7+)
• Two HTTPS endpoints:
  • Portal URL (SERVER_URL, e.g. https://managelm.example.com) — admin UI + agent WebSocket. Can be internal-only. The certificate just needs to be trusted by every agent host: a public CA (Let's Encrypt etc.) works without setup; a private/internal CA works too if you distribute its root cert to the agents' system trust store before enrolling them. See Internal Portal URL.
  • MCP public URL (PUBLIC_URL, e.g. https://mcp.example.com) — required for Claude.ai Custom Connector. Must be a dedicated subdomain on a public DNS record, reachable from the internet, with a certificate from a public CA (Anthropic's servers won't accept a private CA). See MCP Public URL.

Quick Start

docker run -d \
  --name managelm \
  -p 3000:3000 \
  -e SERVER_URL=http://localhost:3000 \
  -e [email protected] \
  -v managelm_pgdata:/data/postgres \
  -v managelm_redisdata:/data/redis \
  --restart unless-stopped \
  managelm/portal:allinone

# PostgreSQL
docker run -d --name managelm-db \
  -e POSTGRES_DB=managelm \
  -e POSTGRES_USER=managelm \
  -e POSTGRES_PASSWORD=your-db-password \
  -v managelm_pgdata:/var/lib/postgresql/data \
  --restart unless-stopped \
  postgres:16-alpine

# Redis
docker run -d --name managelm-redis \
  -v managelm_redisdata:/data \
  --restart unless-stopped \
  redis:7-alpine redis-server --appendonly yes

# Portal
docker run -d --name managelm \
  -p 3000:3000 \
  -e SERVER_URL=http://localhost:3000 \
  -e [email protected] \
  -e DATABASE_URL=postgresql://managelm:your-db-password@managelm-db:5432/managelm \
  -e REDIS_URL=redis://managelm-redis:6379 \
  --link managelm-db --link managelm-redis \
  --restart unless-stopped \
  managelm/portal:latest

External Database Setup

When using your own PostgreSQL or Redis instead of the containers from the compose file, follow these steps to prepare them before starting the portal.

PostgreSQL

ManageLM requires PostgreSQL 15+ (16 recommended). The portal runs migrations automatically on startup and needs full control over its schema.

1. Create the database and user

   # Connect as a PostgreSQL superuser (e.g. postgres)
   sudo -u postgres psql
   
   -- Create the ManageLM user
   CREATE USER managelm WITH PASSWORD 'your-strong-password';
   
   -- Create the database owned by that user
   CREATE DATABASE managelm OWNER managelm;
   
   -- Connect to the new database
   \c managelm
   
   -- Grant full schema permissions (required for migrations)
   GRANT ALL ON SCHEMA public TO managelm;
   
   -- If on PostgreSQL 15+, also grant CREATE (changed default in PG15)
   ALTER DEFAULT PRIVILEGES IN SCHEMA public
     GRANT ALL ON TABLES TO managelm;
   ALTER DEFAULT PRIVILEGES IN SCHEMA public
     GRANT ALL ON SEQUENCES TO managelm;
   
   \q

2. Allow remote connections (if PostgreSQL is on a different host)

   # In postgresql.conf — listen on all interfaces
   listen_addresses = '*'
   
   # In pg_hba.conf — allow the portal host (replace with your subnet)
   host  managelm  managelm  10.0.0.0/8  scram-sha-256

   Restart PostgreSQL after editing: systemctl restart postgresql

3. Set DATABASE_URL in your docker-compose.yml

   DATABASE_URL=postgresql://managelm:your-strong-password@db-host:5432/managelm

4. Test the connection (from the portal host)

   psql "postgresql://managelm:your-strong-password@db-host:5432/managelm" -c "SELECT 1;"

Redis

ManageLM requires Redis 7+ (or Valkey). It is used for real-time agent communication, session state, and pub/sub — it must be available at all times.

1. Enable persistence (recommended)

   # In redis.conf
   appendonly yes
   appendfsync everysec

2. Set REDIS_URL in your docker-compose.yml

   # Without authentication
   REDIS_URL=redis://redis-host:6379
   
   # With authentication (Redis 6+ ACL)
   REDIS_URL=redis://username:password@redis-host:6379

3. Test the connection

   redis-cli -h redis-host ping
   # Expected: PONG

Remove compose services

When using external databases, remove the postgres and redis services, their volumes, and the depends_on block from your docker-compose.yml. A minimal compose file looks like:

services:
  portal:
    image: managelm/portal:latest
    ports:
      - "3000:3000"
    environment:
      - SERVER_URL=http://localhost:3000
      - [email protected]
      - DATABASE_URL=postgresql://user:pass@db-host:5432/managelm
      - REDIS_URL=redis://redis-host:6379
    restart: unless-stopped

First Steps After Install

Once the portal is running:

1. Front the portal with TLS — reverse proxy at SERVER_URL (nginx, Apache, or Traefik). Required before agents can enroll.
2. Set up the MCP public URL — dedicated subdomain (e.g. mcp.example.com) reverse-proxied to portal /public/. Required for Claude.ai Custom Connector.
3. Register your account at your SERVER_URL.
4. Configure the LLM — Local (Ollama), Cloud, or Proxied access mode.
5. Import skills from the built-in catalog.
6. Install an agent on your first server.
7. Connect Claude via MCP.

Internal Portal URL

Place a reverse proxy in front of the portal for TLS. This fronts SERVER_URL — admin UI, agent WebSocket, OAuth login/consent. The separate public-facing MCP endpoint is covered in MCP Public URL below.

WebSocket support is required for agent connections.

nginx

server {
    listen 443 ssl http2;
    server_name managelm.example.com;

    ssl_certificate     /etc/ssl/certs/managelm.pem;
    ssl_certificate_key /etc/ssl/private/managelm.key;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }
}

Apache

<VirtualHost *:443>
    ServerName managelm.example.com

    SSLEngine on
    SSLCertificateFile    /etc/ssl/certs/managelm.pem
    SSLCertificateKeyFile /etc/ssl/private/managelm.key

    ProxyPreserveHost On
    ProxyPass        / http://127.0.0.1:3000/
    ProxyPassReverse / http://127.0.0.1:3000/

    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} =websocket [NC]
    RewriteRule /(.*) ws://127.0.0.1:3000/$1 [P,L]

    ProxyTimeout 86400
</VirtualHost>

Traefik

Traefik discovers the portal from Docker labels — no separate config file. WebSocket upgrades are handled transparently. Add these labels to the portal service in your docker-compose.yml:

    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.managelm.rule=Host(`managelm.example.com`)"
      - "traefik.http.routers.managelm.entrypoints=websecure"
      - "traefik.http.routers.managelm.tls.certresolver=letsencrypt"
      - "traefik.http.services.managelm.loadbalancer.server.port=3000"

Replace letsencrypt with the cert resolver name on your Traefik instance, and remove the ports: mapping from the portal service — with Traefik, the portal is only reached through the proxy. If you don't have Traefik running yet, see the Traefik quick-start for setting up an instance with cert resolvers.

MCP Public URL

Claude.ai's Custom Connector flow runs OAuth and every MCP tool call from Anthropic's backend, so the MCP endpoint has to be reachable from the public internet. ManageLM exposes a small curated /public/ surface on the portal — OAuth discovery, token exchange, MCP, the connector logo, and (when you opt-in per-agent) the agent bootstrap + WebSocket so agents outside your network can enroll. Everything else (admin UI, agent UI, login, internal APIs) stays on SERVER_URL and is not reachable from the public hostname.

You point Claude (and any external agents) at a dedicated public subdomain that reverse-proxies to http://<portal>:3000/public/. Single rule, allowlist enforced by the portal.

Requirements

• Dedicated subdomain — e.g. mcp.example.com. Don't share with the portal or other services; the well-known OAuth discovery URL must sit at the root of this hostname.
• Public DNS — the name must resolve from outside your network (Anthropic's backend fetches it).
• Trusted public CA — Let's Encrypt or commercial. Private CAs are rejected by Anthropic's servers.
• Port 443 open from the internet to your reverse proxy.

Set PUBLIC_URL

In your docker-compose.yml (or as a -e on docker run):

PUBLIC_URL=https://mcp.example.com

The portal advertises this URL in OAuth metadata and shows it in Settings → Claude Connectors as the URL users paste into Claude.

nginx

server {
    listen 443 ssl http2;
    server_name mcp.example.com;

    ssl_certificate     /etc/letsencrypt/live/mcp.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000/public/;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host  $host;
    }
}

Apache

<VirtualHost *:443>
    ServerName mcp.example.com

    SSLEngine on
    SSLCertificateFile    /etc/letsencrypt/live/mcp.example.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/mcp.example.com/privkey.pem

    ProxyPreserveHost On
    ProxyPass        /  http://127.0.0.1:3000/public/
    ProxyPassReverse /  http://127.0.0.1:3000/public/
</VirtualHost>

Verify

# OAuth discovery — must return JSON metadata
curl -s https://mcp.example.com/.well-known/oauth-authorization-server | head

# MCP endpoint — must return 401 with WWW-Authenticate
curl -i -X POST https://mcp.example.com/mcp -H 'Content-Type: application/json' -d '{}'

# Anything outside the allowlist — must return 404
curl -i https://mcp.example.com/api/auth/me

External agents

The same /public/ surface also serves the agent bootstrap and WebSocket, so agents that can't reach SERVER_URL (remote hosts, customer servers, anything outside your VPN) can enroll and connect via the public hostname instead.

In Agents → Add Agent (or Agent detail → Reinstall), flip the Use Public URL switch before copying the install command. The toggle is only shown when PUBLIC_URL is configured. With it on, the generated curl/wget/iex command points at mcp.example.com and the agent's config.yaml stores that URL as its server_url — the agent uses it for bundle download, enrollment polling, updates, and the runtime WebSocket. With it off, the install uses SERVER_URL (the original behaviour).

The choice is per-install: re-enrolling an existing agent re-prompts, so an agent that was originally internal can move to public (or vice versa) without portal-side surgery.

Threat-alert actions

When PUBLIC_URL is set, the one-click buttons in threat-alert emails (Kill Service / Kill Session / Discard Alert) are served via the public hostname too, so an admin can act on an alert from anywhere — no VPN needed. The authorization is the single-use signed token in the link, not a portal session, and the confirmation page is fully self-contained. No extra proxy rule is required — the existing / → /public/ rule already covers it. The “Open the alert in the portal” link in the same email still points at SERVER_URL, since it loads the admin UI and stays internal.

SMTP / Email

The portal sends emails for account verification, password resets, and team invitations. When SMTP_HOST is not set, email sending is disabled entirely — no connection attempts are made.

To enable emails, configure an SMTP relay (Brevo, Mailgun, SendGrid, etc.):

SMTP_HOST=smtp.brevo.com
SMTP_PORT=587
SMTP_SECURE=starttls
SMTP_USER=your-username
SMTP_PASS=your-password

Environment Variables

Required

Strongly recommended

The all-in-one image auto-generates an ENCRYPTION_KEY on first run and persists it to /data/encryption.key. You only need to set it explicitly if you want to manage the key yourself (e.g. to restore a backup on a new host).

Set this before adding cloud connectors, configuring an LLM API key, enrolling agents, or generating a PKI CA — the portal starts without it (warning only), but any feature that encrypts data at rest will fail until it's configured. Rotating the key invalidates existing encrypted rows, so set it once and keep it.

Database & Redis

The all-in-one image auto-configures these to the embedded services. Override only if you want to point at an external PostgreSQL or Redis.

The shipped compose file sets these to the bundled postgres and redis services. Override to use external instances.

SMTP & DKIM

Optional

Advanced

Updating

docker compose pull
docker compose up -d

Migrations run automatically on startup. Back up first for major updates.

Backup & Restore

# Backup
docker compose stop
docker run --rm \
  -v managelm_pgdata:/data/postgres:ro \
  -v managelm_redisdata:/data/redis:ro \
  -v $(pwd):/backup \
  alpine tar czf /backup/managelm-backup-$(date +%F).tar.gz -C / data
docker compose start

# Restore
docker compose down
docker run --rm \
  -v managelm_pgdata:/data/postgres \
  -v managelm_redisdata:/data/redis \
  -v $(pwd):/backup \
  alpine tar xzf /backup/managelm-backup-YYYY-MM-DD.tar.gz -C /
docker compose up -d

# Backup PostgreSQL (run regularly)
docker compose exec postgres pg_dump -U managelm managelm > backup-$(date +%F).sql

# Restore PostgreSQL
docker compose exec -T postgres psql -U managelm managelm < backup-YYYY-MM-DD.sql

# Optional — Redis snapshot (in-flight session state)
docker compose exec redis redis-cli BGSAVE
docker cp $(docker compose ps -q redis):/data/dump.rdb ./redis-$(date +%F).rdb

Monitoring

# Health check
curl -s http://localhost:3000/health

# Logs
docker compose logs -f portal

# Last 100 lines
docker compose logs --tail 100 portal

Troubleshooting

Portal won't start

Agents can't connect

Database permission errors

Email not sending