Guide de Déploiement

Ce guide vous accompagne dans le déploiement de Minispace sur votre propre serveur depuis zéro.

Étape 1 — Cloner le Dépôt

git clone https://github.com/minispace-app/minispace.git
cd minispace

Étape 2 — Configurer les Variables d'Environnement

Copiez le modèle d'environnement de production :

cp .env.prod.example .env

Ouvrez .env et remplissez chaque valeur. Les sections ci-dessous expliquent chacune d'elles.

Base de Données

POSTGRES_USER=garderie
POSTGRES_PASSWORD=votre_mot_de_passe_securise   # à changer
POSTGRES_DB=minispace

Secrets JWT

Générez deux secrets aléatoires forts (minimum 32 caractères chacun) :

openssl rand -base64 48   # exécutez deux fois, utilisez chaque sortie pour un secret

JWT_SECRET=votre_long_secret_aleatoire
JWT_REFRESH_SECRET=votre_long_secret_de_rafraichissement
JWT_EXPIRY_SECONDS=900        # durée du jeton d'accès (15 min)
JWT_REFRESH_EXPIRY_DAYS=30    # durée du jeton de rafraîchissement

Clé Maître de Chiffrement

Tous les fichiers téléversés sont chiffrés au repos avec AES-256-GCM. Générez une clé de 32 octets :

openssl rand -hex 32

ENCRYPTION_MASTER_KEY=votre_chaine_hexadecimale_de_64_caracteres

Critique : sauvegardez cette clé

Si vous perdez la ENCRYPTION_MASTER_KEY, tous les fichiers téléversés deviendront définitivement illisibles. Stockez-la en sécurité (gestionnaire de mots de passe, coffre-fort de secrets, etc.) et ne la committez jamais dans le contrôle de version.

SMTP (Courriel)

Minispace envoie des courriels pour les codes 2FA, les invitations, les notifications et les journaux. Vous avez besoin d'un serveur SMTP.

SMTP_HOST=smtp.gmail.com         # ou votre fournisseur SMTP
SMTP_PORT=587
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=votre_mot_de_passe_smtp
SMTP_FROM=[email protected]

Utilisateurs Gmail

Utilisez un Mot de Passe d'Application plutôt que votre mot de passe de compte Google. Alternativement, des services comme Mailgun, Resend ou Postmark fonctionnent bien.

Clé Super Admin

Cette clé protège l'API super-admin utilisée pour créer et gérer les garderies.

SUPER_ADMIN_KEY=remplacez_par_une_chaine_aleatoire_forte

Générez-en une avec :

openssl rand -base64 32

URLs de l'Application

APP_BASE_URL=https://votredomaine.com
NEXT_PUBLIC_API_URL=/api
NEXT_PUBLIC_WS_URL=/ws

Nginx & SSL

NGINX_ENV=prod
NGINX_HTTP_PORT=80
NGINX_HTTPS_PORT=443
SSL_CERTS_DIR=/etc/letsencrypt

Sauvegardes (optionnel)

BACKUP_ENCRYPT_PASSWORD=votre_mot_de_passe_sauvegarde   # optionnel, chiffre les fichiers de sauvegarde

Étape 3 — Certificat SSL

Obtenez un certificat avec Certbot :

# Installer Certbot
sudo apt install certbot

# Obtenir le certificat (arrêtez nginx d'abord si le port 80 est utilisé)
sudo certbot certonly --standalone -d votredomaine.com

Les certificats seront à /etc/letsencrypt/live/votredomaine.com/.

Note

La configuration nginx de production attend les certificats à : - /etc/nginx/ssl/live/minispace.app/fullchain.pem - /etc/nginx/ssl/live/minispace.app/privkey.pem

Mettez à jour nginx/nginx.prod.conf pour remplacer minispace.app par votre propre domaine avant de déployer.

Étape 4 — Mettre à Jour la Config Nginx pour Votre Domaine

Ouvrez nginx/nginx.prod.conf et remplacez toutes les occurrences de minispace.app par votre domaine :

sed -i 's/minispace\.app/votredomaine.com/g' nginx/nginx.prod.conf

Vous n'utilisez pas Cloudflare ?

La configuration nginx de production bloque tout le trafic qui ne passe pas par les IPs Cloudflare. Si vous n'utilisez pas Cloudflare, supprimez le bloc geo $cloudflare_ip et les vérifications if ($cloudflare_ip = 0) associées dans nginx.prod.conf, ou utilisez la configuration de développement (nginx.dev.conf) comme point de départ.

Étape 5 — Télécharger et Démarrer les Services

Téléchargez les images pré-compilées depuis GitHub Container Registry et démarrez la pile :

docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d

Vérifiez que tous les services fonctionnent :

docker compose -f docker-compose.prod.yml ps

Tous les services devraient afficher running. Consultez les logs si quelque chose ne va pas :

docker compose -f docker-compose.prod.yml logs -f api

Étape 6 — Créer Votre Première Garderie

Minispace utilise une API super-admin pour provisionner les garderies. Utilisez la SUPER_ADMIN_KEY que vous avez définie dans .env :

curl -X POST https://votredomaine.com/api/super-admin/garderies \
  -H "X-Super-Admin-Key: votre_cle_super_admin" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "ma-garderie",
    "name": "Ma Garderie",
    "email": "[email protected]",
    "phone": "514-555-0100",
    "address": "123 rue Principale, Montréal, QC"
  }'

