Self-hosting

Prérequis

Démarrage rapide

1. Cloner le dépôt

git clone https://github.com/roadmaps-faciles/roadmaps-faciles.git
cd roadmaps-faciles

2. Lancer les services avec Docker Compose

Le fichier docker-compose.yml fourni démarre les trois services nécessaires au développement :

docker compose up -d

3. Configurer les variables d'environnement

Copiez le fichier de configuration de développement et adaptez-le :

cp .env.development .env.production.local

Les variables minimales à configurer sont décrites dans la section Variables d'environnement.

4. Installer les dépendances et préparer la base

pnpm install
pnpm prisma migrate deploy
pnpm prisma db seed

5. Lancer le serveur de développement

pnpm dev

L'application est accessible sur http://localhost:3000.

Variables d'environnement

Obligatoires

Optionnelles

Licence (features EE — optionnel)

Pour débloquer les features Enterprise Edition (intégrations, API keys, webhooks, domaines custom, tracking avancé, 2FA…) sur une instance self-hosted, vous devez acquérir une licence sur licensing.roadmaps-faciles.fr.

Plans disponibles :

Sans licence, l'instance fonctionne en mode Community avec les fonctionnalités core (AGPL v3).

OAuth / SSO (optionnel)

Pour activer la connexion via des fournisseurs OAuth, configurez les variables correspondantes :

Seuls les fournisseurs dont les variables sont renseignées seront disponibles. Chaque tenant choisit ensuite lesquels activer via Administration > Authentification.

Observabilité (optionnel)

Branding

L'apparence de l'instance est personnalisable via les variables NEXT_PUBLIC_BRAND_* :

Mentions légales

Les pages légales (mentions légales, politique de confidentialité) sont personnalisables pour refléter les informations de l'opérateur qui héberge l'instance :

SMTP

Stockage S3 (upload d'images)

Pour activer l'upload d'images dans les contributions, configurez un stockage S3-compatible :

Multi-tenant et domaines

Les variables spécifiques à chaque fournisseur sont documentées dans le fichier .env.development.

Build et lancement en production

1. Build

pnpm install
pnpm build

Le build produit un standalone output dans apps/web/.next/standalone/ — un serveur Node.js autonome qui embarque uniquement les dépendances nécessaires.

2. Lancement

node apps/web/.next/standalone/apps/web/server.js

Le serveur écoute par défaut sur le port 3000. Utilisez la variable PORT pour le modifier :

PORT=8080 node apps/web/.next/standalone/apps/web/server.js

Base de données

Migrations

Appliquez les migrations Prisma avant chaque déploiement :

pnpm prisma migrate deploy

Seed

Le seed initialise un administrateur et un premier espace de travail. Il est configurable via les variables SEED_* :

pnpm prisma db seed

Options de déploiement

Scalingo

Roadmaps Faciles fournit un fichier scalingo.json pour le déploiement one-click :

• Les addons PostgreSQL et Redis sont provisionnés automatiquement.
• Les secrets (SECURITY_JWT_SECRET, SECURITY_WEBHOOK_SECRET) sont générés automatiquement.
• Le script first-deploy exécute prisma migrate reset --force pour initialiser la base.

Variables spécifiques :

Le mode scalingo-wildcard utilise un certificat wildcard (*.rootDomain) pour les sous-domaines, évitant la création d'un certificat par sous-domaine. Prérequis : un enregistrement DNS TXT _acme-challenge.rootDomain pour la validation Let's Encrypt, renouvelé automatiquement si le DNS provider est configuré (OVH, Cloudflare, Gandi, AWS Route 53, etc.).

Clever Cloud

VPS avec Caddy

Pour un hébergement sur VPS, Caddy est recommandé comme reverse proxy. Il gère automatiquement les certificats TLS via le mode on-demand TLS :

1. Caddy reçoit une requête pour un domaine inconnu.
2. Il interroge l'endpoint /api/domains/check?domain=... de l'application.
3. Si le domaine correspond à un espace existant (sous-domaine ou domaine personnalisé), l'application répond 200 et Caddy émet un certificat Let's Encrypt.
4. Si le domaine est inconnu, l'application répond 404 et Caddy refuse la connexion.

Exemple de configuration Caddy (Caddyfile) :

{
    on_demand_tls {
        ask http://localhost:3000/api/domains/check
    }
}

:443 {
    tls {
        on_demand
    }
    reverse_proxy localhost:3000
}

Docker

L'application ne fournit pas de Dockerfile officiel, mais le standalone output se prête bien à la conteneurisation :

FROM node:24-alpine

WORKDIR /app
COPY apps/web/.next/standalone ./
COPY apps/web/.next/static ./apps/web/.next/static
COPY apps/web/public ./apps/web/public

ENV PORT=3000
EXPOSE 3000

CMD ["node", "apps/web/server.js"]

Vérification

L'endpoint GET /api/healthz vérifie la connectivité aux services critiques :

curl -s http://localhost:3000/api/healthz | jq

Réponse type :

{
  "status": "healthy",
  "version": "0.0.1",
  "environment": "production",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "checks": {
    "database": { "status": "healthy", "latencyMs": 5 },
    "redis": { "status": "healthy", "latencyMs": 2 }
  }
}

Cet endpoint est adapté pour les health checks de votre orchestrateur (Kubernetes, load balancer, monitoring).

Domaines personnalisés

Chaque espace de travail peut utiliser un domaine personnalisé en plus de son sous-domaine automatique.

Configuration

1. Créez un enregistrement CNAME pointant vers le domaine racine de votre instance :

feedback.mon-produit.fr.  3600  IN  CNAME  roadmaps-faciles.incubateur.ademe.dev.

2. Ajoutez le domaine personnalisé dans l'interface d'administration de l'espace.

3. La plateforme vérifie le CNAME et provisionne le certificat TLS selon le fournisseur de domaine configuré.

Pour la configuration DNS détaillée, consultez la page Configuration DNS.

Fournisseurs DNS supportés

La plateforme peut automatiser la gestion des enregistrements DNS pour les sous-domaines (pas les domaines personnalisés) :

Bonnes pratiques production

• Secrets — Utilisez des secrets générés aléatoirement (32+ caractères). Ne partagez jamais les secrets entre environnements.
• Backups — Planifiez des sauvegardes régulières de PostgreSQL (pg_dump). Redis stocke des données éphémères (preuves 2FA, challenges WebAuthn, codes OTP) avec des TTL courts — il ne nécessite pas de sauvegarde, mais doit être disponible en permanence.
• Monitoring — Configurez un check périodique sur /api/healthz. Activez Sentry (SENTRY_DSN) pour le suivi d'erreurs en temps réel.
• Logs — En production, les logs sont émis en JSON (Pino). Configurez LOG_LEVEL=info et collectez les logs avec votre outil habituel (Datadog, Loki, ELK...).
• Mises à jour — Suivez les releases du dépôt. Procédure de mise à jour :
  1. git pull (ou téléchargez la release)
  2. pnpm install
  3. pnpm build
  4. pnpm prisma migrate deploy
  5. Redémarrez le serveur
• Administration — Le premier super-administrateur est défini par la variable ADMINS. Limitez le nombre de super-administrateurs au strict nécessaire.
• TLS — En production, toutes les connexions doivent être en HTTPS. Caddy, Scalingo et Clever Cloud gèrent les certificats automatiquement.