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):
The path passed to the program through the –custom_config_path cli option (if no path was passed then this will be skipped)
User config path: Under Linux this is $XDG_CONFIG_HOME/project-W (which usually is ~/.config/project-W)
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)
The source directory of the project_W python package (to be more specific: the directory that also contains the config.py module)
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 security.local_token.session_secret_key from the env var SECRET_KEY, then you would write the following into your config file:
security: local_token: session_secret_key: !ENV ${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 LOCAL_ACCOUNT_MODE to no_signup then you could write the following:
security: local_account: mode: !ENV ${LOCAL_ACCOUNT_MODE:enabled}
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 gives an overview over all config options available to you on the backend. For an example config, please refer to Backend, Frontend & background jobs
- pydantic model project_W.models.settings.Settings
Show JSON schema
{ "title": "Settings", "type": "object", "properties": { "client_url": { "description": "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 fulfill the following requirements:\n\n- It has to start with either 'http://' or 'https://'\n\n- It should contain the port number if it is not just 80 (default of http) or 443 (default of https)\n\n- It should contain the root path under which the frontend is served if its not just /\n- It should end with /# if the frontend uses hash based routing (which our frontend does!)", "examples": [ "https://example.com/#", "https://sub.example.org/apps/project-W/frontend/#", "http://localhost:5173/#", "http://192.168.1.100:5173/#" ], "pattern": "^(http|https):\\/\\/(([a-zA-Z0-9\\-]+\\.)+[a-zA-Z0-9\\-]+|localhost)(:[0-9]+)?((\\/[a-zA-Z0-9\\-]+)+)?(\\/#)?$", "title": "Client Url", "type": "string" }, "web_server": { "$ref": "#/$defs/WebServerSettings", "default": { "allowed_hosts": [ "*" ], "reverse_proxy": null, "ssl": null, "no_https": false, "worker_count": 1, "address": "0.0.0.0/32", "port": 5000 }, "description": "Settings regarding the web server deployment of this application" }, "postgres_connection_string": { "description": "PostgreSQL connection string to connect to the database that should be used by Project-W. See https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING for the syntax.", "format": "multi-host-uri", "minLength": 1, "title": "Postgres Connection String", "type": "string" }, "redis_connection": { "$ref": "#/$defs/RedisConnection" }, "security": { "$ref": "#/$defs/SecuritySettings" }, "smtp_server": { "$ref": "#/$defs/SMTPServerSettings" }, "imprint": { "anyOf": [ { "$ref": "#/$defs/ImprintSettings" }, { "type": "null" } ], "default": null, "description": "Set the imprint/impressum of this instance" }, "terms_of_services": { "additionalProperties": { "$ref": "#/$defs/TosSettings" }, "default": {}, "description": "Attribute set of terms of services. The user will have to accept to every one of these separately before they can use the service. The name of the set will be id of the term of service, don't change it once set!", "title": "Terms Of Services", "type": "object" }, "cleanup": { "$ref": "#/$defs/CleanupSettings", "default": { "finished_job_retention_in_days": null, "user_retention_in_days": null }, "description": "Settings regarding cleanups of this server's database. This requires the cronjob to be set up correctly!" } }, "$defs": { "CleanupSettings": { "additionalProperties": false, "properties": { "finished_job_retention_in_days": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "description": "For how long to keep finished jobs. If a job is older than this it can be cleaned up by the database cleanup task (please note that you have to setup this task as a cronjob or use the cronjob docker container!). If set to None then job cleanup is disabled", "title": "Finished Job Retention In Days" }, "user_retention_in_days": { "anyOf": [ { "minimum": 90, "type": "integer" }, { "type": "null" } ], "default": null, "description": "For how long to keep users and their data. If a user hasn't logged in to Project-W in the specified time frame then the user may be deleted (please note that you have to setup this task as a cronjob or use the cronjob docker container!). If set to None then job cleanup is disabled", "title": "User Retention In Days" } }, "title": "CleanupSettings", "type": "object" }, "EmailValidated": { "title": "EmailValidated", "type": "string" }, "ImprintSettings": { "additionalProperties": false, "properties": { "name": { "description": "The name of the person/institution hosting this instance", "title": "Name", "type": "string" }, "email": { "anyOf": [ { "$ref": "#/$defs/EmailValidated" }, { "type": "null" } ], "default": null, "description": "A contact email address of the person/institution hosting this instance" }, "url": { "anyOf": [ { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "The URL to forward users to if they click on the imprint button on the frontend. Useful if you want to link to an imprint on a different website instead of having a dedicated imprint for Project-W. Mutually exclusive with the 'additional_imprint_html' option.", "title": "Url" }, "additional_imprint_html": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Content of the imprint in addition to the name and email fields. Mutually exclusive with the 'url' option.", "title": "Additional Imprint Html" } }, "required": [ "name" ], "title": "ImprintSettings", "type": "object" }, "LdapAuthMechanismEnum": { "enum": [ "SIMPLE", "DIGEST-MD5", "NTLM" ], "title": "LdapAuthMechanismEnum", "type": "string" }, "LdapAuthSettings": { "additionalProperties": false, "properties": { "mechanism": { "$ref": "#/$defs/LdapAuthMechanismEnum", "default": "SIMPLE", "description": "Authentication mechanism that should be used. Can be one of 'SIMPLE', 'DIGEST-MD5' or 'NTLM'" }, "user": { "description": "Identification of binding user.", "title": "User", "type": "string" }, "password": { "description": "Password of binding user.", "format": "password", "title": "Password", "type": "string", "writeOnly": true } }, "required": [ "user", "password" ], "title": "LdapAuthSettings", "type": "object" }, "LdapProviderSettings": { "additionalProperties": false, "properties": { "hidden": { "default": false, "description": "Whether this provider should not be advertised to the user on the frontend. Useful if this provider should only provide admin accounts.", "title": "Hidden", "type": "boolean" }, "icon_url": { "anyOf": [ { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to a square icon that will be shown to the user in the frontend next to the 'Login with <name>' to visually represent the account/identity provider. Should be a link to a square png with transparent background, or alternatively to a svg", "examples": [ "https://ssl.gstatic.com/images/branding/googleg/2x/googleg_standard_color_64dp.png" ], "title": "Icon Url" }, "allow_creation_of_api_tokens": { "default": true, "description": "If set to true then users logged in from this identity provider can create api tokens with infinite lifetime. These tokens will be automatically invalidated if the user gets deleted from the identity provider ones the periodic background job gets called. Run the periodic background task more often to get user access revoked quicker.", "title": "Allow Creation Of Api Tokens", "type": "boolean" }, "ca_pem_file_path": { "anyOf": [ { "format": "file-path", "type": "string" }, { "type": "null" } ], "default": null, "description": "Path to the pem certs file that includes the certificates that should be trusted for this provider (alternative certificate verification). Useful if the identity provider uses a self-signed certificate", "title": "Ca Pem File Path" }, "server_address": { "description": "Address of the ldap server. Should start with either ldap://, ldaps:// or ldapi:// depending on whether the connection should be unencrypted, ssl/tls encrypted or if it's an URL-encoded filesocket connection", "examples": [ "ldap://example.org", "ldaps://example.org", "ldapi://%2Frun%2Fslapd%2Fldapi" ], "format": "uri", "minLength": 1, "title": "Server Address", "type": "string" }, "username_attributes": { "description": "A list of attribute/field names which contain strings that can be used by the user as a username during login. Project-W will use them to generate an LDAP filter expression and merge it with your provided filter expression like this: (&(<your filter expression>)(|(<username_attribute1>=<username>)(<username_attribute2>=<username>)...))", "examples": [ [ "name" ], [ "name", "mail" ], [ "displayname", "email" ] ], "items": { "type": "string" }, "title": "Username Attributes", "type": "array" }, "uid_attribute": { "description": "The attribute/field name that contains a unique user identifier. Doesn't have to be the same as one of the username_attributes, but can be. Make sure that this identifier is unique to a user across the LDAP directory and will never change/be reassigned to a different user! Every LDAP user that the filter expression can return should have this attribute exactly ones. This attribute in combination with the filter expression will be used to query users outside of the regular login flow.", "examples": [ "uid", "uuid" ], "title": "Uid Attribute", "type": "string" }, "mail_attribute": { "description": "The attribute/field name that contains the email address of a user. Every LDAP user that the filter expression can return should have this attribute exactly ones.", "examples": [ "mail", "email", "mail1" ], "title": "Mail Attribute", "type": "string" }, "user_query": { "anyOf": [ { "$ref": "#/$defs/LdapQuerySettings" }, { "type": "null" } ], "default": null, "description": "Settings that define how normal users should be queried from the ldap server. If left to None then no normal user will be able to sign in using this provider" }, "admin_query": { "anyOf": [ { "$ref": "#/$defs/LdapQuerySettings" }, { "type": "null" } ], "default": null, "description": "Settings that define how admin users should be queried from the ldap server. If left to None then no admin user will be able to sign in (with admin privileges) using this provider" }, "service_account_auth": { "$ref": "#/$defs/LdapAuthSettings", "description": " This user should be a service account with read permissions on all other users and their mail (and any other attributes used in the query, e.g. memberof)." } }, "required": [ "server_address", "username_attributes", "uid_attribute", "mail_attribute", "service_account_auth" ], "title": "LdapProviderSettings", "type": "object" }, "LdapQuerySettings": { "additionalProperties": false, "properties": { "base_dn": { "description": "The base DN under which should be searched", "examples": [ "dc=example,dc=org" ], "title": "Base Dn", "type": "string" }, "filter": { "description": "Ldap filter expression that that will be merged with the user attribute filters.", "examples": [ "(class=person)(&(class=person)(memberof=spn=project-W-users@localhost)(&(class=account)(memberof=spn=project-W-admins@localhost))" ], "title": "Filter", "type": "string" } }, "required": [ "base_dn", "filter" ], "title": "LdapQuerySettings", "type": "object" }, "LocalAccountOperationModeEnum": { "enum": [ "disabled", "no_signup_hidden", "no_signup", "enabled" ], "title": "LocalAccountOperationModeEnum", "type": "string" }, "LocalAccountSettings": { "additionalProperties": false, "properties": { "mode": { "$ref": "#/$defs/LocalAccountOperationModeEnum", "default": "enabled", "description": "\n To what extend local accounts should be enabled.\n - enabled: Both login and signup possible and advertised in frontend to users (default).\n - no_signup: Login possible and advertised to users, signup not. Thus users can only login using already existing accounts (created through provisioning or by signup before this setting was set). Use this for example if you want users to login using local accounts that you created for them through provisioning.\n - no_signup_hidden: Login still possible but not advertised to users in the frontend. Especially helpful if the only local accounts should be provisioned admin accounts for administration purposes while normal users should only login using oidc or ldap accounts.\n - disabled: no login, no signup, no provisioned accounts. Login only through ldap and oidc. Please note that in this case you need to provide admin accounts through ldap or oidc as well!\n " }, "allowed_email_domains": { "default": [], "items": { "description": "Allowed domains in email addresses. Users will only be able to sign up/change their email of their local accounts if their email address uses one of these domains (the part after the '@'). If left empty, then all email domains are allowed.", "examples": [ "uni-heidelberg.de", "stud.uni-heidelberg.de" ], "pattern": "^([a-zA-Z0-9\\-]+\\.)+[a-zA-Z0-9\\-]+$", "type": "string" }, "title": "Allowed Email Domains", "type": "array" }, "allow_creation_of_api_tokens": { "default": true, "description": "If set to true then users logged in with local accounts can create api tokens with infinite lifetime. They will get invalidated if the user gets deleted.", "title": "Allow Creation Of Api Tokens", "type": "boolean" }, "user_provisioning": { "additionalProperties": { "$ref": "#/$defs/ProvisionedUser" }, "default": {}, "description": "Attribute set of users that should be created beforehand. Give every provisioned user a number using the key of this attribute set. This way the users email, password and admin privileges can still be changed later on using this config file. Warning: Deleting a user from this dict will not delete it from the application or database, use the /user/delete route for this!", "examples": [ "0: {<ProvisionedUserSettings>}", "1: {<ProvisionedUserSettings>}" ], "title": "User Provisioning", "type": "object" } }, "title": "LocalAccountSettings", "type": "object" }, "OidcProviderSettings": { "additionalProperties": false, "properties": { "hidden": { "default": false, "description": "Whether this provider should not be advertised to the user on the frontend. Useful if this provider should only provide admin accounts.", "title": "Hidden", "type": "boolean" }, "icon_url": { "anyOf": [ { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to a square icon that will be shown to the user in the frontend next to the 'Login with <name>' to visually represent the account/identity provider. Should be a link to a square png with transparent background, or alternatively to a svg", "examples": [ "https://ssl.gstatic.com/images/branding/googleg/2x/googleg_standard_color_64dp.png" ], "title": "Icon Url" }, "allow_creation_of_api_tokens": { "default": true, "description": "If set to true then users logged in from this identity provider can create api tokens with infinite lifetime. These tokens will be automatically invalidated if the user gets deleted from the identity provider ones the periodic background job gets called. Run the periodic background task more often to get user access revoked quicker.", "title": "Allow Creation Of Api Tokens", "type": "boolean" }, "ca_pem_file_path": { "anyOf": [ { "format": "file-path", "type": "string" }, { "type": "null" } ], "default": null, "description": "Path to the pem certs file that includes the certificates that should be trusted for this provider (alternative certificate verification). Useful if the identity provider uses a self-signed certificate", "title": "Ca Pem File Path" }, "base_url": { "description": "Base url of the OIDC provider. If '/.well-known/openid-configuration' is appended to it it should return its metadata", "examples": [ "https://accounts.google.com", "https://appleid.apple.com" ], "format": "uri", "maxLength": 2083, "minLength": 1, "title": "Base Url", "type": "string" }, "client_id": { "description": "The client_id string as returned by the identity provider after setting up this application", "title": "Client Id", "type": "string" }, "client_secret": { "description": "The client_secret string as returned by the identity provider after setting up this application", "format": "password", "title": "Client Secret", "type": "string", "writeOnly": true }, "enable_pkce_s256_challenge": { "default": true, "description": "Whether the PKCE flow using the S256 challenge method should be enabled. The OIDC provider has to support this.", "title": "Enable Pkce S256 Challenge", "type": "boolean" }, "user_role": { "anyOf": [ { "$ref": "#/$defs/OidcRoleSettings" }, { "type": "null" } ], "default": null, "description": "Configure the role that users should have to be able to access this Project-W instance. Every user who doesn't have this role in their id token won't be able to use this service. Set to None if all users of this IdP should be able to access it" }, "admin_role": { "anyOf": [ { "$ref": "#/$defs/OidcRoleSettings" }, { "type": "null" } ], "default": null, "description": "Configure the role that users should have to be have admin permissions on Project-W. Only users with this role can do things like create new runners and see all user data. Use carefully! Set to None if no users of this IdP should be admins" } }, "required": [ "base_url", "client_id", "client_secret" ], "title": "OidcProviderSettings", "type": "object" }, "OidcRoleSettings": { "additionalProperties": false, "properties": { "name": { "description": "Name of the required role/group", "examples": [ "project-W-users", "project-W-admins", "admins", "employees" ], "title": "Name", "type": "string" }, "field_name": { "description": "Name of the field/claim under which the role list is available in the id token", "examples": [ "roles", "groups" ], "title": "Field Name", "type": "string" } }, "required": [ "name", "field_name" ], "title": "OidcRoleSettings", "type": "object" }, "ProvisionedUser": { "additionalProperties": false, "properties": { "email": { "$ref": "#/$defs/EmailValidated", "description": "Email address of this user. This address will be treated as a verified email address, so make sure that it is valid", "examples": [ "admin@example.org", "user@example.org" ] }, "password": { "description": "The password of this user (for login). Please make sure that this password is secure, especially when provisioning admin users!", "format": "password", "minLength": 12, "title": "Password", "type": "string", "writeOnly": true }, "is_admin": { "default": false, "description": "Whether this user should be an admin user. Be very careful with this, admin users have full access over all other users and their data! Warning: Revoking a users admin privileges over provisioning settings will currently not revoke any existing access tokens of that user, don't rely on that!", "title": "Is Admin", "type": "boolean" } }, "required": [ "email", "password" ], "title": "ProvisionedUser", "type": "object" }, "RedisConnection": { "properties": { "connection_string": { "anyOf": [ { "format": "uri", "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Redis connection string to connect to the caching database that should be used by Project-W.", "title": "Connection String" }, "unix_socket_path": { "anyOf": [ { "format": "path", "type": "string" }, { "type": "null" } ], "default": null, "description": "Path to a redis unix socket. Can be used instead of connection_string", "title": "Unix Socket Path" } }, "title": "RedisConnection", "type": "object" }, "ReverseProxySettings": { "additionalProperties": false, "properties": { "trusted_proxies": { "description": "List of IP addresses to trust as the proxy from which traffic originates", "items": { "type": "string" }, "title": "Trusted Proxies", "type": "array" }, "root_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Set this option to your path prefix if you want to serve Project-W from a root path prefix at your proxy", "title": "Root Path" } }, "required": [ "trusted_proxies" ], "title": "ReverseProxySettings", "type": "object" }, "SMTPSecureEnum": { "enum": [ "ssl", "starttls", "plain" ], "title": "SMTPSecureEnum", "type": "string" }, "SMTPServerSettings": { "additionalProperties": false, "properties": { "hostname": { "description": "FQDN of your smtp server.", "pattern": "^([a-zA-Z0-9\\-]+\\.)+[a-zA-Z0-9\\-]+|localhost$", "title": "Hostname", "type": "string" }, "port": { "default": 587, "description": "Port that should be used for the smtp connection.", "maximum": 65535, "minimum": 0, "title": "Port", "type": "integer" }, "secure": { "$ref": "#/$defs/SMTPSecureEnum", "default": "starttls", "description": "Whether to use 'ssl', 'starttls' or no encryption ('plain') with the smtp server." }, "sender_email": { "$ref": "#/$defs/EmailValidated", "description": "Email address from which emails will be sent to the users." }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Username that should be used to authenticate with the smtp server. Most of the time this is the same as 'senderEmail'.", "title": "Username" }, "password": { "anyOf": [ { "format": "password", "type": "string", "writeOnly": true }, { "type": "null" } ], "default": null, "description": "Password that should be used to authenticate with the smtp server.", "title": "Password" } }, "required": [ "hostname", "sender_email" ], "title": "SMTPServerSettings", "type": "object" }, "SecretKeyValidated": { "format": "password", "title": "SecretKeyValidated", "type": "string", "writeOnly": true }, "SecuritySettings": { "additionalProperties": false, "properties": { "secret_key": { "$ref": "#/$defs/SecretKeyValidated", "description": "The secret key used to sign payloads in emails. 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(32))'`." }, "local_account": { "$ref": "#/$defs/LocalAccountSettings", "default": { "mode": "enabled", "allowed_email_domains": [], "allow_creation_of_api_tokens": true, "user_provisioning": {} } }, "tokens": { "$ref": "#/$defs/TokenSettings", "default": { "session_expiration_time_minutes": 60, "rolling_session_before_expiration_minutes": 10 } }, "oidc_providers": { "additionalProperties": { "$ref": "#/$defs/OidcProviderSettings" }, "default": {}, "description": "Attribute set of identity providers. The name of the set will be shown to users in a form like this: 'Login with <provider name>'.", "examples": [ "Google: {<ProviderSettings>}", "Apple: {<ProviderSettings>}" ], "title": "Oidc Providers", "type": "object" }, "ldap_providers": { "additionalProperties": { "$ref": "#/$defs/LdapProviderSettings" }, "default": {}, "description": "Attribute set of identity providers. The name of the set will be shown to users in a form like this: 'Login with <provider name>'.", "examples": [ "Google: {<ProviderSettings>}", "Apple: {<ProviderSettings>}" ], "title": "Ldap Providers", "type": "object" } }, "required": [ "secret_key" ], "title": "SecuritySettings", "type": "object" }, "SslSettings": { "additionalProperties": false, "properties": { "cert_file": { "description": "Path to the SSL certificate file", "format": "file-path", "title": "Cert File", "type": "string" }, "key_file": { "description": "Path to the SSL key file", "format": "file-path", "title": "Key File", "type": "string" }, "key_file_password": { "anyOf": [ { "format": "password", "type": "string", "writeOnly": true }, { "type": "null" } ], "default": null, "description": "Password of the SSL key file", "title": "Key File Password" } }, "required": [ "cert_file", "key_file" ], "title": "SslSettings", "type": "object" }, "TokenSettings": { "additionalProperties": false, "properties": { "session_expiration_time_minutes": { "default": 60, "description": "Time for which auth tokens stay valid (not API tokens, they stay valid indefinitely). Project-W uses rolling tokens, so beginning from 10 minutes before expiration the auth token will be rotated automatically to prevent active users from being logged out. Inactive users however will be logged out after this period. Increase if you want to keep inactive users logged in for longer (on the prize of a higher risk of the auth token being stolen)", "minimum": 15, "title": "Session Expiration Time Minutes", "type": "integer" }, "rolling_session_before_expiration_minutes": { "default": 10, "description": "The amount of minutes before a token expires when a user should get a new auth token if the user is still active", "minimum": 5, "title": "Rolling Session Before Expiration Minutes", "type": "integer" } }, "title": "TokenSettings", "type": "object" }, "TosSettings": { "additionalProperties": false, "properties": { "name": { "description": "The name of this term of service. This will be shown as a title above the tos_html content in the frontend", "title": "Name", "type": "string" }, "version": { "description": "The version of this term of service. Start by putting this to 1. When incremented then users will have to re-accept these terms.", "minimum": 1, "title": "Version", "type": "integer" }, "tos_html": { "description": "The terms of services in html format. You may include links to external websites if you want.", "title": "Tos Html", "type": "string" } }, "required": [ "name", "version", "tos_html" ], "title": "TosSettings", "type": "object" }, "WebServerSettings": { "additionalProperties": false, "properties": { "allowed_hosts": { "default": [ "*" ], "description": "List of domains that are allowed as hostnames. Wildcard domains supported", "items": { "type": "string" }, "title": "Allowed Hosts", "type": "array" }, "reverse_proxy": { "anyOf": [ { "$ref": "#/$defs/ReverseProxySettings" }, { "type": "null" } ], "default": null, "description": "Settings for when running Project-W behind a Reverse Proxy" }, "ssl": { "anyOf": [ { "$ref": "#/$defs/SslSettings" }, { "type": "null" } ], "default": null, "description": "SSL settings to enable https encrypted traffic" }, "no_https": { "default": false, "description": "Disable https encryption. This will lead to passwords, sensitive data and more to be transmitted unencrypted! Only set this for development or testing purposes!", "title": "No Https", "type": "boolean" }, "worker_count": { "default": 1, "description": "Amount of workers that should serve the web server simultaneously. Increasing this will allow for more concurrent users as long as it is lower or equal than the amount of CPU cores on your system.", "title": "Worker Count", "type": "integer" }, "address": { "default": "0.0.0.0/32", "description": "The address of the interface under which the web server should be served.", "format": "ipvanyinterface", "title": "Address", "type": "string" }, "port": { "default": 5000, "description": "The port under which the web server should be served. The default port is 5000 regardless of whether https is enabled or not. This shouldn't be changed in a docker deployment because that would break the docker container's health check. Use docker's port mapping feature instead.", "maximum": 65535, "minimum": 0, "title": "Port", "type": "integer" } }, "title": "WebServerSettings", "type": "object" } }, "additionalProperties": false, "required": [ "client_url", "postgres_connection_string", "redis_connection", "security", "smtp_server" ] }
- field cleanup: CleanupSettings = CleanupSettings(finished_job_retention_in_days=None, user_retention_in_days=None)
Settings regarding cleanups of this server’s database. This requires the cronjob to be set up correctly!
- field client_url: str [Required]
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 fulfill the following requirements:
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!)
- Constraints:
pattern = ^(http|https)://(([a-zA-Z0-9-]+.)+[a-zA-Z0-9-]+|localhost)(:[0-9]+)?((/[a-zA-Z0-9-]+)+)?(/#)?$
- field imprint: ImprintSettings | None = None
Set the imprint/impressum of this instance
- field postgres_connection_string: PostgresDsn [Required]
PostgreSQL connection string to connect to the database that should be used by Project-W. See https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING for the syntax.
- field redis_connection: RedisConnection [Required]
- field security: SecuritySettings [Required]
- field smtp_server: SMTPServerSettings [Required]
- field terms_of_services: Annotated[dict[int, TosSettings], FieldInfo(annotation=NoneType, required=True, description="Attribute set of terms of services. The user will have to accept to every one of these separately before they can use the service. The name of the set will be id of the term of service, don't change it once set!")] = {}
Attribute set of terms of services. The user will have to accept to every one of these separately before they can use the service. The name of the set will be id of the term of service, don’t change it once set!
- field web_server: WebServerSettings = WebServerSettings(allowed_hosts=['*'], reverse_proxy=None, ssl=None, no_https=False, worker_count=1, address=IPv4Interface('0.0.0.0/32'), port=5000)
Settings regarding the web server deployment of this application
Refer below to each of the fields and their subfields and subsubfields and so on:
- pydantic model project_W.models.settings.CleanupSettings
Show JSON schema
{ "title": "CleanupSettings", "type": "object", "properties": { "finished_job_retention_in_days": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ], "default": null, "description": "For how long to keep finished jobs. If a job is older than this it can be cleaned up by the database cleanup task (please note that you have to setup this task as a cronjob or use the cronjob docker container!). If set to None then job cleanup is disabled", "title": "Finished Job Retention In Days" }, "user_retention_in_days": { "anyOf": [ { "minimum": 90, "type": "integer" }, { "type": "null" } ], "default": null, "description": "For how long to keep users and their data. If a user hasn't logged in to Project-W in the specified time frame then the user may be deleted (please note that you have to setup this task as a cronjob or use the cronjob docker container!). If set to None then job cleanup is disabled", "title": "User Retention In Days" } }, "additionalProperties": false }
- field finished_job_retention_in_days: int | None = None
For how long to keep finished jobs. If a job is older than this it can be cleaned up by the database cleanup task (please note that you have to setup this task as a cronjob or use the cronjob docker container!). If set to None then job cleanup is disabled
- Constraints:
ge = 1
- field user_retention_in_days: int | None = None
For how long to keep users and their data. If a user hasn’t logged in to Project-W in the specified time frame then the user may be deleted (please note that you have to setup this task as a cronjob or use the cronjob docker container!). If set to None then job cleanup is disabled
- Constraints:
ge = 90
- pydantic model project_W.models.settings.ImprintSettings
Show JSON schema
{ "title": "ImprintSettings", "type": "object", "properties": { "name": { "description": "The name of the person/institution hosting this instance", "title": "Name", "type": "string" }, "email": { "anyOf": [ { "$ref": "#/$defs/EmailValidated" }, { "type": "null" } ], "default": null, "description": "A contact email address of the person/institution hosting this instance" }, "url": { "anyOf": [ { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "The URL to forward users to if they click on the imprint button on the frontend. Useful if you want to link to an imprint on a different website instead of having a dedicated imprint for Project-W. Mutually exclusive with the 'additional_imprint_html' option.", "title": "Url" }, "additional_imprint_html": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Content of the imprint in addition to the name and email fields. Mutually exclusive with the 'url' option.", "title": "Additional Imprint Html" } }, "$defs": { "EmailValidated": { "title": "EmailValidated", "type": "string" } }, "additionalProperties": false, "required": [ "name" ] }
- field additional_imprint_html: str | None = None
Content of the imprint in addition to the name and email fields. Mutually exclusive with the ‘url’ option.
- Validated by:
exactly_one_of_url_additional_imprint_html
- field email: EmailValidated | None = None
A contact email address of the person/institution hosting this instance
- Validated by:
exactly_one_of_url_additional_imprint_html
- field name: str [Required]
The name of the person/institution hosting this instance
- Validated by:
exactly_one_of_url_additional_imprint_html
- field url: HttpUrl | None = None
The URL to forward users to if they click on the imprint button on the frontend. Useful if you want to link to an imprint on a different website instead of having a dedicated imprint for Project-W. Mutually exclusive with the ‘additional_imprint_html’ option.
- Validated by:
exactly_one_of_url_additional_imprint_html
- class project_W.models.settings.LdapAuthMechanismEnum(*values)
- pydantic model project_W.models.settings.LdapAuthSettings
Show JSON schema
{ "title": "LdapAuthSettings", "type": "object", "properties": { "mechanism": { "$ref": "#/$defs/LdapAuthMechanismEnum", "default": "SIMPLE", "description": "Authentication mechanism that should be used. Can be one of 'SIMPLE', 'DIGEST-MD5' or 'NTLM'" }, "user": { "description": "Identification of binding user.", "title": "User", "type": "string" }, "password": { "description": "Password of binding user.", "format": "password", "title": "Password", "type": "string", "writeOnly": true } }, "$defs": { "LdapAuthMechanismEnum": { "enum": [ "SIMPLE", "DIGEST-MD5", "NTLM" ], "title": "LdapAuthMechanismEnum", "type": "string" } }, "additionalProperties": false, "required": [ "user", "password" ] }
- field mechanism: LdapAuthMechanismEnum = LdapAuthMechanismEnum.SIMPLE
Authentication mechanism that should be used. Can be one of ‘SIMPLE’, ‘DIGEST-MD5’ or ‘NTLM’
- field password: SecretStr [Required]
Password of binding user.
- field user: str [Required]
Identification of binding user.
- pydantic model project_W.models.settings.LdapProviderSettings
Show JSON schema
{ "title": "LdapProviderSettings", "type": "object", "properties": { "hidden": { "default": false, "description": "Whether this provider should not be advertised to the user on the frontend. Useful if this provider should only provide admin accounts.", "title": "Hidden", "type": "boolean" }, "icon_url": { "anyOf": [ { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to a square icon that will be shown to the user in the frontend next to the 'Login with <name>' to visually represent the account/identity provider. Should be a link to a square png with transparent background, or alternatively to a svg", "examples": [ "https://ssl.gstatic.com/images/branding/googleg/2x/googleg_standard_color_64dp.png" ], "title": "Icon Url" }, "allow_creation_of_api_tokens": { "default": true, "description": "If set to true then users logged in from this identity provider can create api tokens with infinite lifetime. These tokens will be automatically invalidated if the user gets deleted from the identity provider ones the periodic background job gets called. Run the periodic background task more often to get user access revoked quicker.", "title": "Allow Creation Of Api Tokens", "type": "boolean" }, "ca_pem_file_path": { "anyOf": [ { "format": "file-path", "type": "string" }, { "type": "null" } ], "default": null, "description": "Path to the pem certs file that includes the certificates that should be trusted for this provider (alternative certificate verification). Useful if the identity provider uses a self-signed certificate", "title": "Ca Pem File Path" }, "server_address": { "description": "Address of the ldap server. Should start with either ldap://, ldaps:// or ldapi:// depending on whether the connection should be unencrypted, ssl/tls encrypted or if it's an URL-encoded filesocket connection", "examples": [ "ldap://example.org", "ldaps://example.org", "ldapi://%2Frun%2Fslapd%2Fldapi" ], "format": "uri", "minLength": 1, "title": "Server Address", "type": "string" }, "username_attributes": { "description": "A list of attribute/field names which contain strings that can be used by the user as a username during login. Project-W will use them to generate an LDAP filter expression and merge it with your provided filter expression like this: (&(<your filter expression>)(|(<username_attribute1>=<username>)(<username_attribute2>=<username>)...))", "examples": [ [ "name" ], [ "name", "mail" ], [ "displayname", "email" ] ], "items": { "type": "string" }, "title": "Username Attributes", "type": "array" }, "uid_attribute": { "description": "The attribute/field name that contains a unique user identifier. Doesn't have to be the same as one of the username_attributes, but can be. Make sure that this identifier is unique to a user across the LDAP directory and will never change/be reassigned to a different user! Every LDAP user that the filter expression can return should have this attribute exactly ones. This attribute in combination with the filter expression will be used to query users outside of the regular login flow.", "examples": [ "uid", "uuid" ], "title": "Uid Attribute", "type": "string" }, "mail_attribute": { "description": "The attribute/field name that contains the email address of a user. Every LDAP user that the filter expression can return should have this attribute exactly ones.", "examples": [ "mail", "email", "mail1" ], "title": "Mail Attribute", "type": "string" }, "user_query": { "anyOf": [ { "$ref": "#/$defs/LdapQuerySettings" }, { "type": "null" } ], "default": null, "description": "Settings that define how normal users should be queried from the ldap server. If left to None then no normal user will be able to sign in using this provider" }, "admin_query": { "anyOf": [ { "$ref": "#/$defs/LdapQuerySettings" }, { "type": "null" } ], "default": null, "description": "Settings that define how admin users should be queried from the ldap server. If left to None then no admin user will be able to sign in (with admin privileges) using this provider" }, "service_account_auth": { "$ref": "#/$defs/LdapAuthSettings", "description": " This user should be a service account with read permissions on all other users and their mail (and any other attributes used in the query, e.g. memberof)." } }, "$defs": { "LdapAuthMechanismEnum": { "enum": [ "SIMPLE", "DIGEST-MD5", "NTLM" ], "title": "LdapAuthMechanismEnum", "type": "string" }, "LdapAuthSettings": { "additionalProperties": false, "properties": { "mechanism": { "$ref": "#/$defs/LdapAuthMechanismEnum", "default": "SIMPLE", "description": "Authentication mechanism that should be used. Can be one of 'SIMPLE', 'DIGEST-MD5' or 'NTLM'" }, "user": { "description": "Identification of binding user.", "title": "User", "type": "string" }, "password": { "description": "Password of binding user.", "format": "password", "title": "Password", "type": "string", "writeOnly": true } }, "required": [ "user", "password" ], "title": "LdapAuthSettings", "type": "object" }, "LdapQuerySettings": { "additionalProperties": false, "properties": { "base_dn": { "description": "The base DN under which should be searched", "examples": [ "dc=example,dc=org" ], "title": "Base Dn", "type": "string" }, "filter": { "description": "Ldap filter expression that that will be merged with the user attribute filters.", "examples": [ "(class=person)(&(class=person)(memberof=spn=project-W-users@localhost)(&(class=account)(memberof=spn=project-W-admins@localhost))" ], "title": "Filter", "type": "string" } }, "required": [ "base_dn", "filter" ], "title": "LdapQuerySettings", "type": "object" } }, "additionalProperties": false, "required": [ "server_address", "username_attributes", "uid_attribute", "mail_attribute", "service_account_auth" ] }
- field admin_query: LdapQuerySettings | None = None
Settings that define how admin users should be queried from the ldap server. If left to None then no admin user will be able to sign in (with admin privileges) using this provider
- field allow_creation_of_api_tokens: bool = True
If set to true then users logged in from this identity provider can create api tokens with infinite lifetime. These tokens will be automatically invalidated if the user gets deleted from the identity provider ones the periodic background job gets called. Run the periodic background task more often to get user access revoked quicker.
- field ca_pem_file_path: FilePath | None = None
Path to the pem certs file that includes the certificates that should be trusted for this provider (alternative certificate verification). Useful if the identity provider uses a self-signed certificate
Whether this provider should not be advertised to the user on the frontend. Useful if this provider should only provide admin accounts.
- field icon_url: HttpUrl | None = None
URL to a square icon that will be shown to the user in the frontend next to the ‘Login with <name>’ to visually represent the account/identity provider. Should be a link to a square png with transparent background, or alternatively to a svg
- field mail_attribute: str [Required]
The attribute/field name that contains the email address of a user. Every LDAP user that the filter expression can return should have this attribute exactly ones.
- field server_address: Annotated[Url, UrlConstraints(max_length=None, allowed_schemes=['ldap', 'ldaps', 'ldapi'], host_required=None, default_host=None, default_port=None, default_path=None)] [Required]
Address of the ldap server. Should start with either ldap://, ldaps:// or ldapi:// depending on whether the connection should be unencrypted, ssl/tls encrypted or if it’s an URL-encoded filesocket connection
- Constraints:
allowed_schemes = [‘ldap’, ‘ldaps’, ‘ldapi’]
- field service_account_auth: LdapAuthSettings [Required]
This user should be a service account with read permissions on all other users and their mail (and any other attributes used in the query, e.g. memberof).
- field uid_attribute: str [Required]
The attribute/field name that contains a unique user identifier. Doesn’t have to be the same as one of the username_attributes, but can be. Make sure that this identifier is unique to a user across the LDAP directory and will never change/be reassigned to a different user! Every LDAP user that the filter expression can return should have this attribute exactly ones. This attribute in combination with the filter expression will be used to query users outside of the regular login flow.
- field user_query: LdapQuerySettings | None = None
Settings that define how normal users should be queried from the ldap server. If left to None then no normal user will be able to sign in using this provider
- field username_attributes: list[str] [Required]
A list of attribute/field names which contain strings that can be used by the user as a username during login. Project-W will use them to generate an LDAP filter expression and merge it with your provided filter expression like this: (&(<your filter expression>)(|(<username_attribute1>=<username>)(<username_attribute2>=<username>)…))
- pydantic model project_W.models.settings.LdapQuerySettings
Show JSON schema
{ "title": "LdapQuerySettings", "type": "object", "properties": { "base_dn": { "description": "The base DN under which should be searched", "examples": [ "dc=example,dc=org" ], "title": "Base Dn", "type": "string" }, "filter": { "description": "Ldap filter expression that that will be merged with the user attribute filters.", "examples": [ "(class=person)(&(class=person)(memberof=spn=project-W-users@localhost)(&(class=account)(memberof=spn=project-W-admins@localhost))" ], "title": "Filter", "type": "string" } }, "additionalProperties": false, "required": [ "base_dn", "filter" ] }
- field base_dn: str [Required]
The base DN under which should be searched
- field filter: str [Required]
Ldap filter expression that that will be merged with the user attribute filters.
- pydantic model project_W.models.settings.LocalAccountSettings
Show JSON schema
{ "title": "LocalAccountSettings", "type": "object", "properties": { "mode": { "$ref": "#/$defs/LocalAccountOperationModeEnum", "default": "enabled", "description": "\n To what extend local accounts should be enabled.\n - enabled: Both login and signup possible and advertised in frontend to users (default).\n - no_signup: Login possible and advertised to users, signup not. Thus users can only login using already existing accounts (created through provisioning or by signup before this setting was set). Use this for example if you want users to login using local accounts that you created for them through provisioning.\n - no_signup_hidden: Login still possible but not advertised to users in the frontend. Especially helpful if the only local accounts should be provisioned admin accounts for administration purposes while normal users should only login using oidc or ldap accounts.\n - disabled: no login, no signup, no provisioned accounts. Login only through ldap and oidc. Please note that in this case you need to provide admin accounts through ldap or oidc as well!\n " }, "allowed_email_domains": { "default": [], "items": { "description": "Allowed domains in email addresses. Users will only be able to sign up/change their email of their local accounts if their email address uses one of these domains (the part after the '@'). If left empty, then all email domains are allowed.", "examples": [ "uni-heidelberg.de", "stud.uni-heidelberg.de" ], "pattern": "^([a-zA-Z0-9\\-]+\\.)+[a-zA-Z0-9\\-]+$", "type": "string" }, "title": "Allowed Email Domains", "type": "array" }, "allow_creation_of_api_tokens": { "default": true, "description": "If set to true then users logged in with local accounts can create api tokens with infinite lifetime. They will get invalidated if the user gets deleted.", "title": "Allow Creation Of Api Tokens", "type": "boolean" }, "user_provisioning": { "additionalProperties": { "$ref": "#/$defs/ProvisionedUser" }, "default": {}, "description": "Attribute set of users that should be created beforehand. Give every provisioned user a number using the key of this attribute set. This way the users email, password and admin privileges can still be changed later on using this config file. Warning: Deleting a user from this dict will not delete it from the application or database, use the /user/delete route for this!", "examples": [ "0: {<ProvisionedUserSettings>}", "1: {<ProvisionedUserSettings>}" ], "title": "User Provisioning", "type": "object" } }, "$defs": { "EmailValidated": { "title": "EmailValidated", "type": "string" }, "LocalAccountOperationModeEnum": { "enum": [ "disabled", "no_signup_hidden", "no_signup", "enabled" ], "title": "LocalAccountOperationModeEnum", "type": "string" }, "ProvisionedUser": { "additionalProperties": false, "properties": { "email": { "$ref": "#/$defs/EmailValidated", "description": "Email address of this user. This address will be treated as a verified email address, so make sure that it is valid", "examples": [ "admin@example.org", "user@example.org" ] }, "password": { "description": "The password of this user (for login). Please make sure that this password is secure, especially when provisioning admin users!", "format": "password", "minLength": 12, "title": "Password", "type": "string", "writeOnly": true }, "is_admin": { "default": false, "description": "Whether this user should be an admin user. Be very careful with this, admin users have full access over all other users and their data! Warning: Revoking a users admin privileges over provisioning settings will currently not revoke any existing access tokens of that user, don't rely on that!", "title": "Is Admin", "type": "boolean" } }, "required": [ "email", "password" ], "title": "ProvisionedUser", "type": "object" } }, "additionalProperties": false }
- field allow_creation_of_api_tokens: bool = True
If set to true then users logged in with local accounts can create api tokens with infinite lifetime. They will get invalidated if the user gets deleted.
- field allowed_email_domains: list[Annotated[str, Field(pattern='^([a-zA-Z0-9\\-]+\\.)+[a-zA-Z0-9\\-]+$', examples=['uni-heidelberg.de', 'stud.uni-heidelberg.de'], description="Allowed domains in email addresses. Users will only be able to sign up/change their email of their local accounts if their email address uses one of these domains (the part after the '@'). If left empty, then all email domains are allowed.")]] = []
- field mode: LocalAccountOperationModeEnum = LocalAccountOperationModeEnum.ENABLED
To what extend local accounts should be enabled. - enabled: Both login and signup possible and advertised in frontend to users (default). - no_signup: Login possible and advertised to users, signup not. Thus users can only login using already existing accounts (created through provisioning or by signup before this setting was set). Use this for example if you want users to login using local accounts that you created for them through provisioning. - no_signup_hidden: Login still possible but not advertised to users in the frontend. Especially helpful if the only local accounts should be provisioned admin accounts for administration purposes while normal users should only login using oidc or ldap accounts. - disabled: no login, no signup, no provisioned accounts. Login only through ldap and oidc. Please note that in this case you need to provide admin accounts through ldap or oidc as well!
- field user_provisioning: Annotated[dict[int, ProvisionedUser], FieldInfo(annotation=NoneType, required=True, description='Attribute set of users that should be created beforehand. Give every provisioned user a number using the key of this attribute set. This way the users email, password and admin privileges can still be changed later on using this config file. Warning: Deleting a user from this dict will not delete it from the application or database, use the /user/delete route for this!', examples=['0: {<ProvisionedUserSettings>}', '1: {<ProvisionedUserSettings>}'])] = {}
Attribute set of users that should be created beforehand. Give every provisioned user a number using the key of this attribute set. This way the users email, password and admin privileges can still be changed later on using this config file. Warning: Deleting a user from this dict will not delete it from the application or database, use the /user/delete route for this!
- pydantic model project_W.models.settings.OidcProviderSettings
Show JSON schema
{ "title": "OidcProviderSettings", "type": "object", "properties": { "hidden": { "default": false, "description": "Whether this provider should not be advertised to the user on the frontend. Useful if this provider should only provide admin accounts.", "title": "Hidden", "type": "boolean" }, "icon_url": { "anyOf": [ { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to a square icon that will be shown to the user in the frontend next to the 'Login with <name>' to visually represent the account/identity provider. Should be a link to a square png with transparent background, or alternatively to a svg", "examples": [ "https://ssl.gstatic.com/images/branding/googleg/2x/googleg_standard_color_64dp.png" ], "title": "Icon Url" }, "allow_creation_of_api_tokens": { "default": true, "description": "If set to true then users logged in from this identity provider can create api tokens with infinite lifetime. These tokens will be automatically invalidated if the user gets deleted from the identity provider ones the periodic background job gets called. Run the periodic background task more often to get user access revoked quicker.", "title": "Allow Creation Of Api Tokens", "type": "boolean" }, "ca_pem_file_path": { "anyOf": [ { "format": "file-path", "type": "string" }, { "type": "null" } ], "default": null, "description": "Path to the pem certs file that includes the certificates that should be trusted for this provider (alternative certificate verification). Useful if the identity provider uses a self-signed certificate", "title": "Ca Pem File Path" }, "base_url": { "description": "Base url of the OIDC provider. If '/.well-known/openid-configuration' is appended to it it should return its metadata", "examples": [ "https://accounts.google.com", "https://appleid.apple.com" ], "format": "uri", "maxLength": 2083, "minLength": 1, "title": "Base Url", "type": "string" }, "client_id": { "description": "The client_id string as returned by the identity provider after setting up this application", "title": "Client Id", "type": "string" }, "client_secret": { "description": "The client_secret string as returned by the identity provider after setting up this application", "format": "password", "title": "Client Secret", "type": "string", "writeOnly": true }, "enable_pkce_s256_challenge": { "default": true, "description": "Whether the PKCE flow using the S256 challenge method should be enabled. The OIDC provider has to support this.", "title": "Enable Pkce S256 Challenge", "type": "boolean" }, "user_role": { "anyOf": [ { "$ref": "#/$defs/OidcRoleSettings" }, { "type": "null" } ], "default": null, "description": "Configure the role that users should have to be able to access this Project-W instance. Every user who doesn't have this role in their id token won't be able to use this service. Set to None if all users of this IdP should be able to access it" }, "admin_role": { "anyOf": [ { "$ref": "#/$defs/OidcRoleSettings" }, { "type": "null" } ], "default": null, "description": "Configure the role that users should have to be have admin permissions on Project-W. Only users with this role can do things like create new runners and see all user data. Use carefully! Set to None if no users of this IdP should be admins" } }, "$defs": { "OidcRoleSettings": { "additionalProperties": false, "properties": { "name": { "description": "Name of the required role/group", "examples": [ "project-W-users", "project-W-admins", "admins", "employees" ], "title": "Name", "type": "string" }, "field_name": { "description": "Name of the field/claim under which the role list is available in the id token", "examples": [ "roles", "groups" ], "title": "Field Name", "type": "string" } }, "required": [ "name", "field_name" ], "title": "OidcRoleSettings", "type": "object" } }, "additionalProperties": false, "required": [ "base_url", "client_id", "client_secret" ] }
- field admin_role: OidcRoleSettings | None = None
Configure the role that users should have to be have admin permissions on Project-W. Only users with this role can do things like create new runners and see all user data. Use carefully! Set to None if no users of this IdP should be admins
- field allow_creation_of_api_tokens: bool = True
If set to true then users logged in from this identity provider can create api tokens with infinite lifetime. These tokens will be automatically invalidated if the user gets deleted from the identity provider ones the periodic background job gets called. Run the periodic background task more often to get user access revoked quicker.
- field base_url: HttpUrl [Required]
Base url of the OIDC provider. If ‘/.well-known/openid-configuration’ is appended to it it should return its metadata
- field ca_pem_file_path: FilePath | None = None
Path to the pem certs file that includes the certificates that should be trusted for this provider (alternative certificate verification). Useful if the identity provider uses a self-signed certificate
- field client_id: str [Required]
The client_id string as returned by the identity provider after setting up this application
- field client_secret: SecretStr [Required]
The client_secret string as returned by the identity provider after setting up this application
- field enable_pkce_s256_challenge: bool = True
Whether the PKCE flow using the S256 challenge method should be enabled. The OIDC provider has to support this.
Whether this provider should not be advertised to the user on the frontend. Useful if this provider should only provide admin accounts.
- field icon_url: HttpUrl | None = None
URL to a square icon that will be shown to the user in the frontend next to the ‘Login with <name>’ to visually represent the account/identity provider. Should be a link to a square png with transparent background, or alternatively to a svg
- field user_role: OidcRoleSettings | None = None
Configure the role that users should have to be able to access this Project-W instance. Every user who doesn’t have this role in their id token won’t be able to use this service. Set to None if all users of this IdP should be able to access it
- pydantic model project_W.models.settings.OidcRoleSettings
Show JSON schema
{ "title": "OidcRoleSettings", "type": "object", "properties": { "name": { "description": "Name of the required role/group", "examples": [ "project-W-users", "project-W-admins", "admins", "employees" ], "title": "Name", "type": "string" }, "field_name": { "description": "Name of the field/claim under which the role list is available in the id token", "examples": [ "roles", "groups" ], "title": "Field Name", "type": "string" } }, "additionalProperties": false, "required": [ "name", "field_name" ] }
- field field_name: str [Required]
Name of the field/claim under which the role list is available in the id token
- field name: str [Required]
Name of the required role/group
- pydantic model project_W.models.settings.ProviderSettings
Show JSON schema
{ "title": "ProviderSettings", "type": "object", "properties": { "hidden": { "default": false, "description": "Whether this provider should not be advertised to the user on the frontend. Useful if this provider should only provide admin accounts.", "title": "Hidden", "type": "boolean" }, "icon_url": { "anyOf": [ { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to a square icon that will be shown to the user in the frontend next to the 'Login with <name>' to visually represent the account/identity provider. Should be a link to a square png with transparent background, or alternatively to a svg", "examples": [ "https://ssl.gstatic.com/images/branding/googleg/2x/googleg_standard_color_64dp.png" ], "title": "Icon Url" }, "allow_creation_of_api_tokens": { "default": true, "description": "If set to true then users logged in from this identity provider can create api tokens with infinite lifetime. These tokens will be automatically invalidated if the user gets deleted from the identity provider ones the periodic background job gets called. Run the periodic background task more often to get user access revoked quicker.", "title": "Allow Creation Of Api Tokens", "type": "boolean" }, "ca_pem_file_path": { "anyOf": [ { "format": "file-path", "type": "string" }, { "type": "null" } ], "default": null, "description": "Path to the pem certs file that includes the certificates that should be trusted for this provider (alternative certificate verification). Useful if the identity provider uses a self-signed certificate", "title": "Ca Pem File Path" } } }
- field allow_creation_of_api_tokens: bool = True
If set to true then users logged in from this identity provider can create api tokens with infinite lifetime. These tokens will be automatically invalidated if the user gets deleted from the identity provider ones the periodic background job gets called. Run the periodic background task more often to get user access revoked quicker.
- field ca_pem_file_path: Annotated[Path, PathType(path_type=file)] | None = None
Path to the pem certs file that includes the certificates that should be trusted for this provider (alternative certificate verification). Useful if the identity provider uses a self-signed certificate
Whether this provider should not be advertised to the user on the frontend. Useful if this provider should only provide admin accounts.
- field icon_url: HttpUrl | None = None
URL to a square icon that will be shown to the user in the frontend next to the ‘Login with <name>’ to visually represent the account/identity provider. Should be a link to a square png with transparent background, or alternatively to a svg
- pydantic model project_W.models.settings.ProvisionedUser
Show JSON schema
{ "title": "ProvisionedUser", "type": "object", "properties": { "email": { "$ref": "#/$defs/EmailValidated", "description": "Email address of this user. This address will be treated as a verified email address, so make sure that it is valid", "examples": [ "admin@example.org", "user@example.org" ] }, "password": { "description": "The password of this user (for login). Please make sure that this password is secure, especially when provisioning admin users!", "format": "password", "minLength": 12, "title": "Password", "type": "string", "writeOnly": true }, "is_admin": { "default": false, "description": "Whether this user should be an admin user. Be very careful with this, admin users have full access over all other users and their data! Warning: Revoking a users admin privileges over provisioning settings will currently not revoke any existing access tokens of that user, don't rely on that!", "title": "Is Admin", "type": "boolean" } }, "$defs": { "EmailValidated": { "title": "EmailValidated", "type": "string" } }, "additionalProperties": false, "required": [ "email", "password" ] }
- field email: EmailValidated [Required]
Email address of this user. This address will be treated as a verified email address, so make sure that it is valid
- field is_admin: bool = False
Whether this user should be an admin user. Be very careful with this, admin users have full access over all other users and their data! Warning: Revoking a users admin privileges over provisioning settings will currently not revoke any existing access tokens of that user, don’t rely on that!
- field password: SecretStr [Required]
The password of this user (for login). Please make sure that this password is secure, especially when provisioning admin users!
- Constraints:
min_length = 12
- pydantic model project_W.models.settings.RedisConnection
Show JSON schema
{ "title": "RedisConnection", "type": "object", "properties": { "connection_string": { "anyOf": [ { "format": "uri", "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "Redis connection string to connect to the caching database that should be used by Project-W.", "title": "Connection String" }, "unix_socket_path": { "anyOf": [ { "format": "path", "type": "string" }, { "type": "null" } ], "default": null, "description": "Path to a redis unix socket. Can be used instead of connection_string", "title": "Unix Socket Path" } } }
- field connection_string: RedisDsn | None = None
Redis connection string to connect to the caching database that should be used by Project-W.
- Validated by:
either_connection_string_unix_socket_path
- field unix_socket_path: Annotated[Path, PathType(path_type=socket)] | None = None
Path to a redis unix socket. Can be used instead of connection_string
- Validated by:
either_connection_string_unix_socket_path
- pydantic model project_W.models.settings.ReverseProxySettings
Show JSON schema
{ "title": "ReverseProxySettings", "type": "object", "properties": { "trusted_proxies": { "description": "List of IP addresses to trust as the proxy from which traffic originates", "items": { "type": "string" }, "title": "Trusted Proxies", "type": "array" }, "root_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Set this option to your path prefix if you want to serve Project-W from a root path prefix at your proxy", "title": "Root Path" } }, "additionalProperties": false, "required": [ "trusted_proxies" ] }
- field root_path: str | None = None
Set this option to your path prefix if you want to serve Project-W from a root path prefix at your proxy
- field trusted_proxies: list[str] [Required]
List of IP addresses to trust as the proxy from which traffic originates
- class project_W.models.settings.SMTPSecureEnum(*values)
- pydantic model project_W.models.settings.SMTPServerSettings
Show JSON schema
{ "title": "SMTPServerSettings", "type": "object", "properties": { "hostname": { "description": "FQDN of your smtp server.", "pattern": "^([a-zA-Z0-9\\-]+\\.)+[a-zA-Z0-9\\-]+|localhost$", "title": "Hostname", "type": "string" }, "port": { "default": 587, "description": "Port that should be used for the smtp connection.", "maximum": 65535, "minimum": 0, "title": "Port", "type": "integer" }, "secure": { "$ref": "#/$defs/SMTPSecureEnum", "default": "starttls", "description": "Whether to use 'ssl', 'starttls' or no encryption ('plain') with the smtp server." }, "sender_email": { "$ref": "#/$defs/EmailValidated", "description": "Email address from which emails will be sent to the users." }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Username that should be used to authenticate with the smtp server. Most of the time this is the same as 'senderEmail'.", "title": "Username" }, "password": { "anyOf": [ { "format": "password", "type": "string", "writeOnly": true }, { "type": "null" } ], "default": null, "description": "Password that should be used to authenticate with the smtp server.", "title": "Password" } }, "$defs": { "EmailValidated": { "title": "EmailValidated", "type": "string" }, "SMTPSecureEnum": { "enum": [ "ssl", "starttls", "plain" ], "title": "SMTPSecureEnum", "type": "string" } }, "additionalProperties": false, "required": [ "hostname", "sender_email" ] }
- field hostname: str [Required]
FQDN of your smtp server.
- Constraints:
pattern = ^([a-zA-Z0-9-]+.)+[a-zA-Z0-9-]+|localhost$
- field password: SecretStr | None = None
Password that should be used to authenticate with the smtp server.
- field port: int = 587
Port that should be used for the smtp connection.
- Constraints:
ge = 0
le = 65535
- field secure: SMTPSecureEnum = SMTPSecureEnum.STARTTLS
Whether to use ‘ssl’, ‘starttls’ or no encryption (‘plain’) with the smtp server.
- field sender_email: EmailValidated [Required]
Email address from which emails will be sent to the users.
- field username: str | None = None
Username that should be used to authenticate with the smtp server. Most of the time this is the same as ‘senderEmail’.
- pydantic model project_W.models.settings.SecretKeyValidated
Show JSON schema
{ "title": "SecretKeyValidated", "type": "string", "format": "password", "writeOnly": true }
- field root: SecretStr [Required]
- Validated by:
session_token_validation
- pydantic model project_W.models.settings.SecuritySettings
Show JSON schema
{ "title": "SecuritySettings", "type": "object", "properties": { "secret_key": { "$ref": "#/$defs/SecretKeyValidated", "description": "The secret key used to sign payloads in emails. 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(32))'`." }, "local_account": { "$ref": "#/$defs/LocalAccountSettings", "default": { "mode": "enabled", "allowed_email_domains": [], "allow_creation_of_api_tokens": true, "user_provisioning": {} } }, "tokens": { "$ref": "#/$defs/TokenSettings", "default": { "session_expiration_time_minutes": 60, "rolling_session_before_expiration_minutes": 10 } }, "oidc_providers": { "additionalProperties": { "$ref": "#/$defs/OidcProviderSettings" }, "default": {}, "description": "Attribute set of identity providers. The name of the set will be shown to users in a form like this: 'Login with <provider name>'.", "examples": [ "Google: {<ProviderSettings>}", "Apple: {<ProviderSettings>}" ], "title": "Oidc Providers", "type": "object" }, "ldap_providers": { "additionalProperties": { "$ref": "#/$defs/LdapProviderSettings" }, "default": {}, "description": "Attribute set of identity providers. The name of the set will be shown to users in a form like this: 'Login with <provider name>'.", "examples": [ "Google: {<ProviderSettings>}", "Apple: {<ProviderSettings>}" ], "title": "Ldap Providers", "type": "object" } }, "$defs": { "EmailValidated": { "title": "EmailValidated", "type": "string" }, "LdapAuthMechanismEnum": { "enum": [ "SIMPLE", "DIGEST-MD5", "NTLM" ], "title": "LdapAuthMechanismEnum", "type": "string" }, "LdapAuthSettings": { "additionalProperties": false, "properties": { "mechanism": { "$ref": "#/$defs/LdapAuthMechanismEnum", "default": "SIMPLE", "description": "Authentication mechanism that should be used. Can be one of 'SIMPLE', 'DIGEST-MD5' or 'NTLM'" }, "user": { "description": "Identification of binding user.", "title": "User", "type": "string" }, "password": { "description": "Password of binding user.", "format": "password", "title": "Password", "type": "string", "writeOnly": true } }, "required": [ "user", "password" ], "title": "LdapAuthSettings", "type": "object" }, "LdapProviderSettings": { "additionalProperties": false, "properties": { "hidden": { "default": false, "description": "Whether this provider should not be advertised to the user on the frontend. Useful if this provider should only provide admin accounts.", "title": "Hidden", "type": "boolean" }, "icon_url": { "anyOf": [ { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to a square icon that will be shown to the user in the frontend next to the 'Login with <name>' to visually represent the account/identity provider. Should be a link to a square png with transparent background, or alternatively to a svg", "examples": [ "https://ssl.gstatic.com/images/branding/googleg/2x/googleg_standard_color_64dp.png" ], "title": "Icon Url" }, "allow_creation_of_api_tokens": { "default": true, "description": "If set to true then users logged in from this identity provider can create api tokens with infinite lifetime. These tokens will be automatically invalidated if the user gets deleted from the identity provider ones the periodic background job gets called. Run the periodic background task more often to get user access revoked quicker.", "title": "Allow Creation Of Api Tokens", "type": "boolean" }, "ca_pem_file_path": { "anyOf": [ { "format": "file-path", "type": "string" }, { "type": "null" } ], "default": null, "description": "Path to the pem certs file that includes the certificates that should be trusted for this provider (alternative certificate verification). Useful if the identity provider uses a self-signed certificate", "title": "Ca Pem File Path" }, "server_address": { "description": "Address of the ldap server. Should start with either ldap://, ldaps:// or ldapi:// depending on whether the connection should be unencrypted, ssl/tls encrypted or if it's an URL-encoded filesocket connection", "examples": [ "ldap://example.org", "ldaps://example.org", "ldapi://%2Frun%2Fslapd%2Fldapi" ], "format": "uri", "minLength": 1, "title": "Server Address", "type": "string" }, "username_attributes": { "description": "A list of attribute/field names which contain strings that can be used by the user as a username during login. Project-W will use them to generate an LDAP filter expression and merge it with your provided filter expression like this: (&(<your filter expression>)(|(<username_attribute1>=<username>)(<username_attribute2>=<username>)...))", "examples": [ [ "name" ], [ "name", "mail" ], [ "displayname", "email" ] ], "items": { "type": "string" }, "title": "Username Attributes", "type": "array" }, "uid_attribute": { "description": "The attribute/field name that contains a unique user identifier. Doesn't have to be the same as one of the username_attributes, but can be. Make sure that this identifier is unique to a user across the LDAP directory and will never change/be reassigned to a different user! Every LDAP user that the filter expression can return should have this attribute exactly ones. This attribute in combination with the filter expression will be used to query users outside of the regular login flow.", "examples": [ "uid", "uuid" ], "title": "Uid Attribute", "type": "string" }, "mail_attribute": { "description": "The attribute/field name that contains the email address of a user. Every LDAP user that the filter expression can return should have this attribute exactly ones.", "examples": [ "mail", "email", "mail1" ], "title": "Mail Attribute", "type": "string" }, "user_query": { "anyOf": [ { "$ref": "#/$defs/LdapQuerySettings" }, { "type": "null" } ], "default": null, "description": "Settings that define how normal users should be queried from the ldap server. If left to None then no normal user will be able to sign in using this provider" }, "admin_query": { "anyOf": [ { "$ref": "#/$defs/LdapQuerySettings" }, { "type": "null" } ], "default": null, "description": "Settings that define how admin users should be queried from the ldap server. If left to None then no admin user will be able to sign in (with admin privileges) using this provider" }, "service_account_auth": { "$ref": "#/$defs/LdapAuthSettings", "description": " This user should be a service account with read permissions on all other users and their mail (and any other attributes used in the query, e.g. memberof)." } }, "required": [ "server_address", "username_attributes", "uid_attribute", "mail_attribute", "service_account_auth" ], "title": "LdapProviderSettings", "type": "object" }, "LdapQuerySettings": { "additionalProperties": false, "properties": { "base_dn": { "description": "The base DN under which should be searched", "examples": [ "dc=example,dc=org" ], "title": "Base Dn", "type": "string" }, "filter": { "description": "Ldap filter expression that that will be merged with the user attribute filters.", "examples": [ "(class=person)(&(class=person)(memberof=spn=project-W-users@localhost)(&(class=account)(memberof=spn=project-W-admins@localhost))" ], "title": "Filter", "type": "string" } }, "required": [ "base_dn", "filter" ], "title": "LdapQuerySettings", "type": "object" }, "LocalAccountOperationModeEnum": { "enum": [ "disabled", "no_signup_hidden", "no_signup", "enabled" ], "title": "LocalAccountOperationModeEnum", "type": "string" }, "LocalAccountSettings": { "additionalProperties": false, "properties": { "mode": { "$ref": "#/$defs/LocalAccountOperationModeEnum", "default": "enabled", "description": "\n To what extend local accounts should be enabled.\n - enabled: Both login and signup possible and advertised in frontend to users (default).\n - no_signup: Login possible and advertised to users, signup not. Thus users can only login using already existing accounts (created through provisioning or by signup before this setting was set). Use this for example if you want users to login using local accounts that you created for them through provisioning.\n - no_signup_hidden: Login still possible but not advertised to users in the frontend. Especially helpful if the only local accounts should be provisioned admin accounts for administration purposes while normal users should only login using oidc or ldap accounts.\n - disabled: no login, no signup, no provisioned accounts. Login only through ldap and oidc. Please note that in this case you need to provide admin accounts through ldap or oidc as well!\n " }, "allowed_email_domains": { "default": [], "items": { "description": "Allowed domains in email addresses. Users will only be able to sign up/change their email of their local accounts if their email address uses one of these domains (the part after the '@'). If left empty, then all email domains are allowed.", "examples": [ "uni-heidelberg.de", "stud.uni-heidelberg.de" ], "pattern": "^([a-zA-Z0-9\\-]+\\.)+[a-zA-Z0-9\\-]+$", "type": "string" }, "title": "Allowed Email Domains", "type": "array" }, "allow_creation_of_api_tokens": { "default": true, "description": "If set to true then users logged in with local accounts can create api tokens with infinite lifetime. They will get invalidated if the user gets deleted.", "title": "Allow Creation Of Api Tokens", "type": "boolean" }, "user_provisioning": { "additionalProperties": { "$ref": "#/$defs/ProvisionedUser" }, "default": {}, "description": "Attribute set of users that should be created beforehand. Give every provisioned user a number using the key of this attribute set. This way the users email, password and admin privileges can still be changed later on using this config file. Warning: Deleting a user from this dict will not delete it from the application or database, use the /user/delete route for this!", "examples": [ "0: {<ProvisionedUserSettings>}", "1: {<ProvisionedUserSettings>}" ], "title": "User Provisioning", "type": "object" } }, "title": "LocalAccountSettings", "type": "object" }, "OidcProviderSettings": { "additionalProperties": false, "properties": { "hidden": { "default": false, "description": "Whether this provider should not be advertised to the user on the frontend. Useful if this provider should only provide admin accounts.", "title": "Hidden", "type": "boolean" }, "icon_url": { "anyOf": [ { "format": "uri", "maxLength": 2083, "minLength": 1, "type": "string" }, { "type": "null" } ], "default": null, "description": "URL to a square icon that will be shown to the user in the frontend next to the 'Login with <name>' to visually represent the account/identity provider. Should be a link to a square png with transparent background, or alternatively to a svg", "examples": [ "https://ssl.gstatic.com/images/branding/googleg/2x/googleg_standard_color_64dp.png" ], "title": "Icon Url" }, "allow_creation_of_api_tokens": { "default": true, "description": "If set to true then users logged in from this identity provider can create api tokens with infinite lifetime. These tokens will be automatically invalidated if the user gets deleted from the identity provider ones the periodic background job gets called. Run the periodic background task more often to get user access revoked quicker.", "title": "Allow Creation Of Api Tokens", "type": "boolean" }, "ca_pem_file_path": { "anyOf": [ { "format": "file-path", "type": "string" }, { "type": "null" } ], "default": null, "description": "Path to the pem certs file that includes the certificates that should be trusted for this provider (alternative certificate verification). Useful if the identity provider uses a self-signed certificate", "title": "Ca Pem File Path" }, "base_url": { "description": "Base url of the OIDC provider. If '/.well-known/openid-configuration' is appended to it it should return its metadata", "examples": [ "https://accounts.google.com", "https://appleid.apple.com" ], "format": "uri", "maxLength": 2083, "minLength": 1, "title": "Base Url", "type": "string" }, "client_id": { "description": "The client_id string as returned by the identity provider after setting up this application", "title": "Client Id", "type": "string" }, "client_secret": { "description": "The client_secret string as returned by the identity provider after setting up this application", "format": "password", "title": "Client Secret", "type": "string", "writeOnly": true }, "enable_pkce_s256_challenge": { "default": true, "description": "Whether the PKCE flow using the S256 challenge method should be enabled. The OIDC provider has to support this.", "title": "Enable Pkce S256 Challenge", "type": "boolean" }, "user_role": { "anyOf": [ { "$ref": "#/$defs/OidcRoleSettings" }, { "type": "null" } ], "default": null, "description": "Configure the role that users should have to be able to access this Project-W instance. Every user who doesn't have this role in their id token won't be able to use this service. Set to None if all users of this IdP should be able to access it" }, "admin_role": { "anyOf": [ { "$ref": "#/$defs/OidcRoleSettings" }, { "type": "null" } ], "default": null, "description": "Configure the role that users should have to be have admin permissions on Project-W. Only users with this role can do things like create new runners and see all user data. Use carefully! Set to None if no users of this IdP should be admins" } }, "required": [ "base_url", "client_id", "client_secret" ], "title": "OidcProviderSettings", "type": "object" }, "OidcRoleSettings": { "additionalProperties": false, "properties": { "name": { "description": "Name of the required role/group", "examples": [ "project-W-users", "project-W-admins", "admins", "employees" ], "title": "Name", "type": "string" }, "field_name": { "description": "Name of the field/claim under which the role list is available in the id token", "examples": [ "roles", "groups" ], "title": "Field Name", "type": "string" } }, "required": [ "name", "field_name" ], "title": "OidcRoleSettings", "type": "object" }, "ProvisionedUser": { "additionalProperties": false, "properties": { "email": { "$ref": "#/$defs/EmailValidated", "description": "Email address of this user. This address will be treated as a verified email address, so make sure that it is valid", "examples": [ "admin@example.org", "user@example.org" ] }, "password": { "description": "The password of this user (for login). Please make sure that this password is secure, especially when provisioning admin users!", "format": "password", "minLength": 12, "title": "Password", "type": "string", "writeOnly": true }, "is_admin": { "default": false, "description": "Whether this user should be an admin user. Be very careful with this, admin users have full access over all other users and their data! Warning: Revoking a users admin privileges over provisioning settings will currently not revoke any existing access tokens of that user, don't rely on that!", "title": "Is Admin", "type": "boolean" } }, "required": [ "email", "password" ], "title": "ProvisionedUser", "type": "object" }, "SecretKeyValidated": { "format": "password", "title": "SecretKeyValidated", "type": "string", "writeOnly": true }, "TokenSettings": { "additionalProperties": false, "properties": { "session_expiration_time_minutes": { "default": 60, "description": "Time for which auth tokens stay valid (not API tokens, they stay valid indefinitely). Project-W uses rolling tokens, so beginning from 10 minutes before expiration the auth token will be rotated automatically to prevent active users from being logged out. Inactive users however will be logged out after this period. Increase if you want to keep inactive users logged in for longer (on the prize of a higher risk of the auth token being stolen)", "minimum": 15, "title": "Session Expiration Time Minutes", "type": "integer" }, "rolling_session_before_expiration_minutes": { "default": 10, "description": "The amount of minutes before a token expires when a user should get a new auth token if the user is still active", "minimum": 5, "title": "Rolling Session Before Expiration Minutes", "type": "integer" } }, "title": "TokenSettings", "type": "object" } }, "additionalProperties": false, "required": [ "secret_key" ] }
- field ldap_providers: Annotated[dict[str, LdapProviderSettings], FieldInfo(annotation=NoneType, required=True, description="Attribute set of identity providers. The name of the set will be shown to users in a form like this: 'Login with <provider name>'.", examples=['Google: {<ProviderSettings>}', 'Apple: {<ProviderSettings>}'])] = {}
Attribute set of identity providers. The name of the set will be shown to users in a form like this: ‘Login with <provider name>’.
- field local_account: LocalAccountSettings = LocalAccountSettings(mode=<LocalAccountOperationModeEnum.ENABLED: 'enabled'>, allowed_email_domains=[], allow_creation_of_api_tokens=True, user_provisioning={})
- field oidc_providers: Annotated[dict[str, OidcProviderSettings], FieldInfo(annotation=NoneType, required=True, description="Attribute set of identity providers. The name of the set will be shown to users in a form like this: 'Login with <provider name>'.", examples=['Google: {<ProviderSettings>}', 'Apple: {<ProviderSettings>}'])] = {}
Attribute set of identity providers. The name of the set will be shown to users in a form like this: ‘Login with <provider name>’.
- field secret_key: SecretKeyValidated [Required]
The secret key used to sign payloads in emails. 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(32))’.
- field tokens: TokenSettings = TokenSettings(session_expiration_time_minutes=60, rolling_session_before_expiration_minutes=10)
- pydantic model project_W.models.settings.SslSettings
Show JSON schema
{ "title": "SslSettings", "type": "object", "properties": { "cert_file": { "description": "Path to the SSL certificate file", "format": "file-path", "title": "Cert File", "type": "string" }, "key_file": { "description": "Path to the SSL key file", "format": "file-path", "title": "Key File", "type": "string" }, "key_file_password": { "anyOf": [ { "format": "password", "type": "string", "writeOnly": true }, { "type": "null" } ], "default": null, "description": "Password of the SSL key file", "title": "Key File Password" } }, "additionalProperties": false, "required": [ "cert_file", "key_file" ] }
- field cert_file: Annotated[Path, PathType(path_type=file)] [Required]
Path to the SSL certificate file
- Constraints:
path_type = file
- field key_file: Annotated[Path, PathType(path_type=file)] [Required]
Path to the SSL key file
- Constraints:
path_type = file
- field key_file_password: SecretStr | None = None
Password of the SSL key file
- pydantic model project_W.models.settings.TokenSettings
Show JSON schema
{ "title": "TokenSettings", "type": "object", "properties": { "session_expiration_time_minutes": { "default": 60, "description": "Time for which auth tokens stay valid (not API tokens, they stay valid indefinitely). Project-W uses rolling tokens, so beginning from 10 minutes before expiration the auth token will be rotated automatically to prevent active users from being logged out. Inactive users however will be logged out after this period. Increase if you want to keep inactive users logged in for longer (on the prize of a higher risk of the auth token being stolen)", "minimum": 15, "title": "Session Expiration Time Minutes", "type": "integer" }, "rolling_session_before_expiration_minutes": { "default": 10, "description": "The amount of minutes before a token expires when a user should get a new auth token if the user is still active", "minimum": 5, "title": "Rolling Session Before Expiration Minutes", "type": "integer" } }, "additionalProperties": false }
- field rolling_session_before_expiration_minutes: int = 10
The amount of minutes before a token expires when a user should get a new auth token if the user is still active
- Constraints:
ge = 5
- Validated by:
rlling_session_before_session_significantly_smaller_than_session_exp
- field session_expiration_time_minutes: int = 60
Time for which auth tokens stay valid (not API tokens, they stay valid indefinitely). Project-W uses rolling tokens, so beginning from 10 minutes before expiration the auth token will be rotated automatically to prevent active users from being logged out. Inactive users however will be logged out after this period. Increase if you want to keep inactive users logged in for longer (on the prize of a higher risk of the auth token being stolen)
- Constraints:
ge = 15
- Validated by:
rlling_session_before_session_significantly_smaller_than_session_exp
- pydantic model project_W.models.settings.TosSettings
Show JSON schema
{ "title": "TosSettings", "type": "object", "properties": { "name": { "description": "The name of this term of service. This will be shown as a title above the tos_html content in the frontend", "title": "Name", "type": "string" }, "version": { "description": "The version of this term of service. Start by putting this to 1. When incremented then users will have to re-accept these terms.", "minimum": 1, "title": "Version", "type": "integer" }, "tos_html": { "description": "The terms of services in html format. You may include links to external websites if you want.", "title": "Tos Html", "type": "string" } }, "additionalProperties": false, "required": [ "name", "version", "tos_html" ] }
- field name: str [Required]
The name of this term of service. This will be shown as a title above the tos_html content in the frontend
- field tos_html: str [Required]
The terms of services in html format. You may include links to external websites if you want.
- field version: int [Required]
The version of this term of service. Start by putting this to 1. When incremented then users will have to re-accept these terms.
- Constraints:
ge = 1
- pydantic model project_W.models.settings.WebServerSettings
Show JSON schema
{ "title": "WebServerSettings", "type": "object", "properties": { "allowed_hosts": { "default": [ "*" ], "description": "List of domains that are allowed as hostnames. Wildcard domains supported", "items": { "type": "string" }, "title": "Allowed Hosts", "type": "array" }, "reverse_proxy": { "anyOf": [ { "$ref": "#/$defs/ReverseProxySettings" }, { "type": "null" } ], "default": null, "description": "Settings for when running Project-W behind a Reverse Proxy" }, "ssl": { "anyOf": [ { "$ref": "#/$defs/SslSettings" }, { "type": "null" } ], "default": null, "description": "SSL settings to enable https encrypted traffic" }, "no_https": { "default": false, "description": "Disable https encryption. This will lead to passwords, sensitive data and more to be transmitted unencrypted! Only set this for development or testing purposes!", "title": "No Https", "type": "boolean" }, "worker_count": { "default": 1, "description": "Amount of workers that should serve the web server simultaneously. Increasing this will allow for more concurrent users as long as it is lower or equal than the amount of CPU cores on your system.", "title": "Worker Count", "type": "integer" }, "address": { "default": "0.0.0.0/32", "description": "The address of the interface under which the web server should be served.", "format": "ipvanyinterface", "title": "Address", "type": "string" }, "port": { "default": 5000, "description": "The port under which the web server should be served. The default port is 5000 regardless of whether https is enabled or not. This shouldn't be changed in a docker deployment because that would break the docker container's health check. Use docker's port mapping feature instead.", "maximum": 65535, "minimum": 0, "title": "Port", "type": "integer" } }, "$defs": { "ReverseProxySettings": { "additionalProperties": false, "properties": { "trusted_proxies": { "description": "List of IP addresses to trust as the proxy from which traffic originates", "items": { "type": "string" }, "title": "Trusted Proxies", "type": "array" }, "root_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Set this option to your path prefix if you want to serve Project-W from a root path prefix at your proxy", "title": "Root Path" } }, "required": [ "trusted_proxies" ], "title": "ReverseProxySettings", "type": "object" }, "SslSettings": { "additionalProperties": false, "properties": { "cert_file": { "description": "Path to the SSL certificate file", "format": "file-path", "title": "Cert File", "type": "string" }, "key_file": { "description": "Path to the SSL key file", "format": "file-path", "title": "Key File", "type": "string" }, "key_file_password": { "anyOf": [ { "format": "password", "type": "string", "writeOnly": true }, { "type": "null" } ], "default": null, "description": "Password of the SSL key file", "title": "Key File Password" } }, "required": [ "cert_file", "key_file" ], "title": "SslSettings", "type": "object" } }, "additionalProperties": false }
- field address: IPvAnyInterface = IPv4Interface('0.0.0.0/32')
The address of the interface under which the web server should be served.
- field allowed_hosts: list[str] = ['*']
List of domains that are allowed as hostnames. Wildcard domains supported
- field no_https: bool = False
Disable https encryption. This will lead to passwords, sensitive data and more to be transmitted unencrypted! Only set this for development or testing purposes!
- field port: int = 5000
The port under which the web server should be served. The default port is 5000 regardless of whether https is enabled or not. This shouldn’t be changed in a docker deployment because that would break the docker container’s health check. Use docker’s port mapping feature instead.
- Constraints:
ge = 0
le = 65535
- field reverse_proxy: ReverseProxySettings | None = None
Settings for when running Project-W behind a Reverse Proxy
- field ssl: SslSettings | None = None
SSL settings to enable https encrypted traffic
- field worker_count: int = 1
Amount of workers that should serve the web server simultaneously. Increasing this will allow for more concurrent users as long as it is lower or equal than the amount of CPU cores on your system.
Description of runner config options
The following gives an overview over all config options available to you on the runner:
- pydantic model runner_settings.Settings
Show JSON schema
{ "title": "Settings", "type": "object", "properties": { "runner_attributes": { "$ref": "#/$defs/RunnerAttributes", "description": "General attributes of this runner" }, "backend_settings": { "$ref": "#/$defs/BackendSettings", "description": "How to connect to the Project-W Backend" }, "whisper_settings": { "$ref": "#/$defs/WhisperSettings", "description": "Settings related to performing the actual transcription and running the whisper and other ML models" } }, "$defs": { "BackendSettings": { "additionalProperties": false, "properties": { "url": { "description": "The Url used to connect to the backend", "format": "uri", "maxLength": 2083, "minLength": 1, "title": "Url", "type": "string" }, "ca_pem_file_path": { "anyOf": [ { "format": "file-path", "type": "string" }, { "type": "null" } ], "default": null, "description": "Path to the pem certs file that includes the certificates that should be trusted for the backend (alternative certificate verification). Useful if the backend uses a self-signed certificate", "title": "Ca Pem File Path" }, "auth_token": { "description": "The token of this runner that is used to authenticate to the backend. The backend also uses this token to identify the runner which means that each runner needs to have their own unique token", "format": "password", "title": "Auth Token", "type": "string", "writeOnly": true } }, "required": [ "url", "auth_token" ], "title": "BackendSettings", "type": "object" }, "ComputeTypeEnum": { "enum": [ "float16", "float32", "int8" ], "title": "ComputeTypeEnum", "type": "string" }, "ModelPrefetchingEnum": { "enum": [ "none", "without_alignment_and_diarization", "without_alignment", "all" ], "title": "ModelPrefetchingEnum", "type": "string" }, "RunnerAttributes": { "additionalProperties": false, "properties": { "name": { "description": "A unique string identifier. This name is displayed to users for transparency reasons so that they have some idea where their data is going and so that it is easier to identify runners. Ideally the name should contain the location/organization where the runner is hosted", "examples": [ "university runner 1", "working group runner 3", "cloud cluster runner 12" ], "maxLength": 40, "title": "Name", "type": "string" }, "priority": { "default": 100, "description": "The priority in the job assignment process. If both runner A and B are free and runner A has a higher priority than runner B it means that any given job will always be assigned to runner A first. Furthermore the runner priority should be a relative measure for the runners hardware capability, e.g. if runner A has double the priority as runner B it should be roughly twice as powerful", "exclusiveMinimum": 0, "title": "Priority", "type": "integer" } }, "required": [ "name" ], "title": "RunnerAttributes", "type": "object" }, "WhisperSettings": { "additionalProperties": false, "properties": { "model_cache_dir": { "default": "/home/docs/.cache/project-W-runner", "description": "The directory in which whisperx should download/read models from", "format": "directory-path", "title": "Model Cache Dir", "type": "string" }, "model_prefetching": { "$ref": "#/$defs/ModelPrefetchingEnum", "default": "all", "description": "Which models to prefetch before connecting to the backend. It is recommended to leave this to 'all' in production since otherwise users might have to wait for the runner to fetch models first (which could very well fail, especially for the diarization model)" }, "hf_token": { "description": "Hugging Face token required to download pyannote models for diarization. To get a token please create a Hugging Face account, accept the conditions for the pyannote/segmentation-3.0 and pyannote/speaker-diarization-3.1 models and create a token with the permissions to access content of public gated repos", "format": "password", "title": "Hf Token", "type": "string", "writeOnly": true }, "torch_device": { "default": "cuda", "description": "On which torch device whisperx should run", "title": "Torch Device", "type": "string" }, "compute_type": { "$ref": "#/$defs/ComputeTypeEnum", "default": "float16", "description": "The compute type used by the whisper model. One of 'float16', 'float32', 'int8'. Set this to int8 if you want to run whisper on CPU" }, "batch_size": { "default": 16, "description": "Batch size for inference with Whisper model. Set this to a smaller value (e.g. to 4) if you want to run whisper on CPU", "minimum": 2, "title": "Batch Size", "type": "integer" } }, "required": [ "hf_token" ], "title": "WhisperSettings", "type": "object" } }, "additionalProperties": false, "required": [ "runner_attributes", "backend_settings", "whisper_settings" ] }
- field backend_settings: BackendSettings [Required]
How to connect to the Project-W Backend
- field runner_attributes: RunnerAttributes [Required]
General attributes of this runner
- field whisper_settings: WhisperSettings [Required]
Settings related to performing the actual transcription and running the whisper and other ML models
Refer below to each of the fields and their subfields and subsubfields and so on:
- pydantic model runner_settings.BackendSettings
Show JSON schema
{ "title": "BackendSettings", "type": "object", "properties": { "url": { "description": "The Url used to connect to the backend", "format": "uri", "maxLength": 2083, "minLength": 1, "title": "Url", "type": "string" }, "ca_pem_file_path": { "anyOf": [ { "format": "file-path", "type": "string" }, { "type": "null" } ], "default": null, "description": "Path to the pem certs file that includes the certificates that should be trusted for the backend (alternative certificate verification). Useful if the backend uses a self-signed certificate", "title": "Ca Pem File Path" }, "auth_token": { "description": "The token of this runner that is used to authenticate to the backend. The backend also uses this token to identify the runner which means that each runner needs to have their own unique token", "format": "password", "title": "Auth Token", "type": "string", "writeOnly": true } }, "additionalProperties": false, "required": [ "url", "auth_token" ] }
- field auth_token: SecretStr [Required]
The token of this runner that is used to authenticate to the backend. The backend also uses this token to identify the runner which means that each runner needs to have their own unique token
- field ca_pem_file_path: Annotated[Path, PathType(path_type=file)] | None = None
Path to the pem certs file that includes the certificates that should be trusted for the backend (alternative certificate verification). Useful if the backend uses a self-signed certificate
- field url: HttpUrl [Required]
The Url used to connect to the backend
- class runner_settings.ComputeTypeEnum(*values)
- class runner_settings.ModelPrefetchingEnum(*values)
- pydantic model runner_settings.RunnerAttributes
Show JSON schema
{ "title": "RunnerAttributes", "type": "object", "properties": { "name": { "description": "A unique string identifier. This name is displayed to users for transparency reasons so that they have some idea where their data is going and so that it is easier to identify runners. Ideally the name should contain the location/organization where the runner is hosted", "examples": [ "university runner 1", "working group runner 3", "cloud cluster runner 12" ], "maxLength": 40, "title": "Name", "type": "string" }, "priority": { "default": 100, "description": "The priority in the job assignment process. If both runner A and B are free and runner A has a higher priority than runner B it means that any given job will always be assigned to runner A first. Furthermore the runner priority should be a relative measure for the runners hardware capability, e.g. if runner A has double the priority as runner B it should be roughly twice as powerful", "exclusiveMinimum": 0, "title": "Priority", "type": "integer" } }, "additionalProperties": false, "required": [ "name" ] }
- field name: str [Required]
A unique string identifier. This name is displayed to users for transparency reasons so that they have some idea where their data is going and so that it is easier to identify runners. Ideally the name should contain the location/organization where the runner is hosted
- Constraints:
max_length = 40
- field priority: int = 100
The priority in the job assignment process. If both runner A and B are free and runner A has a higher priority than runner B it means that any given job will always be assigned to runner A first. Furthermore the runner priority should be a relative measure for the runners hardware capability, e.g. if runner A has double the priority as runner B it should be roughly twice as powerful
- Constraints:
gt = 0
- pydantic model runner_settings.WhisperSettings
Show JSON schema
{ "title": "WhisperSettings", "type": "object", "properties": { "model_cache_dir": { "default": "/home/docs/.cache/project-W-runner", "description": "The directory in which whisperx should download/read models from", "format": "directory-path", "title": "Model Cache Dir", "type": "string" }, "model_prefetching": { "$ref": "#/$defs/ModelPrefetchingEnum", "default": "all", "description": "Which models to prefetch before connecting to the backend. It is recommended to leave this to 'all' in production since otherwise users might have to wait for the runner to fetch models first (which could very well fail, especially for the diarization model)" }, "hf_token": { "description": "Hugging Face token required to download pyannote models for diarization. To get a token please create a Hugging Face account, accept the conditions for the pyannote/segmentation-3.0 and pyannote/speaker-diarization-3.1 models and create a token with the permissions to access content of public gated repos", "format": "password", "title": "Hf Token", "type": "string", "writeOnly": true }, "torch_device": { "default": "cuda", "description": "On which torch device whisperx should run", "title": "Torch Device", "type": "string" }, "compute_type": { "$ref": "#/$defs/ComputeTypeEnum", "default": "float16", "description": "The compute type used by the whisper model. One of 'float16', 'float32', 'int8'. Set this to int8 if you want to run whisper on CPU" }, "batch_size": { "default": 16, "description": "Batch size for inference with Whisper model. Set this to a smaller value (e.g. to 4) if you want to run whisper on CPU", "minimum": 2, "title": "Batch Size", "type": "integer" } }, "$defs": { "ComputeTypeEnum": { "enum": [ "float16", "float32", "int8" ], "title": "ComputeTypeEnum", "type": "string" }, "ModelPrefetchingEnum": { "enum": [ "none", "without_alignment_and_diarization", "without_alignment", "all" ], "title": "ModelPrefetchingEnum", "type": "string" } }, "additionalProperties": false, "required": [ "hf_token" ] }
- field batch_size: int = 16
Batch size for inference with Whisper model. Set this to a smaller value (e.g. to 4) if you want to run whisper on CPU
- Constraints:
ge = 2
- field compute_type: ComputeTypeEnum = ComputeTypeEnum.FLOAT16
The compute type used by the whisper model. One of ‘float16’, ‘float32’, ‘int8’. Set this to int8 if you want to run whisper on CPU
- field hf_token: SecretStr [Required]
Hugging Face token required to download pyannote models for diarization. To get a token please create a Hugging Face account, accept the conditions for the pyannote/segmentation-3.0 and pyannote/speaker-diarization-3.1 models and create a token with the permissions to access content of public gated repos
- field model_cache_dir: Annotated[Path, PathType(path_type=dir)] = PosixPath('/home/docs/.cache/project-W-runner')
The directory in which whisperx should download/read models from
- Constraints:
path_type = dir
- field model_prefetching: ModelPrefetchingEnum = ModelPrefetchingEnum.ALL
Which models to prefetch before connecting to the backend. It is recommended to leave this to ‘all’ in production since otherwise users might have to wait for the runner to fetch models first (which could very well fail, especially for the diarization model)
- field torch_device: str = 'cuda'
On which torch device whisperx should run