The aam-digital stack contains multiple services from different repositories wich are developed and maintained by aam-digital.
For some features, we also use third party solutions that are maintained from the respective development team.

• ndb-core: main angular frontend application GitHub
• replication-backend: (optional) layer between frontend and the couchdb for handling document permissions GitHub
• aam-backend-services: main backend spring boot application, modulith architecture GitHub

additionally, as multi-tenant services:

• account-backend: simple backend service to handle user account related tasks for the frontend in Keycloak GitHub
• ndb-admin: API for general admin functionality like statistics and config migrations on databases GitHub

Accessible for aam-digital internals and contributors only.

• aam-external-mock-service: mock of external systems are subject to a duty of non-disclosure in some cases.

• couchdb: Seamless multi-master syncing database with an intuitive HTTP/JSON API, designed for reliability GitHub
• postgresql: PostgreSQL is an advanced object-relational database management system GitHub
• keycloak: Open Source Identity and Access Management For Modern Applications and Services GitHub
• rabbitmq-server: Multi-protocol messaging and streaming broker. GitHub
• carbone: Fast, Simple and Powerful report generator in any format GitHub

Accessible for aam-digital internals and contributors only.

• structured-query-server (sqs): An SQL query engine for CouchDB, letting you use SQL SELECT statements to extract information from a CouchDB database. Homepage

• maildev: Local SMTP server with web interface for testing during development.
• caddy: Multi-platform HTTP/1-2-3 web server with automatic HTTPS.

After completing the setup steps below once you can simply use the docker compose file in this directory:

docker compose up -d

(!) Make sure to access the frontend at http://aam.localhost/ instead of "localhost:4200". Otherwise, the connections to backend services like sync will not work.

Also see the "Tips and tricks" section at the end of this file for possible adjustments.

To make development as simple as possible, we provide all services as docker containers. You can start them with the docker-compose file provided here in this folder
All container will communicate directly over a separate docker network: aam-digital

You need to create the docker network initial:

docker network create aam-digital

Fix bug on M4 chips with Sequoia 15.2: corretto/corretto-21#85:

Add this to your .env file:

JAVA_TOOL_OPTIONS="-XX:UseSVE=0"

The stack includes a caddy reverse-proxy that runs on https://aam.localhost/ - SSL is enabled by default. However, this certificate is self-signed and must be added manually as trustworthy.

You also need to adapt your /etc/hosts file and add an entry for aam.localhost to 127.0.0.1:

sudo nano /etc/hosts

Add another line for aam.localhost:

127.0.0.1       localhost
127.0.0.1       aam.localhost

You can add import the auto generated caddy certificate after the aam-stack is started.

To be able to verify https connections, the aam-backend-service need the generated caddy certificate.
You can copy the certificate to the resources directory of the aam-backend-service:

# /aam-services
cp docs/developer/container-data/caddy-authorities/root.crt application/aam-backend-service/src/main/resources/reverse-proxy.crt

1. Open Keychain Access (Cmd + Space and search for it)
2. Switch to System Keychains -> System -> Certificates
   
3. Drag and Drop the ./container-data/caddy-authorities/root.crt into Keychain Access
4. Open certificate details by double-click the certificate
5. Trust the certificate for SSL by setting Trust -> Secure Sockets Layer (SSL) to Always Trust
   

Install the locally generated root CA certificate from docs/developer/container-data/caddy-authorities/root.crt as described here.

If your browser still does not recognize the certificates of aam.localhost connections you can add it manually in your browser:

1. Copy the root certificate
2. Make it for non-root users

sudo cp container-data/caddy-authorities/root.crt aam.localhost.crt
sudo chown $USER:$USER aam.localhost.crt

3. In Chrome / Chromium: Open Settings > Privacy and security > Security > Manage certificates
4. In the "Authorities" tab, Import the certificate

todo

Create a .env file by copying the example:

# /aam-services/docs/developer
cp .env.example .env

You can start all services needed for the local development with docker-compose:

# /aam-services/docs/developer
docker compose -f docker-compose.yml up -d

or in the same directory just

# /aam-services/docs/developer
docker compose up -d

• If needed, switch the sqs image in docker-compose.yml from aam-sqs-mac to aam-sqs-linux for compatibility.
• Attention: sqs is a private repository for internal use only. If you don't have permissions, reach out to us or disable this block in the docker-compose.yml file

You can test the running proxy by open https://aam.localhost/hello - You should see a welcome message. When you see a SSL warning, follow the steps in add self-signed certificate

WARNING! We currently use Keycloak 23 in production. For local development the latest Keycloak 26 is also supported. The docker-compose offers both options. Enable one with code comments or profiles

Note that switching between the two Keycloak containers means the realm setup is different and the public key (REPLICATION_BACKEND_PUBLIC_KEY) has to be updated in .env

• Open the Keycloak Admin UI at https://keycloak.localhost with the credentials defined in the docker-compose file.

• Create a new realm called dummy-realm by importing the realm configuration file realm_config.json from the ndb-setup.

