Guía de instalación Self-Hosted

Requisitos previos

1. Extraer y cargar

tar xzf maildesk-selfhosted.tar.gz
cd maildesk

docker load < maildesk-images.tar.gz

2. Configurar entorno

./setup.sh

Ejecuta ./setup.sh para auto-generar todos los secretos. Luego edita .env para configurar tu APP_URL y clave de licencia.

Abre .env y configura los siguientes valores:

Variables requeridas

Auto-generado por setup.sh

Estos se generan automáticamente al ejecutar setup.sh. No cambiar excepto al migrar datos.

Variables opcionales

Ejemplo .env para 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. Iniciar

docker compose up -d

Esto inicia 6 servicios:

El servicio migrate se ejecuta automáticamente antes de que app y worker inicien. Crea todas las tablas de forma idempotente — seguro para bases de datos nuevas y existentes.

4. Verificar el despliegue

# 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

Una vez healthy, abre tu APP_URL en un navegador. Deberías ver la página de login/registro.

5. Configuración inicial

1. 1Registra la primera cuenta de administrador en tu-dominio.com/register
2. 2Crea una organización — este es tu espacio de trabajo
3. 3Añade un buzón en Configuración > Buzones (credenciales IMAP/SMTP)
4. 4Los correos entrantes crearán tickets automáticamente

Verificación de Email (Opcional)

Configura SMTP para habilitar la verificación de email para nuevos usuarios. Sin SMTP, los nuevos usuarios se verifican automáticamente y pueden iniciar sesión de inmediato.

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

Configuración de Reverse Proxy

MailDesk requiere un reverse proxy para terminación TLS. Aquí hay ejemplos para configuraciones comunes:

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

Clave de licencia

Tu clave de licencia es un JWT firmado con Ed25519 que contiene tu plan, límites y flags de funciones.

Qué controla la clave:

• Nivel de plan (Free, Pro, Business)
• Límites: máx. agentes, buzones, tickets/mes, almacenamiento
• Funciones: respuesta IA, base de conocimiento, traducción automática

Validación:

• La clave se valida offline por defecto usando la clave pública Ed25519 integrada — sin llamadas externas necesarias
• Si MAILDESK_LICENSE_SERVER_URL está configurado, MailDesk verificará la clave online periódicamente (opcional)
• Los datos de licencia validados se almacenan en caché en Redis durante 24 horas
• Si Redis no está disponible, el JWT se verifica directamente (Ed25519 no necesita servidor)

Clave expirada o inválida:

• La app entra en modo solo lectura — los datos existentes siguen accesibles
• Crear tickets, enviar respuestas y funciones de IA están desactivados
• Un banner muestra "Licencia expirada" con un enlace de renovación

Actualización

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

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

Las migraciones se ejecutan automáticamente en cada inicio — no se necesita paso de migración manual.

Backup y restauración

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

Restauración

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

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

Solución de problemas

docker compose logs app
docker compose logs migrate

docker compose logs app | grep -i license

docker compose logs clamav

docker compose logs worker

Vista general de la arquitectura

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

• App — App sirve la interfaz web y las rutas API
• Worker — Worker se conecta a buzones vía IMAP, envía respuestas vía SMTP, procesa tareas en segundo plano
• Postgres — Postgres almacena todos los datos de la aplicación (con pgvector para embeddings de IA)
• Redis — Redis gestiona colas de tareas (BullMQ) y pub/sub en tiempo real (WebSocket)
• ClamAV — ClamAV escanea adjuntos de correo en busca de malware