Skip to content

Configuration

Jump to bottom
sassanix edited this page Oct 30, 2026 · 3 revisions

sliders-h icon Configuration

Warracker has two layers of configuration:

  • Environment variables (.env) — deployment-time values: database, secrets, SMTP, OIDC, upload limits. Set these before first start; change them by editing .env and recreating the container.
  • Settings UI — everything you change after install: user preferences, notification channels, OIDC and Paperless details, site settings. See Settings.

Copy Docker/.env.example (also available as env.example at the repository root) to .env next to your compose file and fill in the values.

Contents

How it works

Inside the container, three services run under a supervisor:

  • nginx on port 80 (mapped to host port 8005 by default) — serves the static frontend and proxies API calls to the backend.
  • Gunicorn — runs the Flask backend, which talks to PostgreSQL.
  • cron — runs the scheduled notification checks.

On every container start, the entrypoint waits for the database, runs any pending database migrations, fixes permissions, and compiles translations. That is why updates are just "pull and recreate" — see Updating.

Database

Variable Default Notes
DB_HOST warrackerdb Service name of the database container
DB_PORT 5432
DB_NAME warranty_db Must match the database container's database
DB_USER / DB_PASSWORD warranty_user / set in .env App credentials
DB_ADMIN_USER / DB_ADMIN_PASSWORD warracker_admin / set in .env Used for migrations and setup
POSTGRES_DB / POSTGRES_USER / POSTGRES_PASSWORD Same as above These configure the database container itself; keep them in sync with DB_*

PostgreSQL is required — there is no SQLite option.

Security

Variable Default Notes
SECRET_KEY (empty) Signs JWTs and Flask sessions. Generate one with openssl rand -hex 32. If left empty, the app generates a random key and saves it inside the container — it is lost on container recreate, which invalidates sessions (data is unaffected). Always set it explicitly in production.
JWT_EXPIRATION_HOURS 24 How long login tokens stay valid

Email / SMTP

Email powers password resets and email notifications. Without it, password reset does not work (see FAQ).

Variable Default Notes
SMTP_HOST / SMTP_PORT smtp.gmail.com / 587
SMTP_USERNAME / SMTP_PASSWORD — Login for the SMTP server
SMTP_USE_TLS / SMTP_USE_SSL true / false Use one or the other, not both
SMTP_SENDER_EMAIL noreply@warracker.com Shown as the sender
SMTP_FROM_ADDRESS (falls back to username) Override the from address if your provider requires it

URLs

Variable Default Notes
FRONTEND_URL http://localhost:8005 Your public URL. Must match the real public address, or OIDC redirects and email links break.
APP_BASE_URL http://localhost:8005 Same value as FRONTEND_URL in practice; used for links in emails and redirects.

When you put Warracker behind a reverse proxy, set both to the public https:// URL — see Reverse Proxy.

File uploads

Variable Default Notes
MAX_UPLOAD_MB 16 in the compose file (32 code default) Per-file limit. The value in your compose file / .env wins.
NGINX_MAX_BODY_SIZE_VALUE 16M in the compose file Must match or exceed MAX_UPLOAD_MB, or nginx rejects the upload before the app sees it.
UPLOAD_FOLDER /data/uploads Where files are stored inside the container; back this up (see Backup and Restore).

Performance

Variable Default Notes
WARRACKER_MEMORY_MODE optimized optimized: 2 workers, ~60–80 MB RAM. ultra-light: 1 worker, ~40–50 MB. performance: 4 workers, ~150–200 MB.

OIDC / SSO

Variable Default Notes
OIDC_ENABLED false
OIDC_ONLY_MODE false Hides the username/password form; OIDC login only. Overrides the Settings UI value when set.
OIDC_SKIP_LOGIN_SCREEN false Redirects straight to the provider. Only takes effect together with OIDC_ONLY_MODE.
OIDC_PROVIDER_NAME oidc Affects button branding: google, github, microsoft, keycloak, and others.
OIDC_CLIENT_ID / OIDC_CLIENT_SECRET — From your identity provider.
OIDC_ISSUER_URL — For example, https://accounts.google.com.
OIDC_SCOPE openid email profile
OIDC_ADMIN_GROUP — Optional; requires the group scope. Members of this provider group become admins.

The redirect URI to register at your provider is your public URL plus /oidc/callback. Full behavior is documented in Authentication.

Apprise notifications

Apprise can also be configured in the Settings UI; these variables set the deployment-time values.

Variable Default Notes
APPRISE_ENABLED false
APPRISE_URLS — Comma-separated notification URLs, for example mailto://user:pass@gmail.com,discord://webhook_id/webhook_token.
APPRISE_EXPIRATION_DAYS 7,30 Days before expiry to notify.
APPRISE_NOTIFICATION_TIME 09:00 Time of day (HH:MM).
APPRISE_TITLE_PREFIX [Warracker] Prefix for notification titles.

Advanced

Variable Default Notes
DISABLE_NGINX false Set to true to run Gunicorn directly on port 5000 without the container's nginx — useful if your own reverse proxy handles static files and TLS. Publish port 5000 in that case.
FLASK_ENV production development enables debug mode; never use it in production.
FLASK_DEBUG false
FLASK_RUN_PORT 5000 Development only.
PYTHONUNBUFFERED 1 Keeps container logs readable.

Clone this wiki locally