---
title: "Il livello web su Cloudflare Workers"
description: "Esegui un livello web Quire ridotto su Cloudflare Workers."
image: "https://docs.quirelms.com/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.quirelms.com/it/llms.txt
> Use this file to discover all available pages before exploring further.

# Il livello web su Cloudflare Workers

<span id="the-web-tier-on-cloudflare-workers"></span>

Il progetto è nella sezione 6 di `docs/architecture/23-ops.md`. Workers esegue un livello web
ridotto. La parità di funzionalità su Workers è fuori ambito (sezione 12 del PRD): ciò che
questo target non può fare viene rifiutato all'avvio, per nome.

## Stato in questa release <!--quire:status-in-this-release-->

La configurazione è pronta (`apps/web/wrangler.jsonc`, il preset Nitro
`cloudflare-module`, il bridge Hyperdrive e i controlli di
avvio). Un Worker richiede storage compatibile S3 per R2
(`QUIRE_STORAGE_DRIVER=s3`), un driver realtime tra richieste
(`QUIRE_REALTIME_DRIVER=durable_objects` oppure `centrifugo`), una cache condivisa
(`QUIRE_CACHE_DRIVER=postgres` oppure `valkey`) e un provider email HTTP.
Senza di essi il Worker rifiuta di avviarsi e il suo registro nomina ciascuna impostazione.
Il driver Durable Objects è un client del Worker realtime in
`apps/realtime-worker` (un Durable Object per canale per fan-out, presenza
e cronologia, uno per persona per le disconnessioni); distribuiscilo accanto, come sotto,
oppure usa Centrifugo.

## I componenti <!--quire:the-pieces-->

| Componente | Su Cloudflare |
| --- | --- |
| `web` | Un Worker con `nodejs_compat` |
| Postgres | Esterno, raggiunto tramite Hyperdrive: `HYPERDRIVE` per il ruolo applicativo, `REPORT_HYPERDRIVE` per il ruolo report sullo stesso database fisico. Il livello web copia ciascuna stringa di connessione in `DATABASE_URL` e `QUIRE_REPORT_DATABASE_URL` all'avvio |
| File | R2, tramite la sua API S3 (`S3_ENDPOINT=https://<account>.r2.cloudflarestorage.com`); il binding `FILES` collega il bucket |
| Job in background | pg-boss su Hyperdrive quando il job deve essere accodato con una scrittura. Con `QUIRE_QUEUE_DRIVER=cloudflare` sul worker companion, i job leggeri (consegne non ordinate di notifiche e webhook) passano invece per Cloudflare Queues, così Postgres non viene interrogato per essi. Il worker companion esegue entrambi |
| Realtime | Il Worker realtime, `apps/realtime-worker`, con Durable Objects |
| `worker`, `scheduler`, `collab`, `content`, ClamAV, Gotenberg, ffmpeg | Un host companion per contenitori. Un Worker non può eseguirli |
| Tracciamento | Osservabilità di Workers, abilitata in `wrangler.jsonc` |

`REPORT_HYPERDRIVE` fornisce il ruolo report per il database fisico nominato
da `HYPERDRIVE`. Questo target non serve tenant fissati ad altri
database fisici, come descritto sotto.

## Cosa questo target non può fare <!--quire:what-this-target-cannot-do-->

Rifiutato all'avvio, con ogni problema elencato in una volta sola:

- **Niente SMTP.** Usa un provider HTTP in `QUIRE_EMAIL_PROVIDER_CONFIG`.
- **Niente disco locale.** `QUIRE_STORAGE_DRIVER` deve nominare object storage.
- **Niente realtime o cache in-process.** I Worker non condividono memoria tra
  richieste, quindi `QUIRE_REALTIME_DRIVER=inprocess` e
  `QUIRE_CACHE_DRIVER=memory` vengono rifiutati.
- **Niente ClamAV, Gotenberg o ffmpeg nel Worker.** `CLAMAV_URL`,
  `GOTENBERG_URL` e `FFMPEG_PATH` impostati sul Worker vengono rifiutati; impostali invece sul
  worker companion.
