Environment Variables

Zou uses environment variables for configuration. All configuration is defined in zou/app/config.py.

Core Settings

DEBUG

boolean

default:"False"

Enable debug mode. Shows detailed error messages and enables auto-reload.

Never enable in production environments

DEBUG_HOST

string

default:"127.0.0.1"

Host address for debug server.

DEBUG_PORT

integer

default:"5000"

Port for debug server.

SECRET_KEY

string

default:"mysecretkey"

Secret key for session encryption and JWT tokens.

Must be changed in production. Use a strong random string

Database Configuration

DB_DRIVER

string

default:"postgresql+psycopg"

SQLAlchemy database driver. Uses psycopg (version 3) by default.

DB_HOST

string

default:"localhost"

PostgreSQL database host address.

DB_PORT

string

default:"5432"

PostgreSQL database port.

DB_USERNAME

string

default:"postgres"

Database username for authentication.

DB_PASSWORD

string

default:"mysecretpassword"

Database password for authentication.

Change this in production environments

DB_DATABASE

string

default:"zoudb"

Name of the PostgreSQL database.

Connection Pool Settings

DB_POOL_SIZE

integer

default:"30"

Number of database connections to maintain in the pool.

DB_MAX_OVERFLOW

integer

default:"60"

Maximum number of connections that can be created beyond pool_size.

DB_POOL_PRE_PING

boolean

default:"True"

Verify connections before using them. Prevents using stale connections.

DB_POOL_RECYCLE

integer

default:"3600"

Recycle connections after this many seconds (prevents long-lived connections).

DB_POOL_RESET_ON_RETURN

string

default:"commit"

Reset connections when returning to pool. Options: commit, rollback, none.Cleans up transaction state to prevent issues between requests.

Redis / Key-Value Store

KV_HOST

string

default:"localhost"

Redis server host for caching, event streams, and job queues.

KV_PORT

string

default:"6379"

Redis server port.

KV_PASSWORD

string

default:"None"

Redis password for authentication (if required).

CACHE_TYPE

string

default:"None"

Cache backend type. Set to enable caching.

Authentication & Security

AUTH_STRATEGY

string

default:"auth_local_classic"

Authentication strategy. Options:

auth_local_classic - Standard username/password authentication
LDAP authentication (requires additional LDAP configuration)
SAML authentication (requires additional SAML configuration)

BCRYPT_LOG_ROUNDS

integer

default:"12"

Bcrypt password hashing rounds. Higher values increase security but slow down authentication.

MIN_PASSWORD_LENGTH

integer

default:"8"

Minimum password length requirement.

ENFORCE_2FA

boolean

default:"False"

Require two-factor authentication for all users.

2FA_EXEMPT_USERS

string

default:""

Comma-separated list of user emails exempt from mandatory 2FA requirement.Example: user1@example.com,user2@example.com

PROTECTED_ACCOUNTS

string

default:""

Semicolon-separated list of protected account emails that cannot be modified.

USER_LIMIT

integer

default:"100"

Maximum number of users allowed in the system.

JWT Token Configuration

JWT tokens are managed automatically. The following are configured in code:

Access token expires: 7 days
Refresh token expires: 15 days
Token locations: cookies and headers
Cookie SameSite: Lax

CLIENT_CACHE_MAX_AGE

integer

default:"604800"

Client-side cache max age in seconds (default: 7 days).

File Storage

PREVIEW_FOLDER

string

default:"./previews"

Local folder path for storing preview files and thumbnails.Falls back to THUMBNAIL_FOLDER if set, otherwise uses ./previews.

PREVIEW_SAVE_SOURCE_FILE

boolean

default:"False"

Save original source files alongside generated previews.

TMP_DIR

string

default:"/tmp/zou"

Temporary directory for file processing.

FS_BACKEND

string

default:"local"

File storage backend. Options:

local - Local filesystem storage
swift - OpenStack Swift object storage
s3 - Amazon S3 or S3-compatible storage

FS_BUCKET_PREFIX

string

default:""

Prefix for storage bucket names.

Swift Storage Configuration

FS_SWIFT_AUTHURL

string

OpenStack Swift authentication URL.

FS_SWIFT_USER

string

Swift username for authentication.

FS_SWIFT_TENANT_NAME

string

Swift tenant/project name.

FS_SWIFT_KEY

string

Swift authentication key/password.

FS_SWIFT_REGION_NAME

string

Swift region name.

FS_SWIFT_CREATE_CONTAINER

boolean

default:"False"

Automatically create containers if they don’t exist.

FS_SWIFT_AUTH_VERSION

string

default:"3"

Swift authentication version.

FS_SWIFT_AES256_ENCRYPTED

boolean

default:"False"

Enable AES-256 encryption for stored files.

FS_SWIFT_AES256_KEY

