Self-Hosted Installation Guide

Prerequisites

1. Extract and load

tar xzf maildesk-selfhosted.tar.gz
cd maildesk

docker load < maildesk-images.tar.gz

2. Configure environment

./setup.sh

Run ./setup.sh to auto-generate all secrets. Then edit .env to set your APP_URL and license key.

Open .env and set the following values:

Required variables

Auto-generated by setup.sh

These are generated automatically when you run setup.sh. Do not change unless migrating data.

Optional variables

Example .env for self-hosted

# Only these 2 lines need manual editing after running ./setup.sh:
APP_URL=https://tickets.example.com
MAILDESK_LICENSE_KEY=eyJhbGciOiJFZERTQSIs...your-key-here

# Everything else is auto-generated by ./setup.sh

3. Start

docker compose up -d

This starts 6 services:

The migrate service runs automatically before app and worker start. It creates all tables idempotently — safe to run on both fresh and existing databases.

4. Verify the deployment

# Check all services are healthy
docker compose ps

# Check app logs
docker compose logs app

# Check worker logs
docker compose logs worker

# Health check endpoint
curl http://localhost:3000/api/health

Once healthy, open your APP_URL in a browser. You should see the login/registration page.

5. Initial setup

1. 1Register the first admin account at your-domain.com/register
2. 2Create an organization — this is your workspace
3. 3Add a mailbox under Settings > Mailboxes (IMAP/SMTP credentials)
4. 4Incoming emails will automatically create tickets

Email Verification (Optional)

Configure SMTP to enable email verification for new users. Without SMTP, new users are auto-verified and can log in immediately.

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=you@gmail.com
SMTP_PASS=your-app-password
SMTP_FROM=MailDesk <noreply@yourdomain.com>

Reverse Proxy Setup

MailDesk requires a reverse proxy for TLS termination. Here are examples for common setups:

tickets.example.com {
    handle /ws* {
        reverse_proxy localhost:3002
    }
    handle {
        reverse_proxy localhost:3000
    }
}

License Key

Your license key is an Ed25519-signed JWT that contains your plan, limits, and feature flags.

What the key controls:

• Plan tier (Free, Pro, Business)
• Limits: max agents, mailboxes, tickets/month, storage
• Features: AI reply, knowledge base, auto-translation

Validation:

• The key is validated offline by default using the embedded Ed25519 public key — no external calls needed
• If MAILDESK_LICENSE_SERVER_URL is set, MailDesk will periodically verify the key online (optional)
• Validated license data is cached in Redis for 24 hours
• If Redis is down, the JWT is verified directly (Ed25519 needs no server)

Expired or invalid key:

• The app enters read-only mode — existing data remains accessible
• Creating tickets, sending replies, and AI features are disabled
• A banner shows "License expired" with a renewal link

Updating

# Load new images
docker load < maildesk-images.tar.gz

# Restart (migrations run automatically)
docker compose up -d

Migrations run automatically on every start — no manual migration step needed.

Backup & Restore

Backup

docker compose exec postgres pg_dump -U maildesk maildesk > backup_$(date +%Y%m%d).sql

docker compose cp worker:/data/attachments ./attachments-backup

docker compose exec redis redis-cli BGSAVE

Restore

docker compose exec -T postgres psql -U maildesk maildesk < backup_20260317.sql

docker compose cp ./attachments-backup/. worker:/data/attachments

Troubleshooting

docker compose logs app
docker compose logs migrate

docker compose logs app | grep -i license

docker compose logs clamav

docker compose logs worker

Architecture Overview

        ┌─────────────┐
        │  Reverse    │
        │  Proxy      │
        │  (TLS)      │
        └──────┬──────┘
               │ :3000
        ┌──────▼──────┐
        │    App      │
        │  (Next.js)  │
        └──┬──────┬───┘
           │      │
  ┌────────▼─┐  ┌─▼────────┐
  │ Postgres │  │  Redis   │
  │ (pgvec)  │  │ (queue)  │
  └────────▲─┘  └─▲────────┘
           │      │
        ┌──┴──────┴───┐
        │   Worker    │
        │ (IMAP/SMTP) │
        └──────┬──────┘
               │
        ┌──────▼──────┐
        │   ClamAV    │
        │ (antivirus) │
        └─────────────┘

• App — App serves the web UI and API routes
• Worker — Worker connects to mailboxes via IMAP, sends replies via SMTP, processes background jobs
• Postgres — Postgres stores all application data (with pgvector for AI embeddings)
• Redis — Redis handles job queues (BullMQ) and real-time pub/sub (WebSocket)
• ClamAV — ClamAV scans email attachments for malware