AIIDA Operation Manual

This document provides instructions on how to operate and manage the Administrative Interface for In-House Data Access (AIIDA).

Quickstart

A quickstart configuration to run AIIDA is provided in the aiida/docker folder of the development project or under this link. This setup uses Docker Compose to orchestrate the necessary services. To get started, follow these steps:

1. Download the quickstart configuration from the provided aiida/docker
2. Run docker compose up -d in that folder.
3. Open the browser on http://localhost:8081 to access the AIIDA web interface.
4. You can log in with the default credentials:
   • Username: aiida
   • Password: aiida
5. For adding data sources, please refer to the data source section.
6. For adding permissions, please refer to the permission section.

Installation

The aiida/docker folder contains a container configuration inside the compose file.

Additional Services

AIIDA requires additional services to function properly. The following services are included in the Docker Compose setup:

Service	Description
TimescaleDB	A time-series database built on PostgreSQL. It is used to store information about permissions, data sources, and time-series data.
EMQX	An open-source MQTT broker that facilitates communication between data sources and AIIDA.
Keycloak	An open-source identity and access management solution. It is used for authentication and authorization.

A sample configuration for these services is also provided in AIIDA's compose file.

Configuration

It is recommended to configure AIIDA using the .env file provided in the aiida/docker folder in combination with the compose.yml file.

