Production Setup

The general setup is described in the Contributor Setup Guide. This guide focuses on the dockerized setup process for PROMPT. The PROMPT setup process is straightforward and requires only a few environment variables to adjust.

There are three crucial steps for setting up PROMPT:

  1. Keycloak Setup (required)

  2. SMTP Server Setup (optional – recommended)

  3. Container Setup

1. Keycloak Setup

PROMPT uses Keycloak for authentication and user rights management. In particular, PROMPT requires the following Keycloak components:

Clients

  • prompt-client
    Used for login on the client side.

  • prompt-server
    Used by the backend server to authenticate and manage user groups and roles.

Roles and Groups

  • General Roles (client-specific roles for prompt-server):

    • PROMPT_ADMIN: Grants access to all courses and functionality.

    • PROMPT_LECTURER: Allows the creation of new courses.

  • Course-Specific Roles
    When a course is created, PROMPT automatically creates the following client roles for prompt-server:

    • <SemesterTag>-<CourseName> (Group and Role)

      • <SemesterTag>-<CourseName>-Lecturer
        Group: Lecturer (a subgroup of the course group). This role grants admin rights on the course. The course creator is automatically added to this role.

      • <SemesterTag>-<CourseName>-Editor
        Group: Editor (a subgroup of the course group). This role has limited user rights. For more details, refer to the Contributor Guide.

There are two options for setting up Keycloak:

Option 1: Configure an Existing Keycloak Instance for PROMPT

Follow these steps:

1. Create the Clients prompt-client

  1. Set URLs
    Add your client domain to the following fields. All URLs must be prefixed with https.

    • Root URL

    • Home URL

    • Valid Redirect URLs (must be postfixed with /*)

    • Valid Logout URLs (must be postfixed with /*)

    • Web-Origin URLs IMPORTANT: Only postfix Valid Redirect and Logout URLs.

  2. Add Mappers for User Attributes
    PROMPT authenticates students using their matriculation_number and university_login. To include these in the token:

    • Navigate to Client Scopes for prompt-client.

    • Select the prompt-client-dedicated scope.

    • Click on Add Mapper by configuration.

    • For each mapper, set:

      • Mapper Type: User Attribute

      • User Attribute: university_login or matriculation_number
        (adjust if your system uses a different name, e.g., TUM ID)

      • Token Claim Name: university_login or matriculation_number (do not change)

      • Add to Access Token: Enabled

2. Create the Clients prompt-server

  1. Set URLs
    Add your server domain to:

    • Root URL

    • Home URL

    • Valid Redirect URI

    • Valid Post Logout Redirect URI

    Each URL must start with https and ALL must be postfixed with /* (note that the postfixes might differ from those in prompt-client).

  2. Enable Service Account Access
    This is required to allow PROMPT to create course-specific roles:

    • Enable Service Account Roles.

    • Under the Service Account Roles tab, add the role realm-admin.

    • In the Credentials tab, select Client Authenticator: Client ID and Secret.

      • Save and generate a new secret.

      • Store this secret in your environment file under KEYCLOAK_CLIENT_SECRET.

  3. Add the required client roles

    • Add the roles PROMPT_ADMIN and PROMPT_LECTURER

    • Optionally create groups for these roles for easier user role management.

Option 2: Use a Standalone Keycloak Instance for PROMPT

For this option, refer to the Contributor Setup Guide on how to configure a standalone Keycloak instance and the keycloakConfig.json.

Keep in mind:

  • The docker-compose.extern.yml includes a sample setup with a Docker container for Keycloak and a database instance to persist Keycloak data.

  • Domain Setup:
    Configure a separate domain for your Keycloak instance (this can be a subdomain but not a subpath).

    • Valid Examples:

      • prompt.<yourDomain>.de and keycloak.prompt.<yourDomain>.de

    • Invalid Example:

      • prompt.<yourDomain>.de and prompt.<yourDomain>.de/keycloak

  • Follow the Contributor Guide closely and copy the KEYCLOAK_CLIENT_SECRET into your environment file as described.

  • To support student login, your Keycloak instance must allow authentication with matriculation_number and university_login attributes. Without these, student-specific management console features will not be available (although this does not affect the application module).

3. Container Setup

3.1 Adjust Environment Variables

An .env.template file is provided in the repository. This file includes all the runtime variables required for deployment. Below is an explanation of the variables:

Deployment Location Specific Variables

  • ACME_EMAIL
    Email used for HTTPS certificate generation and notifications.

  • ENVIRONMENT
    Set to production. Changing this will result in additional debug output.

  • CORE_HOST
    The deployment URL of your application.

  • CHAIR_NAME_SHORT
    The short name displayed in the website header.

  • CHAIR_NAME_LONG
    Used in the welcome text (can be the same as CHAIR_NAME_SHORT).

Dockerized Environment Variables

  • SERVER_ADDRESS
    Defaults to 0.0.0.0:8080. Change only if you are not deploying in a dockerized environment.

  • DB_HOST
    Defaults to db. Do not change if you are using the dockerized environment.

  • DB_PORT
    Defaults to 5432. Do not change if you are using the dockerized environment.

  • DB_NAME
    Defaults to prompt.

  • DB_USER
    Defaults to prompt-postgres.

  • DB_PASSWORD
    Defaults to prompt.

Keycloak Variables

Adjust these if deploying Keycloak on a different host:

  • KEYCLOAK_DB_USER
    Defaults to keycloak.

  • KEYCLOAK_DB_PASSWORD
    Defaults to keycloak.

  • KEYCLOAK_HOST
    Example: keycloak.ase.in.tum.de.

  • KEYCLOAK_REALM_NAME
    Defaults to prompt.

  • KEYCLOAK_CLIENT_ID
    Defaults to prompt-server.

  • KEYCLOAK_CLIENT_SECRET
    Generate this as described in the Keycloak setup section.

  • KEYCLOAK_ID_OF_CLIENT
    Example: a584ca61-fa83-4e95-98b6-c5f3157ae4b4 (change if not using pre-configuration).

  • KEYCLOAK_AUTHORIZED_PARTY
    Defaults to prompt-client.

  • KEYCLOAK_ADMIN
    Defaults to admin.

  • KEYCLOAK_ADMIN_PASSWORD
    Defaults to admin.

Deployment Version Variables

  • SERVER_IMAGE_TAG

  • CORE_IMAGE_TAG

  • TEMPLATE_IMAGE_TAG

  • INTERVIEW_IMAGE_TAG

  • MATCHING_IMAGE_TAG

Set these according to your deployment version (default is main).

SMTP Server Variables

  • SENDER_EMAIL
    Example: prompt@ase.cit.tum.de

  • SENDER_NAME
    Example: AET Mailing Service

  • SMTP_HOST
    Example: postfix

  • SMTP_PORT
    Defaults to 25

  • SMTP_USERNAME (Optional)
    Username for SMTP authentication. Leave empty if your SMTP server doesn’t require authentication.

  • SMTP_PASSWORD (Optional)
    Password for SMTP authentication. Leave empty if your SMTP server doesn’t require authentication.

3.2 Select the Appropriate Docker Compose File

  • docker-compose.prod.yml
    Does not include a Keycloak container. Use this file if you have an already running Keycloak instance.

  • docker-compose.extern.prod.yml
    Includes a Keycloak container. Refer to the Keycloak configuration above for details.

3.3 Start the Docker Containers

To start the docker containers, run the following command (adjust <path to your env file> as needed):

docker compose -f docker-compose.prod.yml --env-file=<path to your env file> up --pull=always -d