Onboarding Cliente

Playbook operativo per portare un nuovo tenant dal provisioning alla consegna. Presuppone che la postazione operatore sia già configurata (flo init, flo vps setup <name>, flo cf setup, flo control login dove si usa il control plane) — vedi Deploy Multi-Tenant (Flo CLI) per i prerequisiti infrastrutturali.

Convenzione dei domini

Ogni cliente corrisponde a una zona più uno slug cliente. Gli host sono role-first e a singola etichetta; i sottodomini a due livelli sono rifiutati alla creazione:

Ruolo	Forma in zona condivisa	Gestito da
api	api-<slug>.<zona>	VPS di produzione (Docker/Traefik)
app	app-<slug>.<zona>	Cloudflare Pages
strapi	strapi-<slug>.<zona>	VPS Strapi (se si aggiunge un CMS)
cdn	cdn-<slug>.<zona>	Cloudflare R2 (dominio dedicato)

1. Provisioning

Il provisioning generico dei clienti non è esposto tramite il registry del control-plane --vps. Esegui flo instance create da una postazione operatore contro il contesto VPS di destinazione (usa --local solo per un tenant locale). Il comando concatena: container backend e routing → progetto Cloudflare Pages con il record DNS api del backend e un deploy frontend iniziale → attesa finché il frontend è live.

# Tenant di produzione: backend + UI admin, frontend su dominio app dedicato
flo instance create \
  --domain api-acme.useflo.net \
  --frontend-domain app-acme.useflo.net \
  --customer-name "Acme Studio" \
  --customer-short ACME \
  --brand flo \
  --tag ghcr.io/team-ledges/flo:master \
  --no-seed \
  --with-backup -y

# Deploy da un branch CI invece di un'immagine fissata (attende la build GHCR)
flo deploy api-acme-useflo-net --branch master -y

Flag principali (vedi flo instance create --help):

Flag	Scopo
--domain <api-host>	Host backend; diventa il dominio del tenant e l'ID istanza
--frontend-domain <app-host>	Provisiona Cloudflare Pages con questo dominio dedicato
--no-custom-domain	Frontend raggiungibile solo su <project>.pages.dev; CORS limitato a quell'origine
--tag <image>	Immagine backend; …:master fa compilare anche il frontend da master
--branch <branch>	Compila l'immagine da un branch (predefinito develop; solo target di test)
--no-seed	Salta i dati demo di seed (predefinito di produzione)
--with-backup	Pianifica il backup GFS standard con un'esecuzione immediata di verifica
--local-storage	Usa il filesystem locale invece di R2
--no-start	Provisiona la configurazione senza avviare i container

La procedura guidata interroga <project>.pages.dev e riporta live / in compilazione. Verifica:

flo instance health api-acme-useflo-net     # health approfondito: container, API, DB, cert, backup, commerce
flo cf dns check api-acme.useflo.net        # record CF · delega · NS · resolver
flo logs app api-acme-useflo-net -f

flo instance health include un controllo Commerce readiness: disabled è sano mentre enable_online_payments è spento; una volta abilitati i pagamenti, un provider o una configurazione fatture mancante è riportata come not ready.

Per testare in locale il sito di un cliente, flo instance create-with-website crea un'istanza locale e collega un repo sito (emette un token API pubblico, registra l'origine dev nel CORS, abilita i feature flag pubblici, scrive environment.local.ts e serve il playground /tests del boilerplate):

flo instance create-with-website --domain api-demo.useflo.net --website ../Ledges.WEBSITE-ng -y

2. Configurazione istanza

flo config env set api-acme-useflo-net KEY VALUE [--restart]
flo config env set api-acme-useflo-net A=1 B=2 C=3 --restart
flo config env show api-acme-useflo-net [--reveal]
flo config env copy source-instance api-acme-useflo-net

env set scrive il .env del tenant (0600) e riavvia solo con --restart. I segreti sono mascherati da show salvo --reveal. Vedi Variabili d'Ambiente per l'elenco completo delle chiavi.

Dominio e TLS:

# Sposta un host backend (migra volumi, routing e config) — alternativa interattiva: flo config domain <id>
flo instance rename api-acme-useflo-net api-acme2.useflo.net -y

# Dominio frontend dedicato sul progetto CF Pages
flo cf domain add api-acme-useflo-net app-acme.useflo.net
flo cf domain swap api-acme-useflo-net app-acme2.useflo.net

# Cloudflare / DNS / TLS
flo cf setup
flo cf ssl app-acme.useflo.net
flo cf dns set api-acme.useflo.net <ip> --type A
flo config ssl origin useflo.net                 # Cert wildcard Cloudflare Origin CA
flo config ssl install cert.pem key.pem --domain useflo.net
flo config ssl status

3. Feature flag

flo config flags show api-acme-useflo-net
flo config flags set api-acme-useflo-net enable_bookings on
flo config flags set api-acme-useflo-net enable_email_sender on

Usa la forma dichiarativa set; flo config flags toggle rifiuta i flag critici per la sicurezza enable_email_sender e enable_login. I flag sono in cache per 60 secondi. Dipendenze da rispettare:

• enable_online_payments richiede enable_bookings e enable_einvoicing.
• enable_subscriptions non può essere spento una volta che _system_subscriptions_cutover è attivo.
• [enable_native_blog, enable_blogs] sono mutuamente esclusivi.

La UI admin (Impostazioni > Feature Flag) salva in blocco la stessa lista. Catalogo completo: Feature Flag.

4. Email

Scegli un percorso transazionale per tenant:

