Sano-KPI-Application

Collective repository for all components of the Sano KPI analysis application: the frontend dashboard, the main backend platform (SanoPublicationDB), and documentation for deploying the entire system.

Deployment

1. Clone the repository and init submodules

To deploy the application, first clone this repository with its submodules:

git clone https://github.com/SanoScience/Sano-KPI-Application.git
cd Sano-KPI-Application
git submodule update --init

This command pulls the code of the submodule repository SanoPublicationDB at the correct commit.

2. Environment configuration

The application is configured via environment variables. They are required to personalise and secure some of the key application functionalities.

Required variables:

• RAILS_MASTER_KEY
  • it is in the config/master.key file
  • can be generated using rails credentials:edit in the application root folder ../SanoPublicationDB
• POSTGRES_PASSWORD
  • password for the PostgreSQL user used by the app
  • can be any random character sequence
  • you can generate it with a secure random password generator
• PUBDB_DATABASE_USERNAME
  • PostgreSQL username, can be any
  • default is pubdb
• SECRET_KEY_BASE
  • Rails secret key base (for signing cookies and sessions)
  • to obtain in the SanoPublicationDB folder, run rails secret (or bin/rails secret) and copy the generated value
• ENTRA_CLIENT_ID
  • Microsoft Entra (Azure AD) application (client) ID
  • To use the SSO system in the application, you need to register it in the Microsoft EntraID system (there is an explanation how to do it below)
  • Then, copy its ID to this variable
• ENTRA_CLIENT_SECRET
  • Client secret for the above app registration
  • used by the backend to authenticate against Entra
  • Can be generated in the app registration (below explained how)
• ENTRA_TENANT_ID
  • ID of your Microsoft Entra tenant
  • Usually one per organization, also can be found in Azure Portal (guide below)
