Déployer Explainer en production : le guide complet

Vous avez rédigé votre documentation, personnalisé le thème, et tout est parfait en local. Il est temps de partager avec le monde. Dans ce guide, nous couvrons toute l’histoire du déploiement — de la configuration de build aux pipelines CI/CD.

Comprendre la sortie de build

Les applications Explainer sont des sites statiques Astro standards. L’exécution de pnpm build produit un répertoire dist/ contenant des fichiers HTML, CSS et JavaScript. Aucun runtime serveur requis — vous pouvez héberger la sortie partout où des fichiers statiques sont servis.

# Compiler les trois applications
pnpm build

# Ou compiler individuellement
pnpm --filter @explainer/docs build
pnpm --filter @explainer/blog build
pnpm --filter @explainer/website build

Variables d’environnement

Avant de compiler pour la production, configurez vos URLs inter-applications. Elles assurent que les liens de la navbar pointent vers les bons domaines :

PUBLIC_WEBSITE_URL=https://explainer.dev
PUBLIC_DOCS_URL=https://docs.explainer.dev
PUBLIC_BLOG_URL=https://blog.explainer.dev

Pour la section contributeurs, vous pouvez optionnellement fournir un token GitHub pour des limites d’API plus élevées :

GITHUB_TOKEN=ghp_xxxxxxxxxxxx

Déployer sur Cloudflare Pages

Cloudflare Pages est notre cible de déploiement recommandée. Il offre un palier gratuit généreux, un CDN mondial et des déploiements de prévisualisation automatiques.

- run: pnpm --filter @explainer/docs build
  env:
    PUBLIC_DOCS_URL: ${{ vars.PUBLIC_DOCS_URL }}
    PUBLIC_BLOG_URL: ${{ vars.PUBLIC_BLOG_URL }}
    PUBLIC_WEBSITE_URL: ${{ vars.PUBLIC_WEBSITE_URL }}
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Déployer sur Vercel

L’approche zéro-config de Vercel fonctionne parfaitement avec Explainer. Chaque application peut être importée comme un projet Vercel séparé.

CI/CD intelligent avec filtrage par chemin

Le workflow monorepo inclut un filtrage intelligent par chemin — seules les applications avec des changements réels sont recompilées et déployées :

- uses: dorny/paths-filter@v4
  with:
    filters: |
      docs:
        - 'apps/docs/**'
        - 'packages/**'
        - 'pnpm-lock.yaml'
      blog:
        - 'apps/blog/**'
        - 'packages/**'
        - 'pnpm-lock.yaml'

Domaines personnalisés et DNS

Une configuration typique utilise des sous-domaines :

Cloudflare Pages comme Vercel gèrent les certificats SSL automatiquement.

Déploiement Docker

Pour les environnements auto-hébergés, Explainer supporte le déploiement Docker avec un build multi-stage :

FROM node:22-alpine AS build
RUN corepack enable
WORKDIR /app
COPY . .
RUN pnpm install --frozen-lockfile
RUN pnpm --filter @explainer/docs build

FROM nginx:alpine
COPY --from=build /app/apps/docs/dist /usr/share/nginx/html

Vous pouvez servir les trois applications derrière un reverse proxy (nginx, Caddy, Traefik) avec un routage par chemin ou par sous-domaine.

Checklist performance

Avant la mise en ligne, vérifiez que ces optimisations sont en place :

Et ensuite

Avec votre documentation déployée, vous pouvez vous concentrer sur l’essentiel — écrire du contenu de qualité. Le pipeline CI/CD garantit que chaque push sur main met vos changements en ligne en quelques minutes.

Bon déploiement !