Il progetto è nella sezione 5 di docs/architecture/23-ops.md. Vercel esegue solo il livello
web. Tutto il resto gira su un host companion gestito da te, e non è
facoltativo.
Stato in questa release
La configurazione è pronta (apps/web/vercel.json, il preset Nitro vercel
e i controlli di avvio). Vercel richiede storage file condiviso
(QUIRE_STORAGE_DRIVER=s3 oppure azure), un driver realtime che funzioni tra
istanze di funzione (QUIRE_REALTIME_DRIVER=sse oppure centrifugo) e un provider
email HTTP. Senza di essi il livello web rifiuta di avviarsi e il suo registro
nomina ciascuna impostazione mancante.
I componenti
Componente
Dove gira
web
Funzioni Vercel, runtime Node: pagine, REST, MCP, LTI, webhook ricevuti
worker, scheduler, collab, content
Un host companion: Fly, Railway, ECS oppure il tuo host Docker con docker/compose.yaml
Postgres
Esterno, dietro un pooler di transazioni: Neon, Supabase oppure RDS con PgBouncer
File
S3 o R2. Non c’è disco persistente
Job in background
Accodati con pg-boss dentro la transazione della richiesta, eseguiti dal worker companion. Con QUIRE_QUEUE_DRIVER=vercel sul worker companion, i job leggeri (consegne non ordinate di notifiche e webhook) passano per Vercel Queues (VERCEL_QUEUE_REGION, VERCEL_QUEUE_TOKEN), così il Postgres in pool non viene interrogato per essi
Job ricorrenti
Lo scheduler companion. Non c’è rotta Vercel Cron, perché un cron che lavora dentro una funzione va in timeout
Tracciamento
OpenTelemetry verso il tuo collector, OTEL_EXPORTER_OTLP_ENDPOINT
Cosa questo target non può fare
Il livello web verifica questi punti all’avvio e rifiuta, nominando ogni problema,
anziché fallire in seguito alla prima email mai inviata:
Niente SMTP. Vercel blocca l’SMTP in uscita. Imposta QUIRE_EMAIL_PROVIDER_CONFIG
su un provider HTTP (Postmark, SES, Mailgun, SendGrid o Resend).
QUIRE_SMTP_URL viene rifiutato.
Niente disco locale.QUIRE_STORAGE_DRIVER=local viene rifiutato.
Niente memoria condivisa tra invocazioni.QUIRE_REALTIME_DRIVER=inprocess
viene rifiutato. Gli eventi server-sent sono limitati al timeout della funzione; il
client si riconnette con un cursore, così nessun evento va perso, ma la presenza non è
disponibile.
I database tenant fissati sono limitati a circa otto, perché ciascuno è
un altro pool di connessioni in un ambiente che non può condividerli.
Distribuzione
Crea un progetto Vercel dal repository con Directory radiceapps/web. apps/web/vercel.json imposta i comandi di installazione e build
(NITRO_PRESET=vercel) e serve /sw.js senza cache.
Imposta le variabili d’ambiente. Da docker/.env.example, almeno:
QUIRE_DEPLOY_TARGET=vercel, QUIRE_APP_ORIGIN, QUIRE_CONTENT_ORIGIN,
QUIRE_PLATFORM_DOMAINS, QUIRE_SECRET_KEY, QUIRE_MASTER_KEY,
DATABASE_URL (l’indirizzo del pooler), QUIRE_REPORT_DATABASE_URL,
QUIRE_AUDIT_DATABASE_URL, QUIRE_DATABASE_ID,
QUIRE_EMAIL_PROVIDER_CONFIG, QUIRE_MAIL_FROM, le impostazioni di storage,
e QUIRE_COLLAB_URL e QUIRE_COLLAB_SIGNING_KEY che puntano al
servizio collab del companion.
QUIRE_REPORT_DATABASE_URL appartiene al database fisico nominato da
DATABASE_URL. Per ciascun database registrato aggiuntivo, aggiungi il suo
URL di connessione quire_report agli ambienti sia web sia worker, poi
registra il nome della sua variabile d’ambiente come env:NAME nella console
della piattaforma. Le analisi falliscono in modo chiuso se manca l’URL report di quel database.
Sull’host companion, esegui docker/compose.yaml senza il servizio web,
con lo stesso docker/.env:
Le migrazioni girano lì, prima che ogni distribuzione Vercel venga promossa.
Distribuisci. Con una configurazione rifiutata il registro della funzione inizia con “The web
tier did not start on vercel” ed elenca ciascuna impostazione da cambiare.
Aggiornamento
Migra prima dall’host companion, poi promuovi la nuova distribuzione Vercel,
poi fai rolling dei worker del companion: l’ordine in
upgrade.md. Un rollback istantaneo Vercel è un rollback di codice ed è
sempre sicuro all’interno di una release.
Quire