Skip to content

Configuration Settings

This page collects the environment variables that live under the # Validibot settings blocks in config/settings/base.py and config/settings/local.py. Keep it close at hand when you need to toggle product features or smoke-test workflow execution.

Core settings (config/settings/base.py)

Variable Default Purpose
POSTMARK_SERVER_TOKEN None API token used by Postmark to send transactional email. Leave unset to disable outbound mail in lower environments.
POSTMARK_WEBHOOK_ALLOWED_IPS Postmark CIDR list Hardens the inbound webhook endpoint by only trusting requests from the documented Postmark ranges.
GITHUB_APP_ID, GITHUB_CLIENT_ID, GITHUB_NAME, GITHUB_PRIVATE_KEY, GITHUB_WEBHOOK_SECRET required when GitHub App is enabled Configure the GitHub App integration that provisions workflow runs from pull requests. The private key value may include literal \n characters that we normalize in settings.
WORKFLOW_RUN_POLL_INTERVAL_SECONDS 3 Controls how frequently the run-detail page polls HTMX for run-status updates. Increasing the value lowers UI churn at the expense of slower refresh cycles.
DJANGO_ACCOUNT_ALLOW_LOGIN True Set to False to temporarily freeze interactive login (used during security incidents).
ENABLE_APP, ENABLE_API True Feature gates for the entire application shell and the public API.
TEST_ENERGYPLUS_WEATHER_FILE USA_CA_SF.epw Default weather file used when exercising EnergyPlus validators outside production.
GCS_WEATHER_DATA_DIR weather_data Subdirectory within validator_assets/ for weather data files. Full path: gs://<bucket>/validator_assets/weather_data/<file>.epw. Use just sync-weather <env> to sync local files.
TRACKER_INCLUDE_SUPERUSER False When True, superuser traffic is included in analytics events. Keep it False locally to avoid noisy metrics.
DJANGO_DEFAULT_FROM_EMAIL Validibot <noreply@example.com> Human-friendly From header for transactional email.
POSTHOG_PROJECT_KEY empty (disabled) PostHog project API key. Leave empty to disable analytics tracking.
POSTHOG_API_HOST https://us.i.posthog.com PostHog API host URL. Change if using EU data residency or self-hosted PostHog.
SITE_URL http://localhost:8000 Public base URL used for links in e-mails and the public-facing app (prod typically uses https://validibot.com).
WORKER_URL empty Internal base URL for the worker service (use the worker *.run.app URL). Validator callbacks and scheduled tasks should target this URL, not SITE_URL.

The submission-size constants that sit in the same section (SUBMISSION_INLINE_MAX_BYTES, SUBMISSION_FILE_MAX_BYTES, etc.) are not env-driven today; adjust them directly in base.py if we ever need new limits.

Initial setup environment variables

These variables are used by the setup_validibot management command during first-time installation. They configure the Django Sites framework, which is used for generating absolute URLs in emails and other contexts.

Variable Default Purpose
VALIDIBOT_SITE_DOMAIN interactive prompt or localhost:8000 Site domain for the Django Sites framework (e.g., validibot.example.com). Can also be set via --domain argument.
VALIDIBOT_SITE_NAME Validibot Display name for the site. Can also be set via --site-name argument.

These are only used during initial setup. To update the site domain later, re-run:

python manage.py setup_validibot --domain newdomain.example.com
python manage.py check_validibot  # Verify configuration

Local development settings (config/settings/local.py)

Variable Default Purpose
SUPERUSER_USERNAME, SUPERUSER_PASSWORD, SUPERUSER_EMAIL, SUPERUSER_NAME admin, someadminpwchangeforrealz, "", Admin User Seed credentials used by the create_local_superuser helper so every teammate can bootstrap a superuser quickly.
SIMULATE_LONG_TASKS True When set, every validation run incurs a synthetic delay so we can preview loading states (for example, the workflow run progress bar).
LONG_TASK_DELAY_SECONDS 20 Duration of the synthetic delay applied while SIMULATE_LONG_TASKS is enabled. Lower it if you simply need a quick manual test of the polling UI.

These knobs affect inline execution only when the local settings module is active. Production ignores them entirely, so you are safe to leave the defaults in your .env file for day-to-day development.