- **Niente organizzazioni con database dedicato.** I binding Hyperdrive di un Worker sono
  fissati al deploy, quindi un'organizzazione con un proprio database riceve una chiara
  pagina "non disponibile qui". Servila da Compose o Vercel.

E una cosa non rifiutata ma da sapere: **prerendering e
rigenerazione statica incrementale non funzionano su Workers**, qualunque cosa dica la
documentazione del framework. Ogni rotta viene renderizzata per richiesta.

Su questo target mantieni brevi le transazioni e non trattenerne mai una durante una chiamata di
rete: Hyperdrive azzera lo stato di sessione quando una connessione torna al pool,
quindi il contesto tenant è impostato per transazione.

## Distribuzione <!--quire:deploying-->

1. Crea le risorse:
   ```sh
   bun run --bun wrangler hyperdrive create quire-app --connection-string="postgres://quire_app:...@db.example.com:5432/quire"
   bun run --bun wrangler hyperdrive create quire-report --connection-string="postgres://quire_report:...@db.example.com:5432/quire"
   bun run --bun wrangler r2 bucket create quire-files
   bun run --bun wrangler queues create quire-jobs
   ```
   Metti i due id Hyperdrive in `apps/web/wrangler.jsonc`.
2. Imposta i segreti, uno alla volta con `bun run --bun wrangler secret put <NAME>` da
   `apps/web`: `QUIRE_SECRET_KEY`, `QUIRE_MASTER_KEY`,
   `QUIRE_EMAIL_PROVIDER_CONFIG`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`,
   `QUIRE_COLLAB_SIGNING_KEY`, `QUIRE_REALTIME_WORKER_SECRET`. Le impostazioni semplici
   (`QUIRE_APP_ORIGIN`, `QUIRE_CONTENT_ORIGIN`, `QUIRE_PLATFORM_DOMAINS`,
   `QUIRE_DATABASE_ID`, `S3_ENDPOINT`, `S3_BUCKET`, `QUIRE_COLLAB_URL`) vanno in
   `vars`.
3. Compila e distribuisci da `apps/web`:
   ```sh
   NITRO_PRESET=cloudflare-module bun run build
   bun run --bun wrangler deploy
   ```
4. Distribuisci il Worker realtime, con il `QUIRE_REALTIME_WORKER_SECRET` del livello web
   e il suo segreto token come `QUIRE_REALTIME_TOKEN_SECRET` (il livello web firma
   i token realtime con il proprio `QUIRE_REALTIME_TOKEN_SECRET`, oppure con
   `QUIRE_SECRET_KEY` quando quello non è impostato, quindi usa quello che usa), e imposta
   `QUIRE_REALTIME_WORKER_URL` sul livello web al suo indirizzo:
   ```sh
   cd apps/realtime-worker
   bun run --bun wrangler secret put QUIRE_REALTIME_WORKER_SECRET
   bun run --bun wrangler secret put QUIRE_REALTIME_TOKEN_SECRET
   bun run --bun wrangler deploy
   ```
5. Per i job leggeri su Cloudflare Queues, crea una coda per coda leggera e
   imposta questi sul worker companion (un token API con lettura e
   scrittura Queues):
   ```sh
   bun run --bun wrangler queues create quire-events-notifications
   bun run --bun wrangler queues create quire-events-notifications-dead
   bun run --bun wrangler queues create quire-events-webhooks
   bun run --bun wrangler queues create quire-events-webhooks-dead
   ```
   `QUIRE_QUEUE_DRIVER=cloudflare`, `CLOUDFLARE_ACCOUNT_ID`,
   `CLOUDFLARE_QUEUES_TOKEN`, e `QUIRE_QUEUE_PREFIX` se non `quire-`.
6. Esegui l'host companion come nella [guida Vercel](/it/ops/vercel/), passaggio 3.
   Le migrazioni girano lì, prima di ogni distribuzione del Worker.

Una configurazione rifiutata si mostra in `bun run --bun wrangler tail` come "The web tier did
not start on cloudflare", seguita da ciascuna impostazione da cambiare.

Source: https://docs.quirelms.com/it/ops/cloudflare/index.mdx