Déployer sur Cloudflare

Cloudflare Workers fournit un environnement d’exécution rapide et distribué mondialement pour EmDash. Ce guide couvre le déploiement avec D1 pour la base de données et R2 pour le stockage des médias.

Prérequis

• Un compte Cloudflare
• Wrangler CLI installé (npm install -g wrangler)
• Authentifié avec Cloudflare (wrangler login)

Configurer les Bindings

Créez wrangler.jsonc à la racine de votre projet avec les bindings D1 et R2. Wrangler provisionne les deux ressources lors du premier déploiement si elles n’existent pas déjà.

{
	"$schema": "node_modules/wrangler/config-schema.json",
	"name": "my-emdash-site",
	"compatibility_date": "2025-01-15",
	"compatibility_flags": ["nodejs_compat"],

	"d1_databases": [
		{
			"binding": "DB",
			"database_name": "emdash-db",
		},
	],

	"r2_buckets": [
		{
			"binding": "MEDIA",
			"bucket_name": "emdash-media",
		},
	],
}

Configurer EmDash

Mettez à jour votre configuration Astro pour utiliser D1 et R2 :

import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";
import emdash from "emdash/astro";
import { d1, r2 } from "@emdash-cms/cloudflare";

export default defineConfig({
	output: "server",
	adapter: cloudflare(),
	integrations: [
		emdash({
			database: d1({ binding: "DB" }),
			storage: r2({ binding: "MEDIA" }),
		}),
	],
});

Premier Démarrage

Les migrations de base de données s’exécutent automatiquement lors de la première requête après le déploiement, et à chaque démarrage ultérieur s’il y a quelque chose de nouveau à appliquer.

Si la base de données est vide (pas de collections) et que l’assistant de configuration n’a pas été complété, EmDash applique également un fichier seed au premier démarrage. Le seed est lu au moment de la compilation depuis .emdash/seed.json, le chemin dans package.json#emdash.seed, ou seed/seed.json — selon ce qui est trouvé en premier — et intégré dans le bundle. Si aucun n’est présent, un seed par défaut intégré est utilisé. Les déploiements ultérieurs contre une base de données existante laissent son contenu intact.

Déployer

Déployez sur Cloudflare Workers :

wrangler deploy

Votre site est maintenant en ligne à https://my-emdash-site.<your-subdomain>.workers.dev.

Read Replicas

Pour les sites distribués mondialement, activez la réplication en lecture D1 pour router les requêtes de lecture vers des réplicas proches au lieu de toujours solliciter la base de données principale. Cela réduit considérablement la latence pour les visiteurs éloignés de la région principale.

emdash({
	database: d1({
		binding: "DB",
		session: "auto",
	}),
	storage: r2({ binding: "MEDIA" }),
}),

Vous devez également activer la réplication en lecture sur la base de données D1 elle-même dans le tableau de bord Cloudflare ou via l’API REST.

Voir Options de Base de Données — Read Replicas pour les modes de session et le fonctionnement de la cohérence basée sur les signets.

Domaine Personnalisé

Ajoutez un domaine personnalisé dans le tableau de bord Cloudflare :

1. Allez dans Workers & Pages > votre worker
2. Cliquez sur Custom Domains > Add Custom Domain
3. Entrez votre domaine et suivez les instructions de configuration DNS

Accès Public R2

Pour servir les médias directement depuis R2 (recommandé pour les performances) :

1. Dans le tableau de bord Cloudflare, allez dans R2 > votre bucket
2. Cliquez sur Settings > Public access
3. Activez l’accès public et notez l’URL publique
4. Mettez à jour votre configuration de stockage :

storage: r2({
  binding: "MEDIA",
  publicUrl: "https://pub-xxx.r2.dev"
}),

Authentification Cloudflare Access

Si votre organisation utilise Cloudflare Access, vous pouvez l’utiliser comme fournisseur d’authentification au lieu des passkeys, offrant une authentification unique via votre fournisseur d’identité existant. La configuration suivante l’active :

emdash({
  database: d1({ binding: "DB" }),
  storage: r2({ binding: "MEDIA" }),
  auth: access({
    teamDomain: "myteam.cloudflareaccess.com",
    audience: "your-app-audience-tag",
    roleMapping: {
      "Admins": 50,
      "Editors": 40,
    },
  }),
}),

Consultez le guide d’Authentification pour les options de configuration complètes.

Variables d’Environnement

Recommandé : clé de chiffrement

EMDASH_ENCRYPTION_KEY est la clé pour chiffrer les secrets des plugins au repos (tokens de webhook, clés Turnstile, etc.). La clé est validée au démarrage ; le chiffrement des secrets de plugins l’utilise une fois activé. Définissez-la à chaque déploiement pour que les secrets soient protégés sans modification de configuration ultérieure.

La clé est fournie par vous et n’est jamais stockée dans la base de données ; seul le texte chiffré l’est. La perdre signifie perdre chaque secret chiffré avec elle.

Générez une clé et stockez-la comme secret Worker avec les commandes suivantes :

npx emdash secrets generate
wrangler secret put EMDASH_ENCRYPTION_KEY

Optionnel : remplacements de valeurs stables

EmDash génère automatiquement le secret HMAC de prévisualisation et le sel de hachage IP des commentateurs et les persiste dans la base de données lors de la première utilisation. Les variables d’environnement ci-dessous sont des remplacements pour les cas où vous devez épingler la valeur vous-même — par exemple, lorsqu’un Worker de prévisualisation dans un processus séparé doit partager le secret avec votre site principal.

Accédez aux variables d’environnement dans votre configuration en utilisant import.meta.env ou le binding env de Cloudflare.

Déploiements de Prévisualisation

Déployez une branche de prévisualisation :

wrangler deploy --env preview

Ajoutez une section d’environnement à wrangler.jsonc :

{
	"env": {
		"preview": {
			"d1_databases": [
				{
					"binding": "DB",
					"database_name": "emdash-db-preview",
				},
			],
		},
	},
}

Dépannage

”D1 binding not found”

Vérifiez que le nom du binding dans wrangler.jsonc correspond à votre configuration de base de données :

// Must match: d1({ binding: "DB" })
"binding": "DB"

“R2 binding not found”

Vérifiez que le bucket R2 est correctement lié :

// Must match: r2({ binding: "MEDIA" })
"binding": "MEDIA"

Erreurs de migration

Si vous voyez des erreurs de schéma, suivez les logs du Worker (wrangler tail) et reproduisez l’erreur pour capturer le message sous-jacent — puis créez un issue avec cette sortie.