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)

Thescripts folder provides utilities to enable the backend and its specific API modules.Check the documentation in the comments at the top of each file for usage instructions.

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 theswag-proxy. 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 swag-proxy. (we have multiple production instances, so as an example the aam-prod-2 config)

1. Create the required network

   docker network create external_web

2. Inswag-proxy/docker-compose.yml setEMAIL to a valid email address and adapt the DOMAINS config to match your setup.
3. Start the required containers (this is only needed once on a server)

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

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 (withouthttps://)
3. Start the required containers

   cd keycloak && docker-compose up -d

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

keycloak/realm_config.json provides a sample configuration that the interactive setup script uses (replacing some placeholders automatically).You can create a custom realm_config.json in each baseConfig folder to overwrite this.

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

Basic backup scripts are available in the "scripts" folder.

Set the setup.env variables for the backup root folder and passphrase (to encrypt backups).Then run thebackup.sh script to create a current backup.

You can set up the script to run via cron:

Start the new cron job

crontab -e# then enter the following (adjusted to your actual file locations)0 2***       /var/docker/ndb-setup/backup.sh# the above runs every day at 2 am

Under/var/docker run the interactive scriptbackup-recover.sh to load a backup for a certain client from a certain date.

To manually load a backup follow these steps:

1. Find the passphrase in the/var/docker/backup.sh file.
2. Go tomnt/<backup-volume>/backups
3. Decrypt a backup using

   gpg --passphrase\<passphrase\> -o output -d\<backup-file\>

4. Decompress the backup

   mkdir ./unpacked&& tar -xzvf output --directory ./unpacked

5. Go to application where backups should be applied and stop docker container

   cd /var/docker/ndb-\<instance\>docker compose down

6. Load the backup

   mv couchdb couchdb_old&& mv~/backups/unpacked/var/docker/ndb-\<instance\>/couchdb ./couchdb

7. Start the docker containers

   docker compose up -d

8. After everything works as expected, delete all temporary data

   rm -rf couchdb_old~/backups/output~/backups/unpacked

When applying a backup, do not forget to clear you browser cache before opening the application again. Otherwise the previously corrupted data will be synced from the browser to the DB that has just been backed up. To delete all local data go tohttps://<instance>.aam-digital.com/support and pressReset Application. All users, which have corrupted data will need to do this.

More information on CouchDB backups can be foundhere.

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.