Guida operativa di produzione Emdash CMS su Cloudflare Free Tier

Pubblicato il 2026-04-08 di Emdash Cms Everything

Sintesi esecutiva

Puoi eseguire EmDash in produzione sul piano Cloudflare Free per i workflow core del CMS.
Ciò che devi accettare: l’esecuzione sandboxata dei plugin non è disponibile, quindi worker_loaders va rimosso dalla configurazione.

Questa guida è ottimizzata prima di tutto per la stabilità, non per la massima copertura funzionale.

Limiti delle capacità nel piano Free

Disponibile

• sito core EmDash e flussi admin
• dati contenuto su D1
• storage media su R2 (entro i limiti gratuiti)
• deploy e routing su Workers

Non disponibile

• Dynamic Workers per plugin sandboxati
• esecuzione runtime non fidata in stile marketplace plugin

Se il tuo lancio dipende dall’esecuzione sandboxata di plugin di terze parti, il piano Free non è sufficiente.

Checklist pre-deploy

Completa tutti i controlli prima di eseguire i comandi di deploy:

• Wrangler è autenticato (wrangler login già eseguito)
• il progetto compila in locale senza assunzioni valide solo in cloud
• wrangler.jsonc ha binding D1 e R2 allineati alla configurazione runtime
• la voce worker_loaders è rimossa per il piano Free
• la scelta del package manager è coerente (npm o pnpm, senza mix)

Ordine di provisioning delle risorse

Esegui il provisioning in questo ordine esatto per ridurre il churn dei binding:

1. Crea il database D1
2. Crea o abilita R2 e poi crea il bucket
3. Aggiorna wrangler.jsonc con nomi e ID esatti
4. Compila e distribuisci il Worker

Motivo: l’ID D1 e i nomi dei bucket diventano la tua fonte di verità per i binding ambientali.

# Esegui prima il provisioning di D1
npx wrangler d1 create your-db-name

# Poi esegui il provisioning del bucket R2
npx wrangler r2 bucket create your-media-bucket

Struttura minima di wrangler.jsonc per il piano Free

Lo scheletro seguente è intenzionalmente minimale:

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "your-site-name",
  "main": "./src/worker.ts",
  "compatibility_date": "2026-04-08",
  "compatibility_flags": ["nodejs_compat"],
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "your-db-name",
      "database_id": "replace-with-d1-id"
    }
  ],
  "r2_buckets": [
    {
      "binding": "MEDIA",
      "bucket_name": "your-media-bucket"
    }
  ]
}

Nessuna sezione worker_loaders nel piano Free.

Flusso di build e deploy

Esegui i comandi dalla root del progetto EmDash:

# scegli un package manager e mantienilo
npm run build
npm run deploy

Se il tuo progetto usa pnpm:

pnpm build
pnpm deploy

Evita di usare npm e pnpm insieme nella stessa sessione di deploy, a meno che i lockfile non siano sincronizzati intenzionalmente.

Checklist di validazione post-deploy

Valida in questo ordine:

1. l’URL frontend risponde e restituisce i contenuti attesi
2. l’URL admin (/_emdash/admin) è raggiungibile
3. la prima configurazione admin si completa con successo
4. crea e pubblica un elemento di test
5. carica un file media e conferma il recupero

Un deploy non è completo finché i percorsi di scrittura dati non sono verificati, non basta la sola raggiungibilità delle route.

Errori frequenti e correzioni più rapide

Errore: il deploy riesce, ma l’admin non si inizializza

Causa probabile: mismatch dei binding tra integrazione runtime e wrangler.jsonc.

Percorso di correzione:

1. verifica che i nomi dei binding (DB, MEDIA) siano identici ovunque
2. ridistribuisci dopo aver corretto la configurazione
3. riprova l’inizializzazione admin

Errore: comando R2 bloccato da prompt account

Causa probabile: R2 non è ancora stato abilitato nella dashboard.

Percorso di correzione:

1. abilita R2 nella dashboard Cloudflare
2. accetta i termini di fatturazione (l’uso gratuito resta valido)
3. riesegui il comando di creazione bucket

Errore: runtime error legato ai plugin nel piano Free

Causa probabile: configurazione sandbox residua.

Percorso di correzione:

1. rimuovi worker_loaders
2. disabilita la configurazione plugin specifica per sandbox
3. ridistribuisci e ritesta

Strategia di rollback

Usa una policy di rollback conservativa:

• mantieni taggato l’ultimo commit di deploy noto come stabile
• se compare una regressione in produzione, ridistribuisci il commit precedente taggato
• rinvia modifiche a schema o plugin finché il traffico non si stabilizza

Operativamente, un rollback rapido è migliore di un hotfix profondo durante una finestra di incidente.

Quando passare da Free a Paid

Esegui l’upgrade solo quando è vera almeno una di queste condizioni:

• ti serve l’esecuzione sandboxata di plugin non fidati
• traffico o storage superano regolarmente i limiti gratuiti
• la governance richiede un isolamento runtime dei plugin più forte

Non fare l’upgrade per formulazioni UI ambigue nelle schermate di billing. Fai l’upgrade solo per esigenze funzionali concrete.