Configuration de l'environnement de déploiement

Cette page est le guide opérateur des variables d'environnement de déploiement. Utilisez-la lors de la création d'un projet Vercel, de la restauration d'un environnement production, de la vérification d'une prévisualisation avec le même câblage fournisseur que la production, ou de la préparation du runtime Docker auto-hébergé.

Règles

• Ne commitez jamais de secrets dans .env, .env.production ou un fichier suivi.
• Stockez les secrets Vercel production et preview dans les variables d'environnement du projet Vercel.
• Stockez les secrets production auto-hébergés dans le magasin de secrets de l'orchestrateur. Pour la base Compose, utilisez un fichier non suivi .env.self-host copié depuis .env.self-host.example.
• Stockez les secrets locaux dans .env.local ou dans un .env.local récupéré avec vercel env pull.
• Gardez les valeurs NEXT_PUBLIC_* non secrètes: elles sont exposées au bundle navigateur.
• Préférez les réglages admin/runtime pour les non-secrets opérationnels lorsque le dashboard les supporte. Par exemple, les réglages dépôt GitHub pour l'accès au code se gèrent depuis /dashboard/admin/billing-settings; les variables d'environnement ne sont que des replis.

Workflow Vercel

Liez le checkout local au bon projet Vercel avant de récupérer ou pousser des variables:

vercel link --yes --project <project-name-or-id> --scope <team-or-user>

Ajoutez les secrets depuis le dashboard Vercel ou la CLI. Bornez les valeurs production-only à Production, les valeurs preview à Preview et les valeurs de développement local à Development:

echo "<secret-value>" | vercel env add VARIABLE_NAME production
echo "<secret-value>" | vercel env add VARIABLE_NAME preview
echo "<secret-value>" | vercel env add VARIABLE_NAME development

Après ajout ou modification de variables, redéployez l'environnement Vercel concerné. Les déploiements existants ne reçoivent pas automatiquement les nouvelles valeurs.

Récupérez une copie locale pour le développement:

vercel env pull .env.local --environment=development --yes

Récupérez les valeurs production uniquement pour un audit explicite sur une machine de confiance:

vercel env pull .env.production.local --environment=production --yes

Vérifiez que chaque clé listée dans .env.example est présente localement:

while IFS='=' read -r key _; do
  [[ -z "$key" || "$key" == \#* ]] && continue
  grep -q "^${key}=" .env.local || echo "Missing in .env.local: $key"
done < .env.example

Workflow Docker Auto-Hébergé

La base portable utilise Docker Compose avec Postgres, MinIO/S3, le serveur app Next.js standalone, un worker Page AI et Caddy:

cp .env.self-host.example .env.self-host
docker compose --env-file .env.self-host -f docker-compose.self-host.yml --profile setup run --rm migrate
docker compose --env-file .env.self-host -f docker-compose.self-host.yml up --build

Les builds Docker utilisent NEXT_BUILD_WORKERS=1 par défaut pour une génération statique Next.js stable sur de petits hôtes. Sur une machine plus large, vous pouvez l'augmenter, par exemple:

NEXT_BUILD_WORKERS=2 docker compose --env-file .env.self-host -f docker-compose.self-host.yml up --build

Les builds Docker auto-hébergés fixent aussi NEXT_STATIC_PAGE_GENERATION_TIMEOUT=180 par défaut. Cela donne aux hôtes lents assez de temps pour pré-rendre de grosses pages docs sans déclencher le timeout Next.js de 60 secondes. Baissez-le sur des builders CI rapides ou augmentez-le uniquement si les logs montrent des pages statiques légitimes en timeout.

Les builds Docker auto-hébergés rendent les pages Fumadocs dynamiquement au lieu de prégénérer toute la documentation pendant la construction d'image. Cela évite aux petits hôtes Coolify ou Docker de dépenser l'essentiel du budget de déploiement sur les docs tout en les servant normalement au runtime.

Les fichiers Compose taguent les cibles app et worker avec YAYAW_APP_IMAGE et YAYAW_WORKER_IMAGE. Gardez le même tag worker pour les services migrate et worker afin que Docker ou Coolify puisse réutiliser la cible worker au lieu de la construire deux fois.

Le déploiement Coolify managé par Yayaw utilise des images précompilées plutôt qu'un build sur la VM production. GitHub Actions construit les images app et worker sur des runners ubuntu-24.04-arm pour la plateforme linux/arm64 du Mac mini, pousse les images vers GHCR, les fait tirer par le serveur Coolify via le runner auto-hébergé privé, met à jour YAYAW_APP_IMAGE et YAYAW_WORKER_IMAGE, puis demande à Coolify de lancer le déploiement Compose. Cela conserve la release automatique sur main, déplace le build coûteux hors de la VM Mac mini et évite le quota de stockage artifacts GitHub Actions.

Coolify doit stocker ces tags d'image comme valeurs build-time et runtime, parce que Docker Compose interpole les entrées image: pendant la préparation du déploiement.

Le profil setup lance la synchronisation de schéma drizzle-kit push puis le seed. Relancez-le avant le démarrage d'une base auto-hébergée fraîche et après les changements de schéma. Ce n'est pas un runner de migrations Drizzle versionnées.

Ne commitez pas .env.self-host. En production, déplacez les mêmes valeurs dans le secret manager de l'hôte cible ou l'environnement Compose. Générez BETTER_AUTH_SECRET avant le premier build Docker, par exemple avec openssl rand -hex 32; le Dockerfile échoue immédiatement lorsqu'il est vide. Le flag --env-file rend les mêmes valeurs publiques disponibles aux arguments de build Docker. BETTER_AUTH_SECRET est aussi passé à next build pour éviter que l'évaluation des routes Better Auth ne retombe sur un secret de développement pendant la construction d'image. Reconstruisez l'image quand les valeurs NEXT_PUBLIC_* changent.

Environnements CI Coolify

Les déploiements Coolify auto-hébergés sont pilotés depuis GitHub Actions:

• les pull requests déploient vers une application Coolify development partagée après réussite de la CI
• les pushes vers main déploient vers l'application Coolify production après réussite de la CI

Configurez deux environnements GitHub avec des UUID d'applications Coolify séparés:

Les workflows ont aussi besoin des permissions packages du dépôt: les jobs de build utilisent packages: write pour publier ghcr.io/<owner>/yayaw-app:<sha> et ghcr.io/<owner>/yayaw-worker:<sha>, tandis que les jobs de déploiement Coolify utilisent packages: read pour tirer ces images depuis le runner auto-hébergé.

L'app development partagée est volontairement mutable: chaque pull request met à jour la git_branch de l'app dans Coolify et déploie cette branche sans forcer de rebuild, afin que BuildKit réutilise les layers entre development et production. GitHub Actions sérialise les déploiements development avec le groupe de concurrence development-coolify-deploy, ce qui garde l'environnement prévisible pendant que les nouvelles runs attendent la fin du déploiement en cours.

Gardez l'origine development privée. Préférez un hostname Tailscale-only ou activez HTTP Basic au niveau de l'app Coolify tout en renvoyant X-Robots-Tag: noindex, nofollow, noarchive. Le smoke test part du runner auto-hébergé avec les secrets Basic Auth development; ce runner doit donc atteindre l'URL protégée.

Socle Production

Ces valeurs sont requises avant qu'un déploiement production puisse servir l'app correctement:

Réglages optionnels de pool base:

Base De Données

DATABASE_URL est requis par le runtime applicatif, les scripts setup, les seeds et les opérations Drizzle.

Pour le déploiement Coolify auto-hébergé, la synchronisation de schéma et les seeds production tournent dans le service Compose migrate avant le démarrage de l'app et du worker. Gardez le DATABASE_URL production dans Coolify ou le secret store de l'orchestrateur afin que l'étape de setup résolve les noms de services Docker internes comme postgres.

Pour les fournisseurs hébergés qui n'exécutent pas la pile Compose auto-hébergée, lancez l'opération de schéma Drizzle choisie depuis un runner capable d'atteindre la base production avant de promouvoir la nouvelle version.

Pour les fournisseurs Postgres hébergés:

1. Créez la base production.
2. Ouvrez le panneau des connection strings.
3. Copiez la connection string poolée lorsqu'elle existe.
4. Stockez-la comme DATABASE_URL dans Vercel Production et Preview, ou dans le secret store auto-hébergé.
5. Utilisez une base de développement séparée pour Vercel Development, .env.local local ou .env.self-host.

Si le fournisseur expose des URL directes et poolées, préférez l'URL poolée pour les fonctions Vercel. L'app utilise déjà un pool production conservateur de trois connexions par runtime afin d'éviter d'épuiser les limites serverless.

Hôte Canonique Et Auth

Définissez:

NEXT_PUBLIC_BASE_URL=https://yayaw.app
BETTER_AUTH_TRUSTED_ORIGINS=https://*.yayaw.app,https://*.vercel.app

NEXT_PUBLIC_BASE_URL pilote les URL canoniques, l'URL de base Better Auth, les métadonnées OAuth, les liens sitemap/robots et les URL absolues de ressources.

Ne définissez pas NEXT_PUBLIC_SITE_URL; l'application ne le lit pas. Ne définissez pas BETTER_AUTH_URL pour les nouveaux déploiements; Better Auth reçoit son URL de base depuis NEXT_PUBLIC_BASE_URL.

Le domaine de prévisualisation branch-backed est https://preview.yayaw.app et suit la branche durable preview.

Les hôtes .eu retirés peuvent rester attachés uniquement comme redirections Vercel 308 vers leurs remplaçants .app, comme yayaw.eu et www.yayaw.eu vers yayaw.app. Ils ne doivent pas servir de trafic dashboard/auth ni figurer dans BETTER_AUTH_TRUSTED_ORIGINS.

Stripe Billing

Stripe a trois secrets requis lorsque la facturation est activée:

Créez deux endpoints webhook Stripe pour la production:

https://yayaw.app/api/auth/stripe/webhook
https://yayaw.app/api/billing/stripe/webhook

Utilisez le signing secret du premier endpoint pour STRIPE_WEBHOOK_SECRET et celui du second pour STRIPE_ONE_TIME_WEBHOOK_SECRET. Ne réutilisez pas le secret d'un endpoint pour l'autre.

L'endpoint abonnement doit recevoir les événements de checkout abonnement et de cycle de vie billing. L'endpoint one-time a seulement besoin de checkout.session.completed pour les achats lifetime.

Les prix des produits de facturation sont gérés depuis /dashboard/admin/billing-products ou via le plan de contrôle MCP. Les Stripe Price IDs sont stockés en base après synchronisation catalogue; ce ne sont pas des secrets de déploiement.

Liens Livrables D'Accès Au Code

Ces valeurs sont des URL non secrètes optionnelles affichées sur /dashboard/organization/code-access après un achat payant qui débloque l'accès au code:

Laissez une valeur vide lorsque le livrable requiert un provisioning manuel.

GitHub Code Access

L'accès dépôt production doit utiliser une GitHub App, pas un personal access token. L'app permet à Yayaw d'inviter les clients payants dans le dépôt configuré avec l'accès lecture seule pull, sans stocker les identifiants GitHub d'un utilisateur humain.

Créer La GitHub App

Créez l'app depuis le compte qui possède le dépôt privé:

GitHub organization -> Settings -> Developer settings -> GitHub Apps -> New GitHub App

Valeurs recommandées:

Permissions de dépôt:

Administration: Read and write est requis car Yayaw appelle l'API GitHub collaborators pour inviter le username demandé dans le dépôt. L'app n'a pas besoin de permission Contents pour le flux actuel: le client reçoit l'accès dépôt normal via son propre compte GitHub.

Installer La GitHub App

Après création:

1. Générez une clé privée depuis les réglages de l'app et téléchargez le .pem.
2. Installez l'app sur le compte ou l'organisation propriétaire.
3. Sélectionnez uniquement le dépôt auquel les clients payants doivent accéder.
4. Copiez l'App ID depuis les réglages.
5. Copiez l'installation ID depuis l'URL d'installation.

L'URL d'installation ressemble généralement à ceci pour une organisation:

https://github.com/organizations/Yayaw-eu/settings/installations/12345678

Le segment numérique final est l'ID d'installation de la GitHub App.

Stocker Le Secret GitHub App

Stockez la clé privée dans l'environnement cible. Pour Vercel:

vercel env add BILLING_CODE_ACCESS_GITHUB_APP_PRIVATE_KEY production
vercel env add BILLING_CODE_ACCESS_GITHUB_APP_PRIVATE_KEY preview

Le dashboard Vercel est l'endroit le plus sûr pour coller une valeur PEM multiligne avec le fournisseur hébergé. Pour un .env.local ou fichier secret auto-hébergé, collez la clé multiligne entre guillemets ou échappez les sauts de ligne sur une ligne:

printf 'BILLING_CODE_ACCESS_GITHUB_APP_PRIVATE_KEY="%s"\n' "$(perl -0pe 's/\n/\\n/g' yayaw-code-access.pem)" >> .env.local

Le runtime accepte les séquences \n échappées et les reconvertit en vrais sauts de ligne avant de signer le JWT GitHub App. Si une plateforme aplatit le PEM en une ligne avec des espaces entre header, body et footer, Yayaw le normalise en PEM au runtime.

Configurer Les Valeurs Non Secrètes GitHub

Préférez l'UI admin pour les valeurs non secrètes:

/dashboard/admin/billing-settings

Définissez:

Des replis d'environnement existent pour les déploiements qui ont besoin de config au démarrage:

BILLING_CODE_ACCESS_GITHUB_REPOSITORY=Yayaw-eu/yayaw
BILLING_CODE_ACCESS_GITHUB_APP_ID=123456
BILLING_CODE_ACCESS_GITHUB_APP_INSTALLATION_ID=12345678
BILLING_CODE_ACCESS_GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"

Repli Token Local Ou Staging

Utilisez BILLING_CODE_ACCESS_GITHUB_TOKEN uniquement pour les environnements locaux ou staging sans GitHub App:

BILLING_CODE_ACCESS_GITHUB_REPOSITORY=Yayaw-eu/yayaw
BILLING_CODE_ACCESS_GITHUB_TOKEN=github_pat_...

Le propriétaire du token doit pouvoir ajouter des collaborateurs au dépôt. Pour un token fine-grained, accordez l'accès au seul dépôt cible et incluez la permission d'administration de dépôt nécessaire aux invitations. N'utilisez pas ce repli en production sauf contournement d'incident avec plan de rotation.

E-mail

RESEND_API_KEY active les e-mails transactionnels d'invitation, reset, magic link et facturation.

Pour la récupérer:

1. Vérifiez le domaine d'envoi dans Resend pour l'e-mail production.
2. Créez une clé API server-side dans Resend.
3. Stockez-la comme RESEND_API_KEY dans l'environnement cible.
4. Envoyez un e-mail de test depuis la surface admin des e-mails transactionnels après déploiement.

Définissez EMAIL_SENDER sur un expéditeur vérifié du domaine Resend, par exemple team@yayaw.app. Définissez EMAIL_SUPPORT sur l'adresse support affichée dans les modèles et EMAIL_USERNAME sur le nom affiché. Ces variables sont des défauts bootstrap et replis; après la première connexion admin, Admin > Site Settings > Email est prioritaire au runtime.

L'absence de RESEND_API_KEY ne casse pas le traitement des webhooks de facturation, mais ignore les e-mails transactionnels.

Fournisseurs OAuth

Ces valeurs sont optionnelles et requises uniquement lorsque le fournisseur correspondant est activé:

Utilisez l'origine production de NEXT_PUBLIC_BASE_URL lors de la configuration des redirect URIs OAuth.

Object Storage

Le stockage média est optionnel jusqu'à l'utilisation d'upload, miniatures, logos ou génération d'images. Utilisez STORAGE_PROVIDER=supabase pour le chemin Supabase hébergé ou STORAGE_PROVIDER=s3 pour MinIO, S3, R2 ou un autre fournisseur compatible S3. Lorsque le fournisseur est vide, Supabase est choisi si les variables Supabase sont présentes; sinon S3 est choisi si l'ensemble S3 est complet.

Variables communes:

Pour un stockage S3 same-origin ou derrière CDN, proxifiez chaque préfixe de bucket public vers le stockage objet avant le repli app. Les buckets publics intégrés sont /media/* pour les médias téléversés et /organization-logos/* pour les logos d'organisation. Si STORAGE_PUBLIC_BASE_URL pointe directement vers une origine de stockage objet dédiée, cette origine doit servir les mêmes chemins /<bucket>/<key>.

Pendant le setup, bun run seed téléverse les ressources par défaut de variables globales de site dans le bucket média sous global/site-variables/* et écrit ces URL publiques dans l'entrée site-variables/main. Les URL de ressources personnalisées existantes sont préservées lorsque le seed est relancé.

Variables Supabase:

Variables de stockage compatible S3:

N'exposez jamais SUPABASE_SERVICE_ROLE_KEY, S3_ACCESS_KEY_ID ou S3_SECRET_ACCESS_KEY au navigateur ni dans une variable NEXT_PUBLIC_*.

Domaines Publics

Les domaines publics d'organisation utilisent PUBLIC_DOMAIN_PROVIDER.

manual-dns génère un challenge TXT de propriété et vérifie le DNS public. Il n'automatise ni les changements chez le fournisseur DNS ni l'émission de certificats TLS.

OpenAI

Les fonctions de génération IA requièrent:

OPENAI_API_KEY=

Créez la clé depuis la page API keys de la plateforme OpenAI et stockez-la côté serveur dans l'environnement cible. Elle active le repli IA de composants, Page AI et la génération d'images lorsque les feature flags et réglages runtime correspondants sont actifs.

Toggles runtime IA optionnels:

Analytics

Choisissez un fournisseur analytics et un mode de capture:

NEXT_PUBLIC_ANALYTICS_PROVIDER=umami
NEXT_PUBLIC_ANALYTICS_CAPTURE_MODE=hybrid

Fournisseurs supportés: posthog, umami, none. Le mode de capture peut être hybrid, server ou client. hybrid est le défaut et enregistre des événements facturation/auth fiables côté serveur tout en gardant l'analytics produit navigateur. server ne rend pas de scripts analytics navigateur et envoie les vues CMS plus les conversions depuis le serveur applicatif. client conserve la capture uniquement navigateur.

Les événements de conversion serveur incluent checkout_started, purchase_completed, subscription_started, subscription_updated, subscription_cancel_scheduled, subscription_canceled et payment_failed. Les événements de facturation incluent revenue, value, currency, plan, product_key et les IDs Stripe pour la réconciliation. Les événements Stripe en mode test sont suivis avec billing_mode=test et is_test_data=true, mais ne comptent pas comme conversion, revenue ou value sauf activation du réglage admin Track Stripe Test Billing Analytics. Le montant test original reste dans test_amount_cents et test_revenue pour le débogage.

PostHog

La capture client et les feature flags utilisent les valeurs PostHog publiques:

NEXT_PUBLIC_POSTHOG_KEY=
NEXT_PUBLIC_POSTHOG_HOST=https://eu.i.posthog.com
NEXT_PUBLIC_POSTHOG_ENABLE_LOCAL=false

Les analytics dashboard côté serveur utilisent les valeurs PostHog privées:

POSTHOG_PERSONAL_API_KEY=
POSTHOG_PROJECT_ID=
POSTHOG_API_HOST=https://eu.posthog.com
POSTHOG_ORG_ID_PROPERTY=organization_id
POSTHOG_FLAG_LOOKUP_TIMEOUT_MS=

Récupérez la clé projet publique et l'ID projet depuis les réglages PostHog. Créez une personal API key avec l'accès suffisant à l'API Query et stockez-la comme POSTHOG_PERSONAL_API_KEY. Gardez POSTHOG_ORG_ID_PROPERTY=organization_id sauf changement de la propriété d'événement analytics dans le produit. Définissez POSTHOG_FLAG_LOOKUP_TIMEOUT_MS uniquement si les lookups de feature flags PostHog côté serveur ont besoin d'un timeout différent du défaut 1500 millisecondes.

Umami

La capture client utilise les valeurs Umami publiques:

NEXT_PUBLIC_UMAMI_HOST_URL=https://analytics.example.com
NEXT_PUBLIC_UMAMI_SCRIPT_URL=
NEXT_PUBLIC_UMAMI_WEBSITE_ID=
NEXT_PUBLIC_UMAMI_DOMAINS=
NEXT_PUBLIC_UMAMI_AUTO_TRACK=true

Les lectures dashboard côté serveur et la capture serveur utilisent les valeurs Umami privées:

UMAMI_API_URL=https://analytics.example.com
UMAMI_WEBSITE_ID=
UMAMI_API_TOKEN=
UMAMI_API_KEY=
UMAMI_USERNAME=
UMAMI_PASSWORD=
UMAMI_CMS_EVENT_PAGE_SIZE=1000

Utilisez soit UMAMI_API_TOKEN (ou l'alias legacy UMAMI_API_KEY), soit UMAMI_USERNAME plus UMAMI_PASSWORD pour les lectures de données dashboard. La capture d'événements serveur utilise Umami /api/send; elle a donc seulement besoin de UMAMI_API_URL et UMAMI_WEBSITE_ID.

Plan De Contrôle MCP

Le MCP production ne requiert pas de variable d'environnement dans le runtime applicatif. Les clients se connectent à /api/mcp avec une clé API Better Auth ou un access token OAuth.

Les tests stdio locaux peuvent utiliser:

YAYAW_MCP_API_KEY=
YAYAW_MCP_LOCAL_USER_ID=

Créez, inspectez et révoquez les clés MCP avec:

bun run mcp:key

Stockez les clés client de confiance hors du dépôt et passez-les au client comme YAYAW_MCP_API_KEY.

Mode Maintenance

Le mode maintenance est optionnel:

MAINTENANCE_MODE=false
MAINTENANCE_MODE_END_DATE=

Définissez MAINTENANCE_MODE=true uniquement lorsque l'app doit servir la surface de maintenance. Utilisez MAINTENANCE_MODE_END_DATE pour le contexte opérateur.

Métadonnées De Déploiement

Les déploiements Vercel reçoivent automatiquement les métadonnées runtime. Les déploiements auto-hébergés peuvent fournir des métadonnées statiques:

Checklist De Déploiement

Avant promotion:

1. L'environnement cible possède chaque variable requise de .env.example ou .env.self-host.example.
2. La prévisualisation a soit des valeurs fournisseurs équivalentes à la production, soit des valeurs staging explicites.
3. NEXT_PUBLIC_BASE_URL correspond à l'origine HTTPS publique de l'environnement.
4. Stripe a deux endpoints webhook et chaque secret d'endpoint est mappé à la variable correspondante.
5. L'accès au code GitHub a soit les réglages admin plus BILLING_CODE_ACCESS_GITHUB_APP_PRIVATE_KEY, soit les replis d'environnement explicites pour dépôt, App ID, installation ID et clé privée.
6. Les variables Resend, PostHog, Supabase/S3, OpenAI et OAuth ne sont présentes que lorsque ces fonctions sont activées.
7. Coolify ou l'orchestrateur possède le DATABASE_URL runtime utilisé par le service Compose migrate, et les environnements GitHub possèdent la valeur build-time DATABASE_URL requise par next build.
8. Un nouveau déploiement ou redémarrage de conteneur a été déclenché après la dernière modification de variable.
9. Lancez les barrières qualité locales avant de merger des changements de config de déploiement:

bun run check
bun run docs:generate
bun run docs:check-links
bun run docs:check-translations
bun run docs:llm:check
bunx tsc --noEmit
bun run build

Références Fournisseurs

• Vercel environment variables
• Vercel CLI environment commands
• Next.js self-hosting
• Next.js standalone output
• Docker Next.js guide
• Stripe API keys
• Stripe webhooks
• GitHub App registration
• GitHub App private keys
• GitHub repository collaborators API
• Resend API keys
• Supabase API keys
• Supabase self-hosting
• MinIO S3 compatibility
• OpenAI API authentication