Skip to main content

Configurations

Overview​

AVTotpy can read configurations from either a .env file in the project root or from environment variables.

Using environment variables is the recommended approach for production environments.

Each config and its default value is listed below. When no value is present, it means a default is not set and a startup error may ensue when the field is not nullable.

General​

General application settings.

LOG_LEVEL​

Sets the application log level.

Allowed values are:

  • DEBUG
  • INFO
  • WARNING
  • ERROR
  • CRITICAL
LOG_LEVEL=INFO

CORS_ALLOWED_ORIGINS​

A JSON list of origins allowed for Cross-Origin Resource Sharing (CORS).

CORS_ALLOWED_ORIGINS=["*"]

CORS_ALLOWED_METHODS​

A JSON list of HTTP methods allowed for CORS requests.

CORS_ALLOWED_METHODS=["*"]

CORS_ALLOWED_HEADERS​

A JSON list of HTTP headers allowed for CORS requests.

CORS_ALLOWED_HEADERS=["*"]

PostgreSQL​

Configurations for the PostgreSQL database connection driver (psycopg).

POSTGRES_PSYCOPG_LOG_LEVEL​

Changes the log level for the psycopg library.

Allowed values are:

  • DEBUG
  • INFO
  • WARNING
  • ERROR
  • CRITICAL
POSTGRES_PSYCOPG_LOG_LEVEL=WARNING

POSTGRES_PSYCOPG_POOL_LOG_LEVEL​

Changes the log level for the psycopg library's connection pooler.

Allowed values are:

  • DEBUG
  • INFO
  • WARNING
  • ERROR
  • CRITICAL
POSTGRES_PSYCOPG_POOL_LOG_LEVEL=WARNING

POSTGRES_CONNECTION_STR​

Set the connection string for the database.

This config is to be treated a secret since it must contain username and password for the database.

The username and password should be those set in the configs POSTGRES_MIGRATOR_UNPRIVILEGED_USER and POSTGRES_MIGRATOR_UNPRIVILEGED_USER_PASSWORD.

Any other user with correct credentials and access permissions will do. It's best to use a user with as restricted permissions as possible (like the one created at migration time).

The format is the following: postgresql://<username>:<password>@<host>:<port>/<database>

POSTGRES_CONNECTION_STR=

POSTGRES_DISABLE_CONNECTION_POOLING​

Disable the PostgreSQL library's connection pooling.

Useful when external connection poolers like pgbouncer are used.

caution

When enabled, POSTGRES_POOL_MIN_SIZE MUST be set to 0.

POSTGRES_DISABLE_CONNECTION_POOLING=False

POSTGRES_POOL_MIN_SIZE​

The minimum number of connections the pool will hold. The pool will actively try to create new connections if some are lost (closed, broken) and will try to never go below the set value.

info

Does nothing when POSTGRES_DISABLE_CONNECTION_POOLING is set to True.

caution

MUST be set to 0 when POSTGRES_DISABLE_CONNECTION_POOLING is set to True.

POSTGRES_POOL_MIN_SIZE=2

POSTGRES_POOL_MAX_SIZE​

The maximum number of connections the pool will hold.

If unset, or equal to POSTGRES_POOL_MIN_SIZE, the pool will not grow or shrink. If larger than POSTGRES_POOL_MIN_SIZE, the pool can grow if more than POSTGRES_POOL_MIN_SIZE connections are requested at the same time and will shrink back after the extra connections have been unused for more than POSTGRES_POOL_MAX_IDLE seconds.

info

Does nothing when POSTGRES_DISABLE_CONNECTION_POOLING is set to True.

POSTGRES_POOL_MAX_SIZE=8

POSTGRES_POOL_MAX_IDLE​

Maximum time, in seconds, that a connection can stay unused in the pool before being closed, and the pool shrunk.

This only happens to connections more than POSTGRES_POOL_MIN_SIZE, if POSTGRES_POOL_MAX_SIZE allowed the pool to grow.

info

Does nothing when POSTGRES_DISABLE_CONNECTION_POOLING is set to True.

POSTGRES_POOL_MAX_IDLE=600.0

POSTGRES_POOL_TIMEOUT​

