Frontdoor
Sezioni

Installazione con Docker

Avvia Frontdoor con Docker Compose, con archiviazione persistente e accesso tramite Microsoft Entra.

In questa pagina

Frontdoor è distribuito come un singolo container con un database SQLite integrato. Express serve sia la web app sia l'API sulla porta 3001.

Requisiti

  • Docker con Docker Compose 2.24 o successivo (il file compose passa il tuo .env con env_file).
  • Una registrazione di app in Microsoft Entra con client ID, client secret e tenant ID, oppure la modalità demo locale descritta sotto. Vedi Configurazione di Microsoft Entra.
  • Una copia del repository di Frontdoor: l'immagine viene costruita da lì.

Provarlo in locale senza Entra

Il profilo demo non richiede né un file .env né una registrazione in Microsoft Entra:

docker compose -f docker-compose.demo.yml up --build

Apri http://localhost:3001 e usa il pannello Login Dev per accedere come owner, admin, admin_readonly o user. Il profilo demo usa un proprio volume di dati e pubblica la porta solo su 127.0.0.1.

Il Login Dev permette a chiunque di scegliere qualsiasi ruolo e firma i token con un secret di riserva pubblico. Non esporre mai questo profilo in rete e non metterlo dietro un reverse proxy. Per rimuoverlo:

docker compose -f docker-compose.demo.yml down -v

Configurare l'ambiente

Copia il file di esempio per Docker e inserisci i tuoi valori:

cp .env.example.docker .env

BASE_DOMAIN=frontdoor.contoso.com
FRONTEND_URL=https://frontdoor.contoso.com
AZURE_CLIENT_ID=00000000-0000-0000-0000-000000000000
AZURE_CLIENT_SECRET=your-client-secret
AZURE_TENANT_ID=00000000-0000-0000-0000-000000000000
AZURE_REDIRECT_URI=https://frontdoor.contoso.com/api/auth/microsoft/callback
JWT_SECRET=a-unique-random-value-of-at-least-32-characters
ADMIN_EMAILS=alice@contoso.com

ADMIN_EMAILS elenca gli owner, promossi in automatico quando accedono. Tutte le variabili sono descritte nel Riferimento della configurazione. PORT, DATABASE_PATH e le cartelle sotto /data sono impostati da docker-compose.yml e non si possono cambiare dal .env; NODE_ENV è sempre production, quindi il Login Dev è disattivato.

Avviare il container

docker compose up -d

Il primo avvio costruisce l'immagine. Apri il tuo FRONTEND_URL (oppure http://localhost:3001 sulla stessa macchina) e accedi con Microsoft. Se un valore obbligatorio manca o non è valido, il container si ferma all'avvio con un messaggio chiaro nei log:

docker compose logs frontdoor

Per registrare il commit nei backup, passalo al momento della build:

COMMIT_SHA=$(git rev-parse --short HEAD) docker compose build

Con un semplice docker build, usa invece --build-arg COMMIT_SHA=....

Dati persistenti

Tutti i percorsi scrivibili stanno sul volume frontdoor-data, montato su /data: il database (/data/frontdoor.db), gli avatar, le icone delle app, il branding e i file dei plugin. I dati sopravvivono agli aggiornamenti dell'immagine. Un healthcheck interroga /api/health ogni 30 secondi e il container si riavvia, a meno che non lo fermi tu.

Per preriscaldare la cache degli avatar degli utenti esistenti, esegui l'utility come utente dell'app, così i file in cache mantengono il proprietario corretto:

docker compose exec -u frontdoor frontdoor npm run avatars:prewarm

Per scaricare in questo modo le foto di Microsoft 365 serve il permesso Microsoft Graph ProfilePhoto.Read.All (vedi Configurazione di Microsoft Entra).

Checklist per la produzione

Imposta almeno:

  • BASE_DOMAIN e FRONTEND_URL
  • AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID e AZURE_REDIRECT_URI
  • un JWT_SECRET univoco di almeno 32 caratteri
  • ENTRA_GROUP_SYNC (true per impostazione predefinita in docker-compose.yml)
  • CORS_ALLOWED_ORIGINS solo se una pagina o un'app satellite su un'altra origine deve chiamare Frontdoor con le credenziali

Consigliati: ADMIN_EMAILS, ADMIN_API_KEY e JWT_EXPIRES_IN. Se davanti a Frontdoor c'è un reverse proxy, imposta un limite sulla dimensione delle richieste pari a BACKUP_MAX_UPLOAD_MB (predefinito 1024).

Aggiornamento

  1. Scarica un backup da Personalizza → Manutenzione.
  2. Scarica o costruisci la nuova versione e avviala sullo stesso volume: docker compose up -d --build. Le migrazioni vengono eseguite all'avvio.
  3. Accedi, apri le pagine di amministrazione e, con ENTRA_GROUP_SYNC=true, esegui un Force Sync.
  4. Se qualcosa va storto, avvia l'immagine precedente e ripristina il backup.

Per la procedura completa, compresa una prova su una copia dei tuoi dati, vedi Aggiornamento e rollback.