• Under **Keycloak Realm > Clients ** (https://keycloak.localhost/admin/master/console/#/dummy-realm/clients), import the client configuration using client_config.json from the ndb-setup.

• In the new realm, create a user and assign relevant roles. (Usually you will want at least "user_app" and/or "admin_app" role to be able to load the basic app config.
  If the roles are not visible in "Assign roles" dialog, you may need to change the "Filter by realm roles".)

• Add additional providers (plugins):

cd ./container-data/keycloak/providers # (create folder if necessary)
sudo wget https://github.com/aerogear/keycloak-metrics-spi/releases/download/6.0.0/keycloak-metrics-spi-6.0.0.jar && \
sudo wget https://github.com/wouterh-dev/keycloak-spi-trusted-device/releases/download/v0.0.1-22/keycloak-spi-trusted-device-0.0.1-22.jar && \
sudo wget https://static.aam-digital.net/keycloak-2fa-email-authenticator-1.0-SNAPSHOT.jar && \
sudo wget https://github.com/Aam-Digital/aam-services/releases/download/keycloak-third-party-authentication/v0.1.0/keycloak-third-party-authentication.jar

• Access CouchDB at https://aam.localhost/db/couchdb/_utils/#database/app/_all_docs.
  • username: admin
  • password: docker
• Add a document of type Config:CONFIG_ENTITY to the app database
  • e.g., from dev.aam-digital.net CouchDB instance. Note: If you get an error while adding a document (e.g. document update conflict warning) remove the "_rev": " value".
  • or in a demo system with generated data, navigate to "Admin > Admin Overview" and click "Download configuration". (the downloaded json needs to be copied into a new CouchDb Document { "_id": "Config:CONFIG_ENTITY", "data": <downloaded config> })
• Add a document of type Config:Permissions to the app database:

{
  "_id": "Config:Permissions",
  "data": {
    "public": [
      {
        "subject": [
          "Config",
          "SiteSettings",
          "PublicFormConfig",
          "ConfigurableEnum"
        ],
        "action": "read"
      }
    ],
    "default": [
      {
        "subject": "all",
        "action": "read"
      }
    ],
    "admin_app": [
      {
        "subject": "all",
        "action": "manage"
      }
    ]
  }
}

Retrieve the public_key for dummy-realm from https://keycloak.localhost/realms/dummy-realm and add it to the .env file as REPLICATION_BACKEND_PUBLIC_KEY:

# from
REPLICATION_BACKEND_PUBLIC_KEY=<the-content-of-"public_key"-from-here-https://keycloak.localhost/realms/dummy-realm>

# to
REPLICATION_BACKEND_PUBLIC_KEY=MIIBI....

Restart the deployment to use the updated settings:

docker compose down && docker compose up -d

In your local repository of ndb-core:

1. Update environment.ts or assets/config.json with the following settings, in order to run the app in "synced" mode using the backend services:

session_type: "synced",
demo_mode: false,
account_url: "https://aam.localhost/accounts-backend"

2. Update assets/keycloak.json with the following settings

{
  "realm": "dummy-realm",
  "auth-server-url": "https://keycloak.localhost",
  "ssl-required": "external",
  "resource": "app",
  "public-client": true,
  "confidential-port": 0
}

3. Start the frontend:

# https://github.com/Aam-Digital/ndb-core
ng serve --host 0.0.0.0

Attention

If you use the default npm start command, make sure to update the start command in the package.json to:

{
  "scripts": {
    "start": "ng serve --host 0.0.0.0"
  }
}

To use the queue, you have to create a user and virutal host in the RabbitMQ admin interface:

1. Open aam.localhost/rabbitmq/
2. Login with the default credentials (guest:guest)
3. Navigate to the "Admin" section
4. Create a new virtual host (local) to fit the application.yaml settings
5. Create a new user (local-spring:docker)
6. Edit that user and assign permissions to the "local" virtual host

Refer to the Module READMEs at docs/modules to set up specific modules like Notification:

• ndb-core (frontend): https://aam.localhost/
• replication-backend: https://aam.localhost/db
• aam-backend-service: https://aam.localhost/api
• maildev (smtp-trap): https://aam.localhost/maildev/
• Keycloak: https://keycloak.localhost
• CouchDB: https://aam.localhost/db/couchdb
• CouchDB Admin: https://aam.localhost/db/couchdb/_utils/ (the final "/" is important!)
• RabbitMQ: https://aam.localhost/rabbitmq/ (the final "/" is important!)

For easy start in local development, we create some default accounts.

Unless otherwise specified, the default credentials are:

• username: admin
• password: docker

The default credentials for rabbitmq are:

• username: guest
• password: guest

Sometimes, when you're playing around with http(s):// redirects in your browser, Chrome will cache the redirect for some time. When you explicit want to open the http:// version of an url, but Chrome will not let you:

• go to chrome://net-internals/#hsts
• insert your domain in the Delete domain security policies section
• press delete

You can open the http:// version directly again.

This setup provides all services, including the aam-services backend in this repository, through their docker images. To test backend code locally, you can adjust the reverse-proxy to point to a local version of a service (e.g. to test a development version of accounts or replication-backend in this integrated environment). For this, edit the Caddyfile and replace the relevant line of the reverse-proxy to use an address through host.docker.internal to point to your local machine (see comments in Caddyfile).

Please note that the .env files here in this directory are not automatically used as environment variables in a locally started service like this code base.