Repository files navigation

This repository describes how to set up everything that is needed to run theAam Digital case management system in production.This includes deploying the app, deploying and connecting the database and optionally deploying and connecting the permission backend and keycloak.

The source code of the actual application, as well as instructions to run it on your local machine during development, can be found in theAam-Digital/ndb-core repository.

(!) copy the example.* files (e.g. setup.example.env) and add your actual variables and config

The deployment works with minimal requirements.All you need is a system that runsDocker and allows to reach endpoints through a public URL.For a single instance a server with2GB RAM, asingle CPU and20GB disc space is sufficient.With more data and/or more deployments more RAM and CPU power might be necessary or the sync could start to become very slow.The required disc space scales with the amount of data and especially images and attachments that are saved in the application.

To monitor the hardware usagethis repo contains a Prometheus setup.This can be connected withGrafana to create a system dashboard and trigger alerts on critical performance.

The interactive scriptinteractive_setup.sh walks you through the process of setting up new applications.Running the setup script will create a new folder in the same parent folder, next to the cloned repo. You can use the script multiple times to create new instances.

1. Clone this repository
2. Set up local environment by copying setup.example.env file and editing thesetup.env andkeyloak/.env
3. Then run the script and follow the questions in the console to generate the required .env and other files:

   ./interactive_setup.sh

The following things can be automatically done

1. Deploy the application
2. (optional) add the permission backend
3. (optional) connect with a running Keycloak
4. (optional) migrate users from CouchDB to Keycloak

To log errors withSentry, simply set the variableSENTRY_DSN in the.env file to you sentry DSN.

Some things have to be set for the interactive setup script through environment variables.Have a look atinteractive_setup.sh to see which .env files are loaded there.

1. Domain name for the final applications (variabledomain)
2. Prefix for created folders (variableprefix)
3. the.env file of the keycloak deployment (see sectionUser management in Keycloak)

In order to make the application's docker container accessible under a public URL, you need to expose it using a tool of your choice.The system works well with thenginx-proxy docker. This allows to automatically configure things so that the app is reachable under a specific domain name (including automatic setup of SSL certificates through letsencrypt).

This setup repository comes with adocker compose for setting up the nginx-proxy.

1. Create the required network

   docker network create nginx-proxy_default

2. Innginx-proxy/docker-compose.yml setDEFAULT_EMAIL to a valid email address
3. Start the required containers (this is only needed once on a server)

   cd nginx-proxy && docker-compose up -d

4. Set theVIRTUAL_HOSTandLETSENCRYPT_HOST as environment variables on new docker containers to define under which URL they should be reachable

The system uses theKeycloak identity management system.All the required configuration can be found in thekeycloak folder.

We use a custom build of Keycloak that includes certain plugins required for 2-Factor-Auth.Plugin versions are managed within that custom docker image inAam-Digital/aam-cloud-infrastructure.

To start the required docker containers execute the following (this is only needed once on a server, you can skip these steps if you just want to add another Aam Digital instance to an existing keycloak server):

1. Open the filekeycloak/.env
2. Set the password variables to secure passwords and assign valid urls for the Keycloak andaccount backend (withouthttps://)
3. Openkeykloak/realm_config.json and add the required settings for you email server to enable Keycloak to send emails in your name
4. Start the required containers

   cd keycloak && docker-compose up -d

Once done, applications can be connected with Keycloak through theinteractive_setup.sh.

Keycloak supports a second login factor through the methods described below:

• Authenticator App
• E-Mail OTP

The only built-in second factor ist OTP using a Authenticator app.This can be enabled by editing a specific user in the Keycloak "Administration Console" and adding theConfigure OTP in the "Required user actions".It can also be activated for everyone by changing theBrowser - Conditional OTP in the used Browser flow fromConditional toRequired.

Through 3rd party libraries OTP via Email is supported.This also comes with the option to trust the device for a configured time period (during which you do not have to enter the OTP when logging in).

To enable this feature visit<KEYCLOAK_URL>/admin/master/console/#/<REALM>/authentication/ (i.e. open the "Authentication" section of the Keycloak realm) and follow the described steps below ("Activating Email 2FA").If you created this realm using a recent version of therealm_config.json then you should find a flow with the nameEmail 2FA,otherwise see the steps below in the next section ("Setting up Email OTP manually").

To activate 2FA over email, click on the 3 dot menu on the right of theEmail 2FA flow and selectBind flow and selectBrowser flow.After saving, when trying to log in to the app you should be asked to enter the OTP which has been sent to the email that is associated with the username.

Similar to the steps of activating the 2FA flow, to disable it you need to re-activate the normal "browser" flow:Click on the 3 dot menu on the right of thebrowser flow, selectBind flow and then selectBrowser flow.

Disabling 2FA for a specific account can be configured but is not part of default setup yet. Please check with existing sample systems for the setup to make the following instructions work:

To disable email 2FA for only one individually user assign the Keycloak User Role "no-email-2fa" to that user account to skip 2FA for that person.If the role does not exist yet, create it in the Keycloak Admin interface.(The logic of this special role is configured within theEmail 2FA Authentication flow as a condition)

If theEmail 2FA flow is not available in the realm (section "Authentication"), you can configure it manually:

1. Click on the 3 dot menu of thebrowser flow and select duplicate
2. EnterEmail 2FA as name
3. Delete the last two steps (Condition - user configured andOTP form)
4. Click on the+ button in the last row (Email 2FA Browser - Conditional OTP)
5. SelectAdd condition, there selectCondition - Device Trusted and clickAdd
6. On the new step (Condition - Device Trusted) click onDisabled and change it toRequired
7. Click on the cog icon next toRequired and entertrusted-config asAlias and clickSave
8. Again click on the+ icon forEmail 2FA Browser - Conditional OTP
9. SelectAdd step, there selectEmail OTP and clickAdd
10. ChangeDisabled toRequired forEmail OTP
11. Again click on the+ icon forEmail 2FA Browser - Conditional OTP
12. SelectAdd step, there selectRegister Trusted Device and clickAdd
13. ChangeDisabled toRequired forRegister Trusted Device

Now the flow is configured correctly, and you can start using it the same way it has been described above.

In the stepEmail OTP you can configure the amount of seconds for which an OTP is valid and in theRegister Trusted Device step you can configure how long a device will be trusted (e.g.P30d for 30 days orPT24h for 24 hours).

There are many ways in which the authentication flow can be configured.For example, you could also add the trust device step to the OTP with authenticator app, or you could make the user decide which OTP (email or app) should be used.Consult theKeycloak docs for ways to edit flows or configure new ones.

It is possible to calculate reports for the app's data using SQL queries.For details information, check ourReport documentation

(e.g. with TolaData)

1. Enable the reporting backend:
   • addaam-backend-service to you COMPOSE_PROFILES .env variable to activate that container in the docker compose:COMPOSE_PROFILES=replication-backend,aam-backend-service
   • addAAM_BACKEND_SERVICE_URL=http://aam-backend-service:3000 to the .env file that feeds into the docker-compose.yml
2. Set up Reporting API according toaam-services README
   • (re-up the docker compose and confirm the new containers are running)
   • follow instructions there to set up an auth client to access results via API

If you just want to use ndb-core through docker, you should not have to build the image yourself. Use the pre-built image on Docker Hubaamdigital/ndb-server.

The Dockerfile to build the image are part of thendb-core repository.See the/build sub folder there.

The image builds upon a simple nginx webserver and modifies the configuration to include a reverse proxy for thedomain.com/db URLs to access the CouchDB database from the same domain, avoiding CORS issues.