Guide d'installation Self-Hosted

Prérequis

1. Extraire et charger

tar xzf maildesk-selfhosted.tar.gz
cd maildesk

docker load < maildesk-images.tar.gz

2. Configurer l'environnement

./setup.sh

Exécutez ./setup.sh pour auto-générer tous les secrets. Puis éditez .env pour définir votre APP_URL et clé de licence.

Ouvrez .env et définissez les valeurs suivantes :

Variables requises

Auto-généré par setup.sh

Ceux-ci sont générés automatiquement lors de l'exécution de setup.sh. Ne pas modifier sauf en cas de migration de données.

Variables optionnelles

Exemple .env pour 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. Démarrer

docker compose up -d

Cela démarre 6 services :

Le service migrate s'exécute automatiquement avant le démarrage de app et worker. Il crée toutes les tables de manière idempotente — sûr pour les bases de données nouvelles et existantes.

4. Vérifier le déploiement

# 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

Une fois healthy, ouvrez votre APP_URL dans un navigateur. Vous devriez voir la page de connexion/inscription.

5. Configuration initiale

1. 1Enregistrez le premier compte administrateur sur votre-domaine.com/register
2. 2Créez une organisation — c'est votre espace de travail
3. 3Ajoutez une boîte mail dans Paramètres > Boîtes mail (identifiants IMAP/SMTP)
4. 4Les e-mails entrants créeront automatiquement des tickets

Vérification d'email (Optionnel)

Configurez SMTP pour activer la vérification d'email pour les nouveaux utilisateurs. Sans SMTP, les nouveaux utilisateurs sont auto-vérifiés et peuvent se connecter immédiatement.

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

Configuration du Reverse Proxy

MailDesk nécessite un reverse proxy pour la terminaison TLS. Voici des exemples pour les configurations courantes :

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

Clé de licence

Votre clé de licence est un JWT signé Ed25519 qui contient votre plan, limites et flags de fonctionnalités.

Ce que la clé contrôle :

• Niveau de plan (Free, Pro, Business)
• Limites : max. agents, boîtes mail, tickets/mois, stockage
• Fonctionnalités : réponse IA, base de connaissances, traduction automatique

Validation :

• La clé est validée hors ligne par défaut avec la clé publique Ed25519 intégrée — aucun appel externe nécessaire
• Si MAILDESK_LICENSE_SERVER_URL est défini, MailDesk vérifiera la clé en ligne périodiquement (optionnel)
• Les données de licence validées sont mises en cache dans Redis pendant 24 heures
• Si Redis est indisponible, le JWT est vérifié directement (Ed25519 n'a pas besoin de serveur)

Clé expirée ou invalide :

• L'application passe en mode lecture seule — les données existantes restent accessibles
• La création de tickets, l'envoi de réponses et les fonctionnalités IA sont désactivés
• Une bannière affiche « Licence expirée » avec un lien de renouvellement

Mise à jour

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

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

Les migrations s'exécutent automatiquement à chaque démarrage — aucune étape de migration manuelle nécessaire.

Sauvegarde et restauration

Sauvegarde

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

Restauration

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

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

Dépannage

docker compose logs app
docker compose logs migrate

docker compose logs app | grep -i license

docker compose logs clamav

docker compose logs worker

Vue d'ensemble de l'architecture

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

• App — App fournit l'interface web et les routes API
• Worker — Worker se connecte aux boîtes mail via IMAP, envoie les réponses via SMTP, traite les tâches en arrière-plan
• Postgres — Postgres stocke toutes les données de l'application (avec pgvector pour les embeddings IA)
• Redis — Redis gère les files d'attente (BullMQ) et le pub/sub en temps réel (WebSocket)
• ClamAV — ClamAV analyse les pièces jointes pour détecter les malwares