Config Files

Both the backend and the runner are configured with a YAML config file each. The handling of the config files is the same, just the content (available attributes) is different.

File type and location

Note

This applies to both the backend and the runner. For the runner config just replace project-W with project-W-runner in the paths.

A config file has to be named config.yml. It can be in one of the following directories. They follow the XDG Base Directory Specification under Linux):

1. User config path: Under Linux this is $XDG_CONFIG_HOME/project-W (which usually is ~/.config/project-W)

2. Site config path: Under Linux this is the first entry of $XDG_CONFIG_DIRS concatenated with /project-W (which usually is /etc/xdg/project-W)

3. The source directory of the project_W python package (to be more specific: the directory that also contains the config.py module)

4. The current working directory (i.e. the directory from which you start the program)

These directories are searched in this order, and the first directory that contains a file called config.yml will be chosen. This means that for example a user can overwrite a system-wide configuration (in /etc/xdg/project-W) by putting their own config file into ~/.config/project-W.

Loading config attributes from environment variables

This works for both the backend and the runner.

Instead of explicitly entering static variables into the config file, you can also choose to dynamically load the value of a variable from the programs environment at startup time. This is especially useful if you don’t want to write secrets like the sessionSecretKey the smtp password or the runner token directly into the config file (e.g. if you keep your config files public).

To do use the !ENV Tag followed by the env var you want to load from with a dollar sign and curly brackets. For example if you want to load loginSecurity.sessionSecretKey from the env var JWT_SECRET_KEY, then you would write the following into your config file:

loginSecurity:
  sessionSecretKey: !ENV ${JWT_SECRET_KEY}

If you want you can also define a default value in case the env var isn’t defined by using a colon. For example if you want signups to be possible by default but you want to be able to disable them temporarily by setting the env var DISABLE_SIGNUP to true then you could write the following:

loginSecurity:
  disableSignup: !ENV ${DISABLE_SIGNUP:false}

For a full reference of the syntax and usage of this feature please refer to the readme of pyaml-env which we use to do this.

Description of backend config options

The following table gives an overview over all options available to you. All options printed in bolt letters must be set since they do not have any default value, however you probably also want to set ‘loginSecurity.sessionSecretKey’. For an example config, please refer to Backend & Frontend

type	object
properties
clientURL	URL under which the frontend is served. It is used for providing the user with clickable links inside of account-activation or password-reset emails. The URL should fullfill the following requirements: It has to start with either ‘http://’ or ‘https://’ It should contain the port number if it is not just 80 (default of http) or 443 (default of https) It should contain the root path under which the frontend is served if its not just / It should end with /# if the frontend uses hash based routing (which our frontend does!)
	type	string
	examples	https://example.com/#
		https://sub.example.org/apps/project-W/frontend/#
		http://localhost:5173/#
		http://192.168.1.100:5173/#
databasePath	Path under which the sqlite ‘database.db’ file will be stored. This database contains all backend data, so make sure to backup this directory. Changing this option for an existing installation without moving the file manually will result in the creation of a new empty database. The default value is the users data dir which under Linux is $XDG_DATA_HOME/project-W (most of the time this is ~/.local/share/project-W)
	type	string
	default	/home/docs/.local/share/project-W
loginSecurity	type	object
	properties
	sessionSecretKey	The secret key used to generate JWT Tokens. Make sure to keep this secret since with this key an attacker could log in as any user. A new key can be generated with the following command: python -c ‘import secrets; print(secrets.token_hex())’. If left to ‘None’, then the server will generate a secret key for you, however it will not put it into your config file! This means that the secret key will be different after every server restart which will invalidate all JWT Tokens. It is recommended to generate a secret key yourself using the command above.
		type	string / null
		default	None
	sessionExpirationTimeMinutes	Time for which a users/clients JWT Tokens stay valid (in minutes). After this time the user will be logged out automatically and has to authenticate again using their username and password.
		type	integer
		minimum	5
		default	60
	allowedEmailDomains	Allowed domains in email addresses. Users will only be able to sign up/change their email if their email address uses one of these domains (the part after the ‘@’). If left empty, then all email domains are allowed.
		type	array
		examples	uni-heidelberg.de
			stud.uni-heidelberg.de
		items	type	string
	disableSignup	Whether signup of new accounts should be possible. If set to ‘true’ then only users who already have an account will be able to use the service.
		type	boolean
smtpServer	type	object
	properties
	domain	FQDN of your smtp server.
		type	string
	port	Port that should be used for the smtp connection.
		type	integer
		maximum	65535
		minimum	0
	secure	Whether to use ssl, starttls or no encryption with the smtp server.
		type	string
	senderEmail	Email address from which emails will be sent to the users.
		type	string
	username	Username that should be used to authenticate with the smtp server. Most of the time this is the same as ‘senderEmail’.
		type	string
	password	Password that should be used to authenticate with the smtp server.
		type	string
disableOptionValidation	This disables the jsonschema validation of the provided config file. This means that the server will start and run even though it loaded possibly invalid data which may cause it to crash or not work proberly. Only set this to ‘true’ for development or testing purposes, never in production!
	type	boolean

Description of runner config options

The following table describes all config options for the runner config.

Name	Optional?	Description
runnerToken	No	The token that’s used to authenticate the runner to the backend.
backendURL	No	The URL where the backend is hosted.
modelCacheDir	Yes	Path to directory used to cache the Whisper models. If this is not set, $HOME/.cache/whisper/ is used.
torchDevice	Yes	The PyTorch device used by Whisper. If this is not set, the default device is used.