# Amazon SES (password via prompt nascosto o stdin rediretto, mai su argv)
flo config email ses api-acme-useflo-net \
  --region eu-south-1 --username AKIA… --from noreply@useflo.net --probe --restart

# Sweego SMTP (transazionale)
flo config email sweego api-acme-useflo-net \
  --host smtp.sweego.io --username flo --from noreply@useflo.net --probe

# Cloudflare Email Service (basato su API)
flo config env set api-acme-useflo-net \
  EMAIL_SENDER_EMAIL_PROVIDER=Cloudflare \
  CF_EMAIL_ACCOUNT_ID=… CF_EMAIL_API_TOKEN=… \
  EMAIL_SENDER_EMAIL_ALIAS=newsletter@useflo.net --restart

Poi abilita l'invio e verifica:

flo config flags set api-acme-useflo-net enable_email_sender on
flo instance email api-acme-useflo-net status
flo instance email api-acme-useflo-net sink --recipient you@example.com   # redirige tutti gli invii durante i test
flo instance email api-acme-useflo-net sink --clear

Il bulk newsletter usa una selezione provider separata; per Sweego: flo instance sweego api-acme-useflo-net set --api-key … --from …. Provider, template e log di consegna sono documentati in Configurazione Email.

5. Branding

Il branding ha due livelli: i temi brand incorporati (Flo / RespiraStudio, rilevamento brand a runtime) e l'overlay whitelabel per tenant. Vedi l'architettura branding in Tematizzazione Multi-Brand.

# Nome cliente visualizzato (registry + .env del tenant)
flo instance set-customer api-acme-useflo-net --name "Acme Studio" --short ACME --restart

# Asset whitelabel (alias: flo config wl)
flo config theme upload api-acme-useflo-net ./logo.svg --name LOGO.svg
flo config theme upload api-acme-useflo-net ./background.webp
flo config theme ls api-acme-useflo-net
flo config theme clone source-instance api-acme-useflo-net

# Branding login / impostazioni registrazione (su DB, stato condiviso con la UI Whitelabel)
flo config branding set api-acme-useflo-net \
  --enable-login --logo /uploads/whitelabeling/LOGO.svg \
  --background /uploads/whitelabeling/background.webp --background-type image

La UI branding su DB è vincolata da enable_whitelabel.

6. Pagamenti e fatturazione elettronica

Se il cliente vende online, configura il provider di pagamento e il gateway SDI prima di abilitare i flag:

flo instance payments api-acme-useflo-net \
  --stripe-secret-key sk_live_… --stripe-webhook-secret whsec_… \
  --invoice-seller-vat … --invoice-seller-name … \
  --e-invoicing-provider FatturaApi --e-invoicing-environment Test \
  --fatturaapi-username … --fatturaapi-password … \
  --admin-email admin@acme.example \
  --enable-flags --test-connection

Valida prima sull'ambiente Test, poi passa a Prod. Conferma che i controlli di readiness siano verdi (flo instance payments <id> o flo instance health <id>). Procedura completa: Configurazione Pagamenti e Fatturazione Elettronica.

7. Analytics

Prerequisito di flotta (una tantum, sulla postazione operatore): provisiona il service account Google e imposta GOOGLE_ANALYTICS_SA_JSON sull'istanza.

flo config web-analytics setup-gcp [api-acme-useflo-net]
flo config web-analytics set api-acme-useflo-net \
  --ga4-property <numeric-id> --gsc-site sc-domain:acme.example \
  --vertical website --enabled on
flo config web-analytics status api-acme-useflo-net
flo config web-analytics backfill api-acme-useflo-net

Abilita enable_web_analytics (dashboard rivolta al cliente) ed eventualmente enable_external_web_analytics (card home con link esterni). Guide di setup: Setup GA4 e Modulo Web Analytics.

8. Pianificazione backup

flo backup schedule api-acme-useflo-net --bucket flo-api-acme-useflo-net-backups --run-now -y
flo backup status api-acme-useflo-net
flo backup schedule api-acme-useflo-net --disable

La pianificazione è un'esecuzione GFS giornaliera (cron predefinito 0 3 * * *, livelli daily/weekly/monthly) caricata sul bucket R2 del tenant; sui tenant di produzione il lifecycle 7/30/90 giorni è applicato automaticamente. --run-now esegue un backup immediato di verifica. Sulla forma remota del control-plane --run-now è obbligatorio, e backup set-bucket / backup retention girano lato operatore. Vedi Backup per dettagli su ripristino, retention e cifratura.

9. Checklist di consegna

• flo instance health <id> — tutti i controlli passano (container, API, DB, cert OIDC, freschezza backup, commerce dove applicabile).
• Frontend raggiungibile sul dominio dedicato (o pages.dev) e flo cf dns check pulito.
• Certificato TLS valido (flo config ssl status) e modalità SSL Cloudflare corretta (flo cf ssl <domain>).
• Nome visualizzato cliente ed etichetta breve impostati (flo instance set-customer).
• Feature flag richiesti attivi, dipendenze soddisfatte (flo config flags show <id>).
• Provider email configurato, enable_email_sender attivo, messaggio di test ricevuto, sink svuotato.
• Asset whitelabel caricati e branding login impostato (se richiesto).
• Pagamenti e fatturazione elettronica configurati, readiness verde, una transazione end-to-end di test verificata (chiavi sandbox / ambiente Test).
• ID web analytics configurati e stato ETL sano (se richiesto).
• Backup GFS pianificato ed esecuzione immediata verificata (flo backup status <id>).
• Utenti demo/test rimossi e account admin del cliente confermato.
• Credenziali e URL admin consegnati tramite il canale sicuro concordato.