• OUTLOOK_USERNAME
  • to use mailing services of the application, you need to provide username (email) and password for Outlook account which will be used to send emails
  • Account should have disabled 2FA and have permission Mail.send (how to set it up is explained below
• OUTLOOK_PASSWORD
  • password to the above Outlook account
• AZCOPY_LINK
  • To use backup functionality, an AzCopy system has to be configured
  • It is a link generated by AzCopy to send and retrieve files from/to remote Azure Storage.

This can be done either by exporting them manually or (recommended) by creating a .env file with the following entries:

POSTGRES_PASSWORD=*your postgres password*
RAILS_MASTER_KEY=*your rails master key*

2.1. EntraID setup

If you use Microsoft Entra (Azure AD) for authentication, you need three values from Azure:

• ENTRA_TENANT_ID
• ENTRA_CLIENT_ID
• ENTRA_CLIENT_SECRET

2.1.1. Tenant ID (ENTRA_TENANT_ID)

1. Go to the Azure Portal: https://portal.azure.com
2. Open Microsoft Entra ID (formerly Azure Active Directory).
3. On the Overview page, copy Tenant ID (or Directory (tenant) ID).
4. Use this value as ENTRA_TENANT_ID in your .env.

2.1.2. Application (client) ID (ENTRA_CLIENT_ID)

• In Microsoft Entra ID, go to App registrations.
• Select an existing app registration for Sano KPI or create a new one via New registration.
• On the app’s Overview page, copy Application (client) ID.
• Use this value as ENTRA_CLIENT_ID in your .env.

2.1.3. Client secret (ENTRA_CLIENT_SECRET)

• In the same app registration, go to Certificates & secrets → New client secret.
• Add a description and expiry, then click Add.
• Copy the Value of the new secret immediately (it will not be shown again).
• Use this value as ENTRA_CLIENT_SECRET in your .env.

2.2. Outlook / SMTP configuration

The application sends notification emails via an Outlook / Microsoft 365 mailbox configured through:

• OUTLOOK_USERNAME – the full email address of the mailbox used to send emails (e.g. notifications@your-org.com).
• OUTLOOK_PASSWORD – the password for that mailbox.
  • If the account uses MFA, this should be an app password generated in Microsoft 365, not your normal login password.

The SMTP server, port and TLS settings are preconfigured in the application (standard Microsoft 365 SMTP AUTH over TLS: smtp.office365.com, port 587). You only need to make sure the mailbox and permissions are set correctly.

2.2.1. Choose or create a mailbox

1. Go to Microsoft 365 admin center → Users → Active users. :contentReference[oaicite:0]{index=0}
2. Either:
   • Pick an existing user mailbox to act as the sender (for example, a generic account like notifications@your-org.com), or
   • Create a new user specifically for the KPI app (assign it an Exchange Online-enabled license).

Use this mailbox’s full email as OUTLOOK_USERNAME.

2.2.2. Enable SMTP AUTH for that mailbox

The app uses authenticated SMTP to send mail. In many tenants, SMTP AUTH is disabled by default and must be explicitly allowed for the mailbox.

1. In Microsoft 365 admin center, go to Users → Active users.
2. Select the mailbox you will use (from step 1), then open the Mail tab.
3. In Email apps, click Manage email apps.
4. Make sure Authenticated SMTP is checked (enabled) for this user.
5. Save changes.

If SMTP AUTH is disabled organization-wide, your M365 admin may also need to enable it globally or via an auth policy before the above setting has effect.

2.2.3. Handle MFA / app passwords (if used)

If the mailbox has multi-factor authentication (MFA) enabled:

1. Sign in to https://portal.office.com with that account.
2. Go to My Account → Security info (or Additional security verification depending on your tenant).
3. Create a new App password for “SMTP / application sending”.
4. Use:
   • OUTLOOK_USERNAME = mailbox email (e.g. notifications@your-org.com)
   • OUTLOOK_PASSWORD = the app password generated above

If MFA is not enabled, OUTLOOK_PASSWORD can be the normal mailbox password (subject to your security policy).

2.2.4. (Alternative) Sending mail via Microsoft Graph (Mail.Send)

Instead of SMTP, the application can be configured (or extended) to send email via Microsoft Graph using application permissions. In this case, the backend authenticates with its App Registration in Entra ID and calls the Graph API directly.

To allow this, you need to grant the app the Mail.Send application permission:

1. Go to the Azure Portal → https://portal.azure.com
2. Open Microsoft Entra ID → App registrations.
3. Select the app registration used by the KPI backend (the same one whose IDs you used for ENTRA_CLIENT_ID / ENTRA_TENANT_ID).
4. In the left menu, go to API permissions.
5. Click Add a permission.
6. Choose Microsoft Graph.
7. Select Application permissions (not Delegated).
8. In the search box, type Mail.Send.
9. Expand Mail, check Mail.Send, then click Add permissions.
10. Back in the API permissions list, click Grant admin consent for <your tenant> and confirm.
    • This step requires an Entra / Azure AD administrator.
    • After consent is granted, the status for Mail.Send should show as Granted for <tenant>.

Once this is done, the app registration will be allowed to send email as configured in your backend code via Microsoft Graph.

2.3. AzCopy configuration (AZCOPY_LINK)

AzCopy is a tool to synchronise database backups with remote storage. The AZCOPY_LINK variable used by scheduled backup jobs tells the backend where to download these backups.

To get the AZCOPY_LINK

1. Open the official AzCopy download page in the Azure documentation.
2. Select the version and OS matching the environment inside your containers (typically Linux x86_64).
3. Copy the direct download link to the AzCopy archive (e.g. .tar.gz).
4. Use this URL as the value of AZCOPY_LINK in your .env.

Example:

AZCOPY_LINK=https://example.microsoft.com/path/to/azcopy-linux.tar.gz

3. Starting

After setting up the environment, run:

docker compose up -d --build

This will build the necessary containers and start the database, frontend dashboard, and backend platform.

You can check the addresses of the running services using:

docker compose ps