Parameter	Description
AIIDA_EXTERNAL_HOST	Network-accessible host of the AIIDA instance (defaults to http://localhost:8080)
AIIDA_CORS_ALLOWED_ORIGINS	The origins that are allowed to communicate with AIIDA (see reverse proxy deployments)
AIIDA_HANDSHAKE_LOCALHOST_REPLACEMENT	Replaces "localhost" hostnames in HTTP requests (useful when testing a local EDDIE instance)
AIIDA_CLEANUP_INTERVAL	Specifies in which fixed duration the cleanup task is scheduled (default: P1D)
AIIDA_CLEANUP_ENTITIES_AIIDARECORD_RETENTION	Specifies the time-to-live for an AIIDA_RECORD (default: P1D)
AIIDA_CLEANUP_ENTITIES_FAILEDTOSENDENTITY_RETENTION	Specifies the time-to-live for a FAILED_TO_SEND_ENTITY (default: P1D)
AIIDA_CLEANUP_ENTITIES_INBOUNDRECORD_RETENTION	Specifies the time-to-live for an INBOUND_RECORD (default: P1D)
AIIDA_CONNECTION_LIMIT_VIOLATION_DETECTION_ENABLED	Whether monitored data sources are checked for connection limit violations (default: true). If false, no violations are stored and no notifications are sent
AIIDA_CONNECTION_LIMIT_VIOLATION_DETECTION_INTERVAL_MS	The interval in milliseconds at which monitored data sources are checked for connection limit violations (default: 10000)
AIIDA_CONNECTION_LIMIT_VIOLATION_DETECTION_RECOVERY_HOLD_MS	The time in milliseconds the measured power has to stay within the limits until a violation ends (default: 60000). 0 ends a violation at the first record within the limits
SPRING_DATASOURCE_HOST	The hostname of the TimescaleDB service
SPRING_DATASOURCE_PORT	The port of the TimescaleDB service
SPRING_DATASOURCE_DATABASE	The database name for AIIDA in TimescaleDB
SPRING_DATASOURCE_USERNAME	The username for accessing the database
SPRING_DATASOURCE_PASSWORD	The password for accessing the database
MQTT_INTERNAL_HOST	The hostname for docker internal communication
MQTT_EXTERNAL_HOST	The hostname for external communication
MQTT_BCRYPT_SALT_ROUNDS	The bcrypt salt rounds for hashing passwords
MQTT_PASSWORD	The password for the MQTT user aiida
MQTT_TLS_CERTIFICATE_PATH	Filepath of TLS certificate for MQTT broker (can be mounted to Docker container)
EMQX_DATABASE_PASSWORD	The password for the emqx user in TimescaleDB
KEYCLOAK_ADMIN_USERNAME	The admin username for Keycloak
KEYCLOAK_ADMIN_PASSWORD	The admin password for Keycloak
KEYCLOAK_EXTERNAL_HOST	The hostname for accessing Keycloak
KEYCLOAK_INTERNAL_HOST	The hostname for docker internal communication
KEYCLOAK_REALM	The Keycloak realm used for AIIDA
KEYCLOAK_CLIENT ID	The Keycloak client ID used for AIIDA
SPRING_MAIL_HOST	The hostname of the SMTP server used to email notifications (notifications are disabled if unset)
SPRING_MAIL_PORT	The port of the SMTP server (default: 25)
SPRING_MAIL_USERNAME	The username for SMTP authentication and the sender address of notification emails
SPRING_MAIL_PASSWORD	The password for SMTP authentication

Email Notifications

AIIDA can send email notifications to users when the measured data of an assigned data source violates the connection limits of a permission, and a recovery email when the data is back within the limits. Notifications are only sent when a mail server is configured (SPRING_MAIL_HOST). To receive notifications the user has to set a contact email address in their account settings.

Each violation is also stored with its start, end, the violated limit and the measured power, and can be queried with GET /connection-limits/{permissionId}/violations. Only active permissions that have a data source assigned are monitored. Violations of a permission end when the measured power is back within the limits or the permission is no longer monitored, for example because it was revoked or terminated. Periods without any limit are treated as having no limits, so they cannot be violated. To avoid flooding the user with notifications when the power oscillates around a limit, a violation only ends after the power stayed within the limits for the recovery hold (AIIDA_CONNECTION_LIMIT_VIOLATION_DETECTION_RECOVERY_HOLD_MS, default: 1 minute). The recovery email is sent after that hold, and the violation ends at the first record that was back within the limits. A new record is needed to confirm the recovery, so a violation stays open until the data source reports again.

The latest measured value of each assigned data source is checked periodically (AIIDA_CONNECTION_LIMIT_VIOLATION_DETECTION_INTERVAL_MS), so a notification can be delayed by up to that interval. The detection can be disabled with AIIDA_CONNECTION_LIMIT_VIOLATION_DETECTION_ENABLED=false.

Only data recorded while AIIDA is running is checked. After a restart, the detection continues with the newest record of each data source, so a violation that started and ended while AIIDA was not running is neither stored nor reported. A violation that was ongoing when AIIDA stopped stays open, and ends at the first record that is back within the limits.

The development setup in aiida/docker includes a Mailpit service to capture outgoing emails. Start it with docker compose --profile mail up and open http://localhost:8025 to inspect them. Uncomment the SPRING_MAIL_* variables in aiida/docker/.env to route notifications to Mailpit.

Additional spring.mail.properties.* settings (like TLS, authentication, or timeouts) can be supplied through the corresponding environment variables (see Spring documentation). AIIDA sets connection, read and write timeouts of 5 seconds, so that an unresponsive mail server does not delay the violation detection. They can be changed with SPRING_MAIL_PROPERTIES_MAIL_SMTP_CONNECTIONTIMEOUT, SPRING_MAIL_PROPERTIES_MAIL_SMTP_TIMEOUT and SPRING_MAIL_PROPERTIES_MAIL_SMTP_WRITETIMEOUT (in milliseconds). Failed notifications, for example due to an invalid contact email or an unreachable mail server, are logged and are not retried. The mail server is not part of the health endpoint, as notifications are optional.

Reverse Proxy Deployment

If you are running an AIIDA instance behind a reverse proxy (e.g. nginx) to make it accessible everywhere, it is necessary to add the origin of the AIIDA instance to the allowed origins. This can be done by setting the config aiida.cors.allowed-origins or using the AIIDA_CORS_ALLOWED_ORIGINS environment variable. For example, if your AIIDA instance is reachable at the url https://aiida.eddie.energy you have to set the value of AIIDA_CORS_ALLOWED_ORIGINS to https://aiida.eddie.energy. To the best of our knowledge, this is only necessary for reverse proxy deployments and not e.g. using Kubernetes.

Customizing Brand Icons in the UI

The AIIDA brand icons can be customized by replacing the SVG files inside aiida/docker/svgs with your custom icons. For best results try to use SVGs with a similar aspect ratio to the original icons. If the icons are deleted or otherwise invalid, fallback icons will be used.

• HeaderLogo.svg the logo used in the header.
• BackgroundBrandmark.svg the icon that is displayed in the background.
• favicon.svg the favicon

Application Information

After the first startup of AIIDA, an application UUID is generated and stored in the database. This UUID can be found in the aiida_application_information table in the database. It is used by the EDDIE instance to differentiate between multiple AIIDA instances.

Internal APIs

AIIDA provides internal APIs for additional information about itself.

OpenAPI Documentation

OpenAPI documentation can be found here: <AIIDA_EXTERNAL_HOST>/v3/api-docs

SwaggerUI is also included and can be found here: <AIIDA_EXTERNAL_HOST>/swagger-ui/index.html

Actuator API

AIIDA uses Spring to expose health information for data sources. The actuator API is available at <AIIDA_EXTERNAL_HOST>/actuator and the health endpoint at <AIIDA_EXTERNAL_HOST>/actuator/health.

Record API

The Record API provides access to the latest record (message) that AIIDA has sent or received.

• Permission Record:
  Returns the most recent message associated with a specific permission.
  For outbound permissions, this includes the fields topic, serverUri, timestamp, schema, and payload.
  For inbound permissions, see the Inbound Provisioning page for details.

• Data Source Record:
  Returns the most recent message received from a specific data source, converted into the Raw Message format.

In the AIIDA web interface, the corresponding record can be downloaded directly from the data source or permission detail views.
All records are provided in JSON format to simplify inspection and debugging.

Use this API to monitor and verify the latest communication between AIIDA and connected data sources or permissions.

Inbound API

Via the Inbound Data Source the EP can send data to AIIDA via MQTT. For that purpose, the user must accept an inbound permission, which automatically creates an inbound data source.

The latest retrieved inbound data can be accessed via the Inbound API. See Inbound Provisioning for more information.

Helm Chart

WARNING

This Helm chart is not actively maintained and may not be up to date with the latest AIIDA features or deployment best practices.

The AIIDA Helm chart is available in the dedicated repository. It enables the deployment of AIIDA on Kubernetes clusters using Helm.

For more details, refer to the AIIDA Helm Chart repository.