Ceci provisionne un nouveau schéma PostgreSQL pour la garderie. Les utilisateurs peuvent ensuite y accéder à :

https://votredomaine.com

Étape 7 — Créer le Premier Utilisateur Admin

Après avoir créé une garderie, ajoutez le premier utilisateur admin :

curl -X POST https://votredomaine.com/api/super-admin/garderies/ma-garderie/users \
  -H "X-Super-Admin-Key: votre_cle_super_admin" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "mot_de_passe_temporaire",
    "first_name": "Admin",
    "last_name": "Utilisateur",
    "role": "admin_garderie"
  }'

L'admin peut ensuite se connecter à https://votredomaine.com et changer son mot de passe depuis son profil.

Sauvegardes

Le service backup s'exécute automatiquement chaque nuit à 02h00 et conserve 30 jours de sauvegardes dans ./backups/.

Pour exécuter une sauvegarde manuelle immédiatement :

docker compose -f docker-compose.prod.yml run --rm \
  -e MANUAL_BACKUP=true backup

Les fichiers de sauvegarde sont stockés dans ./backups/ sur l'hôte :

db_TIMESTAMP.sql.gz — dump PostgreSQL
media_TIMESTAMP.tar.gz — tous les fichiers téléversés

Restaurer depuis une Sauvegarde

# Restaurer la base de données
gunzip -c backups/db_2026-02-01T02:00:00.sql.gz | \
  docker exec -i minispace_db psql -U garderie minispace

# Restaurer les fichiers médias
docker run --rm -v minispace_media_files:/data/media \
  -v $(pwd)/backups:/backup alpine \
  tar -xzf /backup/media_2026-02-01T02:00:00.tar.gz -C /data/media

Mettre à Jour Minispace

Pour mettre à jour vers une version plus récente :

# Télécharger les nouvelles images
docker compose -f docker-compose.prod.yml pull

# Redémarrer les services (les migrations s'exécutent automatiquement au démarrage)
docker compose -f docker-compose.prod.yml up -d

Les migrations de base de données sont appliquées automatiquement au démarrage du conteneur API.

Référence des Variables d'Environnement

Variable	Requis	Description
`POSTGRES_USER`	Oui	Nom d'utilisateur PostgreSQL
`POSTGRES_PASSWORD`	Oui	Mot de passe PostgreSQL
`POSTGRES_DB`	Oui	Nom de la base de données PostgreSQL
`JWT_SECRET`	Oui	Secret de signature JWT (min 32 chars)
`JWT_REFRESH_SECRET`	Oui	Secret du jeton de rafraîchissement JWT
`JWT_EXPIRY_SECONDS`	Non	TTL du jeton d'accès, défaut `900`
`JWT_REFRESH_EXPIRY_DAYS`	Non	TTL du jeton de rafraîchissement, défaut `30`
`ENCRYPTION_MASTER_KEY`	Oui	Clé hex 64 chars pour le chiffrement des fichiers
`SMTP_HOST`	Oui	Nom d'hôte du serveur SMTP
`SMTP_PORT`	Oui	Port SMTP (généralement `587`)
`SMTP_USERNAME`	Oui	Nom d'utilisateur SMTP
`SMTP_PASSWORD`	Oui	Mot de passe SMTP
`SMTP_FROM`	Oui	Adresse courriel expéditeur
`SUPER_ADMIN_KEY`	Oui	Clé secrète pour l'API super-admin
`APP_BASE_URL`	Oui	URL publique de base de votre déploiement
`NEXT_PUBLIC_API_URL`	Oui	URL API du frontend (généralement `/api`)
`NEXT_PUBLIC_WS_URL`	Oui	URL WebSocket du frontend (généralement `/ws`)
`NGINX_ENV`	Non	`dev` ou `prod`, défaut `dev`
`SSL_CERTS_DIR`	Non	Chemin vers les certs SSL, défaut `/etc/letsencrypt`
`BACKUP_ENCRYPT_PASSWORD`	Non	Mot de passe pour chiffrer les archives de sauvegarde
`FCM_API_KEY`	Non	Clé Firebase Cloud Messaging (notifications push)
`RUST_LOG`	Non	Niveau de log, défaut `info`

Dépannage

Le conteneur API ne démarre pas

Consultez les logs :

docker compose -f docker-compose.prod.yml logs api

Causes courantes : - DATABASE_URL est incorrecte ou la base de données n'est pas accessible - ENCRYPTION_MASTER_KEY est manquante ou ne fait pas exactement 64 caractères hexadécimaux - JWT_SECRET est trop court (minimum 32 caractères)

Les courriels ne sont pas envoyés

Vérifiez que les valeurs SMTP_* sont correctes
Vérifiez que le port 587 n'est pas bloqué par le pare-feu de votre serveur
Recherchez les erreurs SMTP dans les logs API : docker compose logs api | grep -i smtp

Problèmes de certificat SSL

Assurez-vous que SSL_CERTS_DIR pointe vers le bon répertoire
Vérifiez que Certbot a les accès en écriture et que le domaine résout vers votre serveur
Consultez les logs nginx : docker compose logs nginx