Distribuire su Cloudflare

Cloudflare Workers offre un runtime veloce e distribuito a livello globale per EmDash. Questa guida illustra la distribuzione con D1 come database e R2 per lo storage dei media.

Prerequisiti

• Un account Cloudflare
• Wrangler CLI installato (npm install -g wrangler)
• Autenticato su Cloudflare (wrangler login)

Creare le risorse

1. Creare un database D1

wrangler d1 create emdash-db

Annota il database_id dall’output.

2. Creare un bucket R2

wrangler r2 bucket create emdash-media

3. Creare wrangler.jsonc

Crea wrangler.jsonc nella root del progetto:

{
	"$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",
			"database_id": "your-database-id",
		},
	],

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

Configurare EmDash

Aggiorna la configurazione Astro per D1 e 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" }),
		}),
	],
});

Eseguire le migrazioni

Genera e applica lo schema del database.

1. Esportare lo SQL dello schema

npx emdash init --database ./data.db

2. Applicare le migrazioni a D1

wrangler d1 migrations apply emdash-db

Senza file di migrazione, applica lo schema core direttamente:

wrangler d1 execute emdash-db --file=./node_modules/emdash/migrations/0001_core.sql

Distribuire

Distribuisci su Cloudflare Workers:

wrangler deploy

Il sito è online su https://my-emdash-site.<your-subdomain>.workers.dev.

Replica in lettura

Per siti distribuiti globalmente, abilita la replica in lettura D1 per instradare le query di lettura verso repliche vicine invece che sempre al database primario. Riduce sensibilmente la latenza per i visitatori lontani dalla regione primaria.

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

Devi anche abilitare la replica in lettura sul database D1 dalla dashboard Cloudflare o tramite API REST.

Vedi Opzioni database — Replica in lettura per le modalità di sessione e la coerenza basata su bookmark.

Dominio personalizzato

Aggiungi un dominio personalizzato nella dashboard Cloudflare:

1. Vai a Workers & Pages > il tuo worker
2. Clicca Custom Domains > Add Custom Domain
3. Inserisci il dominio e segui le istruzioni DNS

Accesso pubblico R2

Per servire i media direttamente da R2 (consigliato per le prestazioni):

1. Dashboard Cloudflare > R2 > il tuo bucket
2. Settings > Public access
3. Abilita l’accesso pubblico e annota l’URL pubblico
4. Aggiorna la configurazione di storage:

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

Autenticazione Cloudflare Access

Se la tua organizzazione usa Cloudflare Access, puoi usarlo come provider di autenticazione al posto dei passkey. Offre SSO con il tuo identity provider esistente.

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,
    },
  }),
}),

Vedi la guida all’autenticazione per tutte le opzioni.

Variabili d’ambiente

EmDash richiede alcuni secret per autenticazione e anteprima.

Secret obbligatori

Genera secret sicuri:

npx emdash auth secret

Imposta i secret con Wrangler:

wrangler secret put EMDASH_AUTH_SECRET
wrangler secret put EMDASH_PREVIEW_SECRET

Accedi alle variabili con import.meta.env o il binding env di Cloudflare.

Deploy di anteprima

Distribuisci un branch di anteprima:

wrangler deploy --env preview

Aggiungi una sezione ambiente in wrangler.jsonc:

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

Risoluzione dei problemi

«D1 binding not found»

Verifica che il nome del binding in wrangler.jsonc corrisponda alla configurazione del database:

// Deve corrispondere: d1({ binding: "DB" })
"binding": "DB"

«R2 binding not found»

Controlla che il bucket R2 sia collegato correttamente:

// Deve corrispondere: r2({ binding: "MEDIA" })
"binding": "MEDIA"

Errori di migrazione

Le migrazioni D1 passano da Wrangler, non a runtime. In caso di errori di schema:

1. Verifica che le migrazioni siano state applicate: wrangler d1 migrations list emdash-db
2. Riapplica se necessario: wrangler d1 migrations apply emdash-db