string

AES-256 encryption key for Swift storage.

S3 Storage Configuration

FS_S3_REGION

string

AWS region for S3 storage.

FS_S3_ENDPOINT

string

S3-compatible endpoint URL (for MinIO, Wasabi, etc.).

FS_S3_ACCESS_KEY

string

S3 access key ID.

FS_S3_SECRET_KEY

string

S3 secret access key.

FS_S3_CREATE_BUCKET

boolean

default:"False"

Automatically create S3 buckets if they don’t exist.

FS_S3_AES256_ENCRYPTED

boolean

default:"False"

Enable AES-256 encryption for stored files.

FS_S3_AES256_KEY

string

AES-256 encryption key for S3 storage.

REMOVE_FILES

boolean

default:"False"

Enable file deletion functionality.

Event Stream

EVENT_STREAM_HOST

string

default:"localhost"

Host address for the event stream WebSocket server.

EVENT_STREAM_PORT

string

default:"5001"

Port for the event stream WebSocket server.

EVENT_HANDLERS_FOLDER

string

default:"./event_handlers"

Folder containing custom event handler scripts.

Mail Configuration

MAIL_ENABLED

boolean

default:"True"

Enable email notifications.

MAIL_SERVER

string

default:"localhost"

SMTP server address.

MAIL_PORT

string

default:"25"

SMTP server port.

MAIL_USERNAME

string

default:""

SMTP username for authentication.

MAIL_PASSWORD

string

default:""

SMTP password for authentication.

MAIL_DEBUG

boolean

default:"False"

Enable mail debugging output.

MAIL_DEBUG_BODY

boolean

default:"False"

Include email body in debug output.

MAIL_USE_TLS

boolean

default:"False"

Use TLS for SMTP connection.

MAIL_USE_SSL

boolean

default:"False"

Use SSL for SMTP connection.

MAIL_DEFAULT_SENDER

string

default:"no-reply@your-studio.com"

Default sender email address.

MAIL_CHECK_DELIVERABILITY

boolean

default:"True"

Check email address deliverability before sending.

DOMAIN_NAME

string

default:"localhost:8080"

Domain name for email links.

DOMAIN_PROTOCOL

string

default:"https"

Protocol for email links (http or https).

LDAP Authentication

LDAP_HOST

string

default:"127.0.0.1"

LDAP server host address.

LDAP_PORT

string

default:"389"

LDAP server port.

LDAP_BASE_DN

string

default:"cn=Users,dc=zou,dc=local"

LDAP base distinguished name.

LDAP_GROUP

string

default:""

LDAP group to restrict access.

LDAP_DOMAIN

string

default:"zou.local"

LDAP domain name.

LDAP_FALLBACK

boolean

default:"False"

Fall back to local authentication if LDAP fails.

LDAP_IS_AD

boolean

default:"False"

Use Active Directory authentication mode.

LDAP_IS_AD_SIMPLE

boolean

default:"False"

Use simplified Active Directory authentication.

LDAP_SSL

boolean

default:"False"

Use SSL/TLS for LDAP connection.

SAML Authentication

SAML_ENABLED

boolean

default:"False"

Enable SAML single sign-on authentication.

SAML_IDP_NAME

string

default:""

SAML identity provider name.

SAML_METADATA_URL

string

default:""

URL to SAML identity provider metadata.

Search Indexer

INDEXER_HOST

string

default:"localhost"

Meilisearch indexer host address.

INDEXER_PORT

string

default:"7700"

Meilisearch indexer port.

INDEXER_PROTOCOL

string

default:"http"

Protocol for indexer connection (http or https).

INDEXER_KEY

string

Meilisearch API key for authentication.

INDEXER_TIMEOUT

integer

default:"5000"

Indexer request timeout in milliseconds.

Job Queue

ENABLE_JOB_QUEUE

boolean

default:"False"

Enable background job queue processing.

ENABLE_JOB_QUEUE_REMOTE

boolean

default:"False"

Use remote job queue (Nomad) instead of local processing.

JOB_QUEUE_NOMAD_PLAYLIST_JOB

string

default:"zou-playlist"

Nomad job name for playlist processing.

JOB_QUEUE_NOMAD_NORMALIZE_JOB

string

default:""

Nomad job name for video normalization.

JOB_QUEUE_NOMAD_HOST

string

default:"zou-nomad-01.zou"

Nomad server host address.

JOB_QUEUE_TIMEOUT

string

default:"3600"

Job queue timeout in seconds.

Logging & Monitoring

LOGS_MODE

string

default:"default"

Logging mode configuration.

LOGS_HOST

string

default:"localhost"

Remote logging server host.

LOGS_PORT

string

default:"2202"

Remote logging server port.

LOGS_TOKEN

string