The maximum time in seconds that a client can wait to receive a connection from the database.

info

Does nothing when POSTGRES_DISABLE_CONNECTION_POOLING is set to True.

POSTGRES_POOL_TIMEOUT=30.0

PostgreSQL Schema Migrator​

Configurations for the PostgreSQL schema migrator on startup.

POSTGRES_MIGRATOR_MODE​

Determines how AVTotpy should handle database schema upgrades.

By default, when AVTotpy starts, it will try to create the schema if it doesn't exist or upgrade it to the latest version. This config makes this behavior configurable; this is especially useful when running multiple AVTotpy instances against the same database for availability.

Allowed values are:

  • SKIP: skips checking and running database migrations. Useful when handled externally.
  • RUN: check and run database migrations when necessary. Starts the application on success.
  • RUN_AND_EXIT: check and run database migrations when necessary and exit with status code 0 on success.
POSTGRES_MIGRATOR_MODE=RUN

POSTGRES_MIGRATOR_CONNECTION_STR​

Set the connection string for the database for running schema migrations.

The user MUST have the necessary permissions to create and edit the database schemas and tables. Using the PostgreSQL superuser account can be acceptable here since it's only used for schema migrations and to create the unprivileged user POSTGRES_MIGRATOR_UNPRIVILEGED_USER.

info

This config is ignored when POSTGRES_MIGRATOR_MODE is set to SKIP.

The format is the following: postgresql://<username>:<password>@<host>:<port>/<database>

POSTGRES_MIGRATOR_CONNECTION_STR=

POSTGRES_MIGRATOR_UNPRIVILEGED_USER​

Username for the unprivileged user that will created when schema migrations are run.

This user will have the minimum permissions possible to only access the interested tables needed for AVTotpy to work.

When left unset, no unprivileged user will be created.

info

This config is ignored when POSTGRES_MIGRATOR_MODE is set to SKIP.

POSTGRES_MIGRATOR_UNPRIVILEGED_USER=

POSTGRES_MIGRATOR_UNPRIVILEGED_USER_PASSWORD​

Password for the unprivileged user POSTGRES_MIGRATOR_UNPRIVILEGED_USER that will be created when schema migrations are run.

info

This config is ignored when POSTGRES_MIGRATOR_MODE is set to SKIP.

info

This config is ignored when POSTGRES_MIGRATOR_UNPRIVILEGED_USER is left unset.

POSTGRES_MIGRATOR_UNPRIVILEGED_USER_PASSWORD=

Authelia​

Configurations for the Authelia authentication provider.

AUTHELIA_PROXY_SAFE_CIDR​

Either an IPv4 or IPv6 CIDR range used to verify the HTTP request is really coming from an authorized proxy.

The default value is 0.0.0.0/0 for simplicity, but it's vital to set it to either the exact IP address of the Authelia instance or to the strictest CIDR range that can contain it; failing to do so, may result in external actors being able to bypass the Authelia authentication.

caution

The CIDR must allow the proxy address, not Authelia directly.

AUTHELIA_PROXY_SAFE_CIDR=0.0.0.0/0

AUTHELIA_REMOTE_USER_HEADER​

The header name where Authelia and the proxy will put the username of the authenticated user.

The username must be unique for avtotpy to work correctly.

AUTHELIA_REMOTE_USER_HEADER=remote-user

AUTHELIA_REMOTE_GROUPS_HEADER​

The header name where Authelia and the proxy will put the groups where the authenticated user belongs to.

AUTHELIA_REMOTE_GROUPS_HEADER=remote-groups

AUTHELIA_REMOTE_NAME_HEADER​

The header name where Authelia and the proxy will put the display name of the authenticated user.

AUTHELIA_REMOTE_NAME_HEADER=remote-name

TOTP​

Configurations about the one-time OTP (TOTP) generation and storage.

TOTP_ENCRYPTION_SECRET_BASE64​

A 32 bytes long secret used to encrypt the TOTP codes at-rest encoded as a base64 string.

Ensure the secret has enough entropy to prevent secrets compromise. It's highly recommended to generate safe secrets with the following command:

openssl rand -base64 32
TOTP_ENCRYPTION_SECRET_BASE64=