🏥 MS3

MS3 - Medical Staff Shift Scheduler is designed to schedule medical shifts of hospital employees.

🚀 Running the Project Locally

Installare PostgreSQL e creare nel DBMS:

• un utente con username = sprintfloyd e password = sprintfloyd con grants da SUPERUSER
• un database vuoto chiamato ms3
• 3 utenti:
  • public_scheme_user con password password_public
  • tenant_a_user con password password_a
  • tenant_b_user con password password_b

    • Ognuno con i seguenti grants:

      LOGIN
      NOSUPERUSER
      NOCREATEDB
      NOCREATEROLE
      INHERIT
      NOREPLICATION
      NOBYPASSRLS
      CONNECTION LIMIT -1
      

Per avviare il sistema, lanciare il Backend e il Frontend e visitare (3000 è la porta di default):

http://localhost:3000

📦 Running the project with Containers

🖥️ Modifiche locali OS-specific

Prima di avviare i container, verificare eventuali modifiche locali in base al sistema operativo:

• Linux: nessuna modifica necessaria.
• WINDOWS: Convertire tramite il comando dos2unix (vedi qui) i file di testo mvnw e src/main/resources/db/init-scripts/init-users.sh.
• macOS Apple Silicon: modifica locale in src/main/resources/Dockerfile.backend da FROM eclipse-temurin:11-jdk-alpine a FROM eclipse-temurin:11-jdk.

⚠️ Queste modifiche sono solo per esecuzione locale e non devono essere committate.

Per avviare il sistema in containers, bisogna avere installato sulla macchina host Docker e battere il seguente comando su terminale:

docker-compose up -d

Se si impiega il codice in produzione, è opportuno impostare le variabili di ambiente DB_USER, DB_PASSWORD, DB_NAME, DB_TENANT_PUBLIC_USER, DB_TENANT_PUBLIC_PASSWORD, DB_TENANT_A_USER, DB_TENANT_A_PASSWORD, DB_TENANT_B_USER e DB_TENANT_B_PASSWORD con i valori desiderati, altrimenti verranno utilizzati i valori di default presenti nel file .env che sono salvati in chiaro in questa repository, e ciò può rappresentare un problema di sicurezza. La variabile di ambiente FRONTEND_EXPOSE determina su quale porta il server node ascolterà le richieste dei clients (Default is 8080).

🔐 Configurazione 2FA (TOTP)

Per l'implementazione TOTP 2FA sono richieste variabili di ambiente aggiuntive. Configurarle prima del deploy e non committare mai i segreti:

Variabile	Descrizione
HMAC_MASTER_KEY	Chiave master usata per derivare i segreti TOTP e i codici di recupero (non deve mai essere loggata o salvata in chiaro).
MAX_OTP_ATTEMPTS	Numero massimo di tentativi OTP consecutivi prima del blocco temporaneo.
OTP_LOCKOUT_SECONDS	Durata del blocco OTP dopo aver superato MAX_OTP_ATTEMPTS.
ENFORCED_2FA_ROLES	Lista (separata da virgole) dei ruoli per cui la 2FA è obbligatoria dopo l'accesso con password.
RECOVERY_CODE_COUNT	Numero totale di codici di recupero generati per ogni enrollment; l'ultimo codice disabilita la 2FA e richiede una nuova attivazione.

Note operative:

• Le challenge OTP non hanno TTL; la sicurezza deriva dalla freschezza dell'OTP (30s) e dal lockout di tentativi.
• I pipeline di deploy devono gestire HMAC_MASTER_KEY come secret sicuro (store dedicato/secret manager) e non tramite file versione.
• Verificare che le variabili siano presenti in ogni ambiente prima di abilitare la 2FA agli utenti.

Per utilizzare l'applicazione, poi, visitare (sostituire FRONTEND_EXPOSE con il valore configurato):

http://localhost:FRONTEND_EXPOSE

📘 Documentazione

• Manuale Codacy (analisi statica e qualità del codice)

🗄️ Aggiornare il database con modifiche di schema (es. colonne 2FA)

L'avvio in container crea i ruoli e i permessi tramite src/main/resources/db/init-scripts/init-users.sh prima che lo SchemasInitializer dell'applicazione applichi gli script SQL per ogni tenant (public, A, B). Assicurarsi che le variabili di ambiente DB_USER, DB_PASSWORD, DB_NAME, DB_TENANT_PUBLIC_USER, DB_TENANT_PUBLIC_PASSWORD, DB_TENANT_A_USER, DB_TENANT_A_PASSWORD, DB_TENANT_B_USER, DB_TENANT_B_PASSWORD siano impostate in .env o nella shell e corrispondano ai placeholder in src/main/resources/application-container.properties, altrimenti l'initializer non potrà collegarsi per creare o aggiornare le tabelle (incluse le colonne 2FA).

Quando vengono introdotte modifiche strutturali (come nuove colonne 2FA), è consigliabile ricreare il volume db_data per evitare schemi obsoleti:

1. Fermare i container: docker-compose down -v (oppure rimuovere il volume ms3_db_data).
2. Rieseguire docker-compose up -d per rieseguire gli script di bootstrap e l'initializer sugli schemi puliti.

Debug del backend su Docker

La presente guida descrive come eseguire il debug sul backend direttamente all'interno di Docker su Intellij.

1. Avviare Docker Compose tramite il file docker-compose-debug.yml
2. Da Intellij, andare su Run > Edit Configurations...
3. Creare una nuova configurazione:
   1. Cliccare sul pulsante + in alto a sinistra
   2. Selezionare Remote JVM Debug
   3. Impostare i seguenti parametri:
      • Host: localhost
      • Port: 5005
      • JKD 9 or later sulla destra
      • Command line arguments for remote JVM: -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005
      • Use module classpath: ms3