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:
DEBUGINFOWARNINGERRORCRITICAL
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:
DEBUGINFOWARNINGERRORCRITICAL
POSTGRES_PSYCOPG_LOG_LEVEL=WARNING
POSTGRES_PSYCOPG_POOL_LOG_LEVEL
Changes the log level for the psycopg library's connection pooler.
Allowed values are:
DEBUGINFOWARNINGERRORCRITICAL
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.
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.
Does nothing when POSTGRES_DISABLE_CONNECTION_POOLING is set to True.
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.
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.
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.
Does nothing when POSTGRES_DISABLE_CONNECTION_POOLING is set to True.
POSTGRES_POOL_TIMEOUT=30.0
POOL_MAX_LIFETIME
The maximum lifetime of a connection in the pool, in seconds. Connections used for longer get closed and replaced by a new one.
POOL_MAX_LIFETIME=3600.0
POOL_RECONNECT_TIMEOUT
Maximum time, in seconds, the pool will try to create a connection.
If a connection attempt fails, the pool will try to reconnect a few times, using an exponential backoff and some random factor to avoid mass attempts.
POOL_RECONNECT_TIMEOUT=300.0
POOL_CHECK_CONNECTION
If enabled, every PostgreSQL open connection will check its state by running a SELECT 1; statement before running the
expected query. This adds latency and an extra round trip but ensures that the connection is always alive before
use.
In case the connection turns out dead, the pooler will try a new connection transparently.
POOL_CHECK_CONNECTION=False
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.
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.
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.
This config is ignored when POSTGRES_MIGRATOR_MODE is set to SKIP.
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.
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=