Skip to main content

Configuration Guide

In the following, we describe how to configure the system for deployment in different environments.

Backend​

The backend is configured through environment variables, which override the values set in resources/application.yml. Spring maps variable names to config keys by convention, e.g. SUBATO_PUBLIC_HOSTNAME corresponds to subato.public_hostname. The backend also needs to be configured with a Spring profile (SPRING_PROFILES_ACTIVE) for rendering HTML pages with the correct colors. The profile variable can be set to prod or test depending on the environment. The sections below should cover the most important configuration options. For the full list, see resources/application.yml.

Hostname​

If the backend is accessed through a proxy, set SUBATO_PUBLIC_HOSTNAME to the public hostname. If the public port differs too, include it as follows: SUBATO_PUBLIC_HOSTNAME=api.subato.cs.hs-rm.de:443.

This is required because relative URLs to images and other media in imported task descriptions get rewritten to absolute URLs when a task is fetched from the backend. By default, the absolute URL uses the hostname from the incoming HTTP request. However, if the backend is reached through a proxy over an internal address, those absolute URLs may not be reachable from outside. Thus, the public hostname needs to be set when using a proxy.

Task Pool Synchronization​

To access private git repositories, set the credentials through SUBATO_TASK_POOL_SYNC_GIT_USER (username) and SUBATO_TASK_POOL_SYNC_GIT_TOKEN (password).

Keycloak​

Set the Keycloak server URL through KEYCLOAK_AUTH_SERVER_URL and the realm through KEYCLOAK_REALM. Subato expects a client named subato-backend to exist. On every login, Subato automatically updates the users table with the user information provided by Keycloak, such as the first name and last name. Thus, Keycloak must be configured to map the claims listed in ClaimConstants into the access token. Moreover, users in Keycloak must be given the roles superadmin or staff for granting them their corresponding global roles in Subato.

At login, a user's degree program is also derived from Keycloak if the student_info attribute was set on the user and was mapped as a claim into the access token. The attribute value must have the following format:

1;DI;1;IAB;1;2017

Subato ignores the first three values (1, DI, 1). IAB identifies the degree program (pos_code), and 2017 identifies the year of examination regulations (po_year). If the degree_program table has an entry matching both pos_code and po_year, that program is assigned to the user.

Upload Limit​

File uploads are capped by a limit configurable through SPRING_SERVLET_MULTIPART_MAX_FILE_SIZE, in <size><unit> format (e.g. 30MB). This limit is communicated through the /config HTTP endpoint and displayed in the web app's file upload form.

Proxy configuration

If the backend is accessed through an HTTP proxy, make sure that the proxy is configured to allow at least the configured limit. Also note that the web app may not show a meaningful error message if a proxy returns a 413 Content Too Large response.

Mime-Type Detection​

The web app uses filenames to determine the MIME type of a file, which is necessary for correctly displaying it (e.g. syntax highlighting and indentation) and for validating submissions (e.g. distinguishing between source and binary files). Since automatic detection isn't always reliable given how many mime types exist, you may need to define overrides. Extend or override them with variables following this pattern:

SUBATO_MIME_0_MAP=.elm
SUBATO_MIME_0_AS=text/x-elm

SUBATO_MIME_1_MAP=.kt
SUBATO_MIME_1_AS=text/x-kotlin

# ...

Data Import​

At RheinMain University of Applied Sciences, we use the university's own AoR system for term planning. To automatically create courses, participants, and permissions from the data of such planning systems, a course must be linked to modules from degree programs when creating them. We use Python scripts to import core data (degree programs and modules) and term data (courses, participants, and permissions). If you are interested in these scripts, feel free to reach out.

For initializing a fresh database, you can use the seeding feature.

Backup​

A backup must include both the data directory (subato2-data) and the database. To back up the database, a dump must be created using the PostgreSQL pg_dump binary. Before creating the dump, ensure that the PostgreSQL version used for creating the dump matches the target environment. Additionally, the dump must not contain any CREATE DATABASE or ALTER DATABASE SET OWNER statements.

Web App​

The configuration is stored in the src/environments directory, with a separate file for each environment:

  • environment.ts — local/dev
  • environment.prod.ts — production
  • environment.test.ts — test

In addition, there is a environments/environment.common.ts file which provides the default config values for all environments. The remaining environment*.ts files are set up so that these values can be easily overridden.

Rebuild on change

Unlike the backend, the web app requires a rebuild on every configuration change. It currently can't be configured through environment variables.

Request Caching is configured through cashewConfig() in app.config.ts. Keycloak connection parameters (except for the URL) live there too.