Riferimenti tecnici

Questa sezione è rivolta principalmente a sviluppatori e ops. Raccoglie i riferimenti necessari per integrare il Tenant Manager con altri sistemi, configurare nuove istanze e diagnosticare problemi a basso livello.

---

Repository

Repository	Path GitLab	Descrizione
Tenant Manager	opencity-labs/area-personale/tenant-manager	Sorgente principale: backend Go, frontend JS, hook PocketBase, migrazioni
Windmill Platform	opencity-labs/core-services/windmill-platform	Workflow di provisioning e deploy per il workspace platform

---

API PocketBase

Il Tenant Manager espone le API standard di PocketBase su tutte le sue collezioni. Le API sono accessibili con autenticazione tramite token Bearer.

Autenticazione:

# Ottenere un token con email + password (account applicativo)
curl -s -X POST https://<TM_URL>/api/collections/users/auth-with-password \
  -H "Content-Type: application/json" \
  -d '{"identity": "<email>", "password": "<password>"}'
# → restituisce {"token": "...", "record": {...}}

Endpoint principali:

Operazione	Metodo	Path
Lista tenant	GET	/api/collections/tenants/records
Singolo tenant	GET	/api/collections/tenants/records/:id
Crea tenant	POST	/api/collections/tenants/records
Aggiorna tenant	PATCH	/api/collections/tenants/records/:id
Elimina tenant	DELETE	/api/collections/tenants/records/:id
Lista clienti	GET	/api/collections/customers/records
Lista applicativi	GET	/api/collections/apps/records
Lista schemi config	GET	/api/collections/config_schemas/records
Health check	GET	/api/health
Callback Windmill	PATCH	/api/webhook/windmill-callback

Filtri, ordinamento e expand:

PocketBase supporta query avanzate tramite parametri URL:

# Tenant attivi di tipo Atti Sicraweb
GET /api/collections/tenants/records
    ?filter=(app_name='integrazione-atti-sicraweb' && status='production')
    &expand=customer,organization
    &sort=-created

Per la documentazione completa delle API PocketBase: pocketbase.io/docs/api-records

---

Collezioni principali

Collezione	Contenuto	Note
tenants	Istanze applicative	Campo config contiene il JSON della configurazione Form.io
customers	Anagrafica clienti (enti)	Relazione 1:N con tenants
organizations	Anagrafica partner/reseller	Relazione opzionale con tenants
apps	Catalogo applicativi disponibili	Gestita dagli sviluppatori nel backoffice
config_schemas	Schemi Form.io per tipo applicativo	Versionati per app_name
state_transitions	Definizione macchina a stati	from_status, to_status, label
windmill_scripts	Mapping transizione → workflow Windmill	Per tipo applicativo e transizione
users	Utenti amministratori e applicativi	OAuth2 via Authentik + email/password

---

Variabili d'ambiente

Le variabili d'ambiente configurano il comportamento del Tenant Manager al deploy. Il file .env.example nel repository contiene l'elenco completo con i valori di default.

Variabili principali:

Variabile	Descrizione	Note
PB_URL	URL pubblico dell'istanza TM	Usato nella callback URL passata a Windmill
PB_SUPERUSER_EMAIL	Email superuser PocketBase	Solo per bootstrap iniziale e admin UI
PB_SUPERUSER_PASSWORD	Password superuser PocketBase	Non usare negli applicativi
PB_DEV	Abilita log verbosi	true in sviluppo, false in produzione
TM_AUTH_DISABLED	Disabilita OIDC (dev locale)	Mai true in produzione
TM_OIDC_CLIENT_ID	Client ID Authentik	—
TM_OIDC_CLIENT_SECRET	Client Secret Authentik	—
TM_OIDC_AUTH_URL	URL authorization endpoint Authentik	—
TM_OIDC_TOKEN_URL	URL token endpoint Authentik	—
TM_WINDMILL_BASE_URL	URL interno Windmill (server→server)	—
TM_WINDMILL_PUBLIC_URL	URL pubblico Windmill (link nella UI)	—
TM_WINDMILL_TOKEN	Token di autenticazione Windmill	—
TM_WINDMILL_WORKSPACE	Workspace Windmill da usare	Valore: platform
KAFKA_BROKERS	Broker Kafka (vuoto = Kafka disabilitato)	—
KAFKA_TOPIC_TENANTS	Topic Kafka per gli eventi tenant	Default: tenants
FORMIO_VALIDATOR_URL	URL del servizio di validazione Form.io	Vuoto = validazione disabilitata
TM_KAFKA_WS_URL	URL WebSocket per aggiornamenti real-time UI	—

---

Eventi Kafka

Il Tenant Manager pubblica eventi CloudEvents 1.0 sul topic configurato in KAFKA_TOPIC_TENANTS a ogni operazione CRUD sui tenant.

Tipi di evento:

ce_type	Quando viene pubblicato
it.opencity.platform.tenant.created	Creazione di un nuovo tenant
it.opencity.platform.tenant.updated	Aggiornamento di un tenant (incluse transizioni di stato)
it.opencity.platform.tenant.deleted	Eliminazione di un tenant

Struttura del messaggio:

{
  "entity": {
    "meta": {
      "id": "<uuid>",
      "created": "...",
      "updated": "..."
    },
    "data": {
      "app_name": "...",
      "status": "...",
      "config": { ... },
      ...
    }
  }
}

Schema JSON completo pubblicato su: https://schemas.opencityitalia.it/tenant-manager/tenant/v1.json

Documentazione AsyncAPI: pubblicata su GitLab Pages del repository Tenant Manager.

---

Windmill: workspace platform

I workflow del Tenant Manager risiedono nel workspace platform di Windmill. La convenzione di naming per i flow è:

f/tenant_manager/<nome_applicativo>_<azione>

Esempi:

• f/tenant_manager/chatbot_provision

• f/tenant_manager/integrazione_atti_sicraweb_deploy

• f/tenant_manager/pocketbase (resource con credenziali TM — non modificare)

Il subflow condiviso per la callback a PocketBase si trova in:

f/tenant_manager/finalize_transition

Tutti i workflow custom devono chiamare questo subflow in coda per finalizzare la transizione di stato. Non reimplementare la logica di callback.