Authentication token for remote logging.

LOG_FILE_NOT_FOUND

boolean

default:"False"

Log 404 file not found errors.

Sentry Error Tracking

SENTRY_ENABLED

boolean

default:"False"

Enable Sentry error tracking for API.

SENTRY_DSN

string

default:""

Sentry DSN (Data Source Name) for API.

SENTRY_SR

float

default:"1.0"

Sentry sample rate for API (0.0 to 1.0).

SENTRY_DEBUG_URL

string

default:"False"

Sentry debug URL configuration.

SENTRY_KITSU_ENABLED

boolean

default:"False"

Enable Sentry error tracking for Kitsu frontend.

SENTRY_KITSU_DSN

string

default:""

Sentry DSN for Kitsu frontend.

SENTRY_KITSU_SR

float

default:"0.1"

Sentry sample rate for Kitsu frontend (0.0 to 1.0).

Prometheus Metrics

PROMETHEUS_METRICS_ENABLED

boolean

default:"False"

Enable Prometheus metrics endpoint.

Localization

DEFAULT_TIMEZONE

string

default:"Europe/Paris"

Default timezone for the application.

DEFAULT_LOCALE

string

default:"en_US"

Default locale for the application.

Pagination

NB_RECORDS_PER_PAGE

integer

default:"100"

Number of records per page for paginated API endpoints.

Plugins

PLUGIN_FOLDER

string

default:"./plugins"

Folder containing custom plugins.

Telemetry

IS_SELF_HOSTED

boolean

default:"True"

Indicate if this is a self-hosted instance.

TELEMETRY_URL

string

URL for sending anonymized telemetry data (user and preview counts).Helps size the Kitsu community. Set by default based on DEBUG mode.

CRISP_TOKEN

string

default:""

Crisp chat widget token.

Deprecated Variables

DEFAULT_FILE_TREE

string

default:"default"

Default file tree template.

Deprecated - may be removed in future versions

THUMBNAIL_FOLDER

string

Legacy preview folder path.

Deprecated - use PREVIEW_FOLDER instead

Example Configuration

# Core
export SECRET_KEY="your-secret-key-here"
export DEBUG=False

# Database
export DB_HOST="localhost"
export DB_PORT="5432"
export DB_USERNAME="postgres"
export DB_PASSWORD="secure-password"
export DB_DATABASE="zoudb"
export DB_POOL_SIZE="30"

# Redis
export KV_HOST="localhost"
export KV_PORT="6379"

# Storage
export PREVIEW_FOLDER="/var/zou/previews"
export FS_BACKEND="local"

# Mail
export MAIL_ENABLED=True
export MAIL_SERVER="smtp.example.com"
export MAIL_PORT="587"
export MAIL_USE_TLS=True
export MAIL_USERNAME="notifications@studio.com"
export MAIL_PASSWORD="mail-password"
export MAIL_DEFAULT_SENDER="noreply@studio.com"

# Domain
export DOMAIN_NAME="kitsu.studio.com"
export DOMAIN_PROTOCOL="https"

# Event Stream
export EVENT_STREAM_HOST="0.0.0.0"
export EVENT_STREAM_PORT="5001"

Get Started

Core Concepts

Configuration

CLI Reference

Core Settings

Database Configuration

Connection Pool Settings

Redis / Key-Value Store

Authentication & Security

JWT Token Configuration

File Storage

Swift Storage Configuration

S3 Storage Configuration

Event Stream

Mail Configuration

LDAP Authentication

SAML Authentication

Search Indexer

Job Queue

Logging & Monitoring

Sentry Error Tracking

Prometheus Metrics

Localization

Plugins

Telemetry

Deprecated Variables

Example Configuration

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

CLI Reference

Documentation Index

​Core Settings

​Database Configuration

​Connection Pool Settings

​Redis / Key-Value Store

​Authentication & Security

​JWT Token Configuration

​File Storage

​Swift Storage Configuration

​S3 Storage Configuration

​Event Stream

​Mail Configuration

​LDAP Authentication

​SAML Authentication

​Search Indexer

​Job Queue

​Logging & Monitoring

​Sentry Error Tracking

​Prometheus Metrics

​Localization

​Pagination

​Plugins

​Telemetry

​Deprecated Variables

​Example Configuration

Build docs developers (and LLMs) love

Core Settings

Database Configuration

Connection Pool Settings

Redis / Key-Value Store

Authentication & Security

JWT Token Configuration

File Storage

Swift Storage Configuration

S3 Storage Configuration

Event Stream

Mail Configuration

LDAP Authentication

SAML Authentication

Search Indexer

Job Queue

Logging & Monitoring

Sentry Error Tracking

Prometheus Metrics

Localization

Pagination

Plugins

Telemetry

Deprecated Variables

Example Configuration