YYayaw

Procédures opérationnelles

Runbooks d'exploitation pour les tâches de maintenance courantes.

Régénérer Les Actions DB

bun run generate:actions

Lancez cette commande après des changements de schéma Drizzle. Commitez les fichiers générés avec le changement de schéma afin que TypeScript et les tests de contrats authz voient la même surface d'actions base de données que le runtime.

Changer Le Domaine Production

La production Yayaw est servie canoniquement depuis https://yayaw.app.

  1. Attachez le domaine apex au projet Vercel yayaw:
vercel domains add yayaw.app
  1. Ajoutez www.yayaw.app comme domaine projet redirigeant vers yayaw.app avec le statut 308.
  2. Gardez les domaines .eu retirés uniquement comme redirections de domaine projet avec le statut 308: routez yayaw.eu et www.yayaw.eu vers yayaw.app. Les projets compagnons doivent suivre le même modèle, par exemple table.yayaw.eu vers table.yayaw.app.
  3. Définissez les variables d'environnement production:
NEXT_PUBLIC_BASE_URL=https://yayaw.app
BETTER_AUTH_TRUSTED_ORIGINS=https://*.yayaw.app,https://*.vercel.app
  1. Gardez une branche Git durable preview, attachez preview.yayaw.app comme domaine de prévisualisation Vercel adossé à cette branche, puis définissez le NEXT_PUBLIC_BASE_URL de prévisualisation:
NEXT_PUBLIC_BASE_URL=https://preview.yayaw.app
  1. Ne gardez pas d'anciens hôtes de prévisualisation comme domaines actifs après vérification de preview.yayaw.app.
  2. Redéployez les derniers déploiements production et prévisualisation afin que les builds reçoivent l'URL publique de base.
  3. Mettez à jour les callbacks et webhooks tiers qui stockent des origines absolues: fournisseurs OAuth, webhooks Stripe, URLs de retour du portail de facturation, liens e-mail et réglages analytics/site.

Déployer Le Runtime Auto-Hébergé

  1. Copiez le fichier exemple et renseignez les secrets production hors git:
cp .env.self-host.example .env.self-host
perl -0pi -e "s/^BETTER_AUTH_SECRET=$/BETTER_AUTH_SECRET=$(openssl rand -hex 32)/m" .env.self-host
  1. Lancez la synchronisation de schéma et le seed:
docker compose --env-file .env.self-host -f docker-compose.self-host.yml --profile setup run --rm migrate
  1. Démarrez ou mettez à jour le runtime:
docker compose --env-file .env.self-host -f docker-compose.self-host.yml up --build -d
  1. Confirmez que Caddy atteint l'app et que les en-têtes Host/X-Forwarded-* sont préservés en ouvrant le DEPLOYMENT_URL configuré.
  2. Téléversez une ressource média et confirmez qu'elle est servie depuis le STORAGE_PUBLIC_BASE_URL configuré.
  3. Confirmez que bun run worker:page-ai tourne via le service Compose worker lorsque PAGE_AI_QUEUE_DRIVER=db-worker.
  4. Sauvegardez Postgres et le stockage objet ensemble avant toute release risquée.

Mettre À Jour Les Feature Flags Seedés

  1. Modifiez src/lib/scripts/seed.ts.
  2. Appliquez le seed:
bun run seed
  1. Relancez les checks applicatifs:
bun run check
bunx tsc --noEmit
bun run build

Miroiter La Documentation Yayaw Table Dans Le CMS

Utilisez le script de migration adossé au MCP seulement lorsqu'un opérateur a besoin d'un miroir CMS de la documentation Fumadocs Yayaw Table sous https://yayaw.app/table/docs. La source de vérité reste content/docs/{en,fr}/table. Gardez la landing Table et la page d'exemple directement rédigées dans le CMS.

Lancez d'abord un dry-run:

YAYAW_MCP_LOCAL_USER_ID=<superadmin-user-id> \
YAYAW_MCP_ENV_FILE=/path/to/yayaw-env.txt \
  bun --conditions react-server --env-file=.env \
  src/lib/scripts/mcp/migrate-table-pages-to-cms.ts

Appliquez et publiez les pages CMS après un dry-run propre:

TABLE_CMS_APPLY=1 TABLE_CMS_PUBLISH=1 \
YAYAW_MCP_LOCAL_USER_ID=<superadmin-user-id> \
YAYAW_MCP_ENV_FILE=/path/to/yayaw-env.txt \
  bun --conditions react-server --env-file=.env \
  src/lib/scripts/mcp/migrate-table-pages-to-cms.ts

Le script clone la source publique Yayaw-Table, construit des documents Puck localisés pour /table/docs et chaque guide /table/docs/*, puis les crée, valide et publie via le serveur MCP stdio local. Définissez YAYAW_TABLE_SOURCE_DIR pour réutiliser un checkout existant ou YAYAW_TABLE_SOURCE_REF pour migrer une branche source précise. Définissez YAYAW_MCP_ENV_FILE si le serveur MCP local doit utiliser un fichier d'environnement autre que .env. Définissez YAYAW_MCP_REQUEST_TIMEOUT_MS si un tunnel lent ou un gros dataset CMS nécessite plus que le timeout MCP par défaut de cinq minutes. Définissez TABLE_CMS_SKIP_EXISTING_PAGE_SCAN=1 pour ignorer le scan non essentiel de la page globale /table via tunnel lent; chaque page est quand même vérifiée par slug avant create/update. Définissez TABLE_CMS_INCLUDE_SITE_PAGES=1 seulement si vous voulez régénérer intentionnellement /table et /table/example depuis le projet source au lieu de conserver ces pages rédigées dans le CMS.

Synchroniser Le Sous-Projet Fumadocs Yayaw Table

Utilisez le sous-projet Fumadocs lorsque Yayaw doit versionner la documentation développeur de Yayaw Table. Ces pages vivent dans content/docs/{en,fr}/table et sont servies depuis /[locale]/docs/table/*. C'est distinct de la route CMS publique /[locale]/table/docs/*.

Lors d'un import depuis le dépôt upstream Yayaw-Table:

  1. Copiez les fichiers anglais content/docs/*.mdx vers content/docs/en/table.
  2. Copiez les fichiers français content/docs/*.fr.mdx vers content/docs/fr/table, en retirant le suffixe .fr.
  3. Copiez content/docs/meta.json vers content/docs/en/table/meta.json et content/docs/meta.fr.json vers content/docs/fr/table/meta.json.
  4. Réécrivez les liens internes de /docs/... vers des liens relatifs comme ./setup afin que les pages se résolvent sous /docs/table.
  5. Gardez content/docs/en/table/meta.json et content/docs/fr/table/meta.json dans le même ordre, puis lancez bun run docs:check-translations.

Valider Les Webhooks De Facturation En Staging

  1. Webhook du plugin Better Auth Stripe:
stripe listen --forward-to https://<staging-domain>/api/auth/stripe/webhook
  1. Webhook ponctuel custom:
stripe listen --forward-to https://<staging-domain>/api/billing/stripe/webhook
  1. Déclenchez des événements:
stripe trigger checkout.session.completed
stripe trigger customer.subscription.updated
stripe trigger customer.subscription.deleted
stripe trigger invoice.payment_failed
stripe trigger invoice.paid

invoice.payment_failed et invoice.paid doivent atteindre l'endpoint Stripe du plugin Better Auth sur /api/auth/stripe/webhook. L'endpoint custom des achats ponctuels sur /api/billing/stripe/webhook traite volontairement uniquement checkout.session.completed.

Rejouer Les Webhooks Ponctuels Échoués

Quand le traitement d'un webhook ponctuel échoue à cause d'un incident transitoire, rejouez les événements échoués:

bun run billing:replay-webhooks

Limite optionnelle:

bun run billing:replay-webhooks -- --limit=20

Régénérer Les Artefacts Source Fumadocs

bun run docs:generate

Régénérer Les Fichiers Assistants LLM

bun run docs:llm:generate

Lancez cette commande après une modification de content/llm/llm-source.md. Ne modifiez pas AGENTS.md, GEMINI.md ni .github/copilot-instructions.md manuellement.

Lancer Une Passe Docs Complète

Utilisez ceci lors de changements documentaires larges:

bun run docs:generate
bun run docs:check-links
bun run docs:check-translations
bun run docs:llm:generate
bun run docs:llm:check
bun run check

Si le changement docs touche les routes, imports ou rendu MDX, lancez aussi:

bunx tsc --noEmit
bun run build

Gardez les docs anglaises canoniques. Lorsque la tâche demande les docs localisées, mettez à jour le miroir français dans la même PR.

Gérer Les Clés MCP Production

Émettre une clé MCP production pour un utilisateur:

bun run mcp:key -- issue --email admin@example.com --permissions read,write,publish,admin

Révoquer une clé MCP production:

bun run mcp:key -- revoke --key-id <api-key-id>

Faites une rotation en émettant d'abord la clé de remplacement, en mettant à jour le secret client, en vérifiant yayaw_status, puis en révoquant l'ancienne clé.

Valider L'Intégrité De Documentation

bun run docs:check-links
bun run docs:check-translations
bun run docs:llm:check

Si docs:llm:check échoue, régénérez avec bun run docs:llm:generate et revoyez le diff des fichiers assistants générés avant commit.

Vérifier L'Accès Au Code GitHub

  1. Confirmez que /dashboard/admin/billing-settings active l'accès dépôt GitHub.
  2. Confirmez la présence du dépôt, de l'ID GitHub App et de l'ID d'installation.
  3. Confirmez que BILLING_CODE_ACCESS_GITHUB_APP_PRIVATE_KEY existe dans l'environnement de déploiement cible.
  4. Utilisez une organisation de test payante avec code-access:read.
  5. Soumettez un username GitHub depuis /dashboard/organization/code-access.
  6. Confirmez que code_access_github_accounts enregistre l'invitation ou l'état d'accès actif.
  7. Confirmez dans GitHub que l'invitation au dépôt donne un accès lecture seule.

En staging sans GitHub App, utilisez BILLING_CODE_ACCESS_GITHUB_TOKEN uniquement comme solution de repli temporaire explicite.

Vérifier Le Stockage Média

  1. Confirmez que les variables du fournisseur de stockage choisi sont configurées: STORAGE_PROVIDER=supabase avec les clés Supabase, ou STORAGE_PROVIDER=s3 avec les clés S3/MinIO et STORAGE_PUBLIC_BASE_URL.
  2. Téléversez une image depuis /dashboard/content/media.
  3. Confirmez qu'une ligne media_assets est créée pour l'organisation active.
  4. Confirmez que l'URL publique charge.
  5. Ouvrez l'éditeur de page et liez la ressource à un champ image.
  6. Publiez la page et confirmez que la page publique rend la ressource choisie.
  7. Si les miniatures sont activées pour ce type de ressource, confirmez qu'une URL de miniature est créée ou qu'un échec non bloquant de miniature est enregistré.

Vérifier Le DNS Manuel De Domaine Public

  1. Définissez PUBLIC_DOMAIN_PROVIDER=manual-dns.
  2. Configurez PUBLIC_DOMAIN_CNAME_TARGET ou PUBLIC_DOMAIN_IPV4_TARGETS.
  3. Ajoutez un domaine depuis les réglages d'organisation ou yayaw_org_domain_add.
  4. Publiez le challenge TXT affiché dans le dashboard.
  5. Pointez le hostname vers le proxy inverse.
  6. Lancez l'action de check/vérification et confirmez que le domaine devient verified.
  7. Ouvrez l'hôte personnalisé et confirmez que les pages publiques rendent tandis que /dashboard, /auth, /api, /docs, /o et /ingest restent bloqués.

Réinitialiser La Base Locale

bun run db:reset

Dépanner Les Problèmes De Build

  1. Régénérez les artefacts:
bun run generate:actions
bun run docs:generate
  1. Relancez les checks:
bun run check
bunx tsc --noEmit
bun run build

Dépanner Les Blocages esbuild / Drizzle

Symptômes:

  • bun run docs:generate ne termine pas
  • bun run db:generate ou bun run db:push reste bloqué

Actions:

  1. Relancez la commande une fois pour confirmer la sortie de timeout des scripts safe.
  2. Réinstallez les dépendances:
rm -rf node_modules
bun install
  1. Réessayez:
bun run docs:generate
bun run db:generate
bun run db:push

CI/CD

Comportement actuel des GitHub Actions et des déploiements.

On this page

Régénérer Les Actions DBChanger Le Domaine ProductionDéployer Le Runtime Auto-HébergéMettre À Jour Les Feature Flags SeedésMiroiter La Documentation Yayaw Table Dans Le CMSSynchroniser Le Sous-Projet Fumadocs Yayaw TableValider Les Webhooks De Facturation En StagingRejouer Les Webhooks Ponctuels ÉchouésRégénérer Les Artefacts Source FumadocsRégénérer Les Fichiers Assistants LLMLancer Une Passe Docs ComplèteGérer Les Clés MCP ProductionValider L'Intégrité De DocumentationVérifier L'Accès Au Code GitHubVérifier Le Stockage MédiaVérifier Le DNS Manuel De Domaine PublicRéinitialiser La Base LocaleDépanner Les Problèmes De BuildDépanner Les Blocages esbuild / Drizzle