Documentation navigation

Environment Variables

Configure your downloaded app from the .env.example in that generated repository. Its selected integrations can differ from the hosted Djass service. Start with the generated-app checklist below; the later reference lists hosted Djass runtime settings, not a list to copy wholesale into your app.

Configure a generated app

Work inside the downloaded project root, beside manage.py and docker-compose-local.yml. Copy the example once; do not overwrite an existing .env that already contains your settings:

cp .env.example .env

The bundled starter checked October 17, 2026 uses these connection rules. Older downloads should follow their own .env.example, project settings.py, and docker-compose-local.yml.

Where Django runs PostgreSQL address Redis address
Generated local Compose backend or worker db:5432 redis:6379
Python running directly on your machine, with dependencies in local Compose localhost and LOCAL_POSTGRES_PORT localhost and LOCAL_REDIS_PORT

Host port changes do not change the ports used between containers. For example, changing LOCAL_POSTGRES_PORT to 5433 does not mean the Compose backend should use POSTGRES_PORT=5433. Docker's Compose networking reference explains service-name discovery and host versus container ports.

Check generated media storage before uploading files

Selecting Use S3 is not a private-upload implementation. Before following the private-attachment build brief, check the downloaded app's <project_slug>/settings.py, .env.example, and docker-compose-local.yml. The bundled starter checked October 30, 2026 has these storage rules:

  • Backend: a blank AWS_S3_ENDPOINT_URL selects filesystem storage; a nonempty value selects S3-compatible storage. Choose before storing files; changing the backend does not copy existing media.
  • Bucket: STORAGES["default"]["OPTIONS"]["bucket_name"] is derived from project slug and ENVIRONMENT. Inspect the resulting name. The example's AWS_S3_BUCKET_NAME is not read by the generated settings. To use it, explicitly wire it into bucket_name. Compare the name with the bucket created by the local Compose bootstrap; do not assume they match.
  • Region: region_name is set to eu-east-1, not read from an environment variable. Replace it with your provider's required region. For AWS, use the bucket's actual region; adding AWS_S3_REGION_NAME alone changes nothing.
  • Access: the S3 options specify public-read and querystring_auth=False. For private files, remove the public ACL, enable signed delivery, and authorize downloads in your app. Verify the effective bucket policy; signing alone does not make an object private. The local Compose bootstrap also grants anonymous downloads to its bucket: change that policy before using it for private files.

The S3 configuration examples show a proposed configuration you can implement, not extra environment switches already connected by the generator. Keep the staticfiles alias separate. AWS's Object Ownership reference explains why public-read can fail when ACLs are disabled; do not make a private bucket public to work around that error.

For local Compose, Django inside backend or workers reaches MinIO at http://minio:9000; a browser on your machine uses the published host port, normally http://localhost:9000. The example endpoint uses localhost, which inside a container points back to that container, not MinIO. Adjust the server-side endpoint, then verify that browser-facing URLs use a reachable hostname and matching signature configuration. Do not rewrite a presigned URL's hostname after signing. See Compose networking and the S3 provider checks.

Before accepting real attachments, use a disposable object to prove save, reopen, and delete against the selected backend. For private files, separately prove anonymous reads and another account's downloads are denied, while the authorized download works. Unit tests with filesystem storage cannot establish those provider permissions. These are setup requirements, not checks Djass has run on your deployment; older downloads must be checked against their own code.

Check URL overrides before changing individual fields

A nonempty DATABASE_URL takes precedence over the generated POSTGRES_* settings. A nonempty REDIS_URL takes precedence over REDIS_* and supplies both the default cache and Django Q2 broker. If a connection still points at an old service, inspect these overrides locally before changing more fields. Do not paste connection URLs or passwords into a support message.

Leave both URL overrides empty to use the individual connection fields. Keep SITE_URL aligned with LOCAL_WEB_PORT; port 8001, for example, needs SITE_URL=http://localhost:8001. Optional integration variables appear according to your generator choices; their presence does not mean a provider account or production secret has been configured.

Apply and check the configuration

The generated Compose file passes .env to both backend and workers through env_file. This is separate from Compose reading values for ${...} interpolation; creating an .env file alone is not a general promise that every container receives its values. See Docker's container environment reference.

After editing runtime values, recreate the affected containers for both backend and workers so they receive the new environment; restarting an old container alone does not replace its configured environment. Then use the generated Makefile's checks:

make manage check
docker compose -f docker-compose-local.yml ps

These commands follow the bundled Makefile and Compose file checked October 17, 2026. Passing Django checks is not proof of email delivery, a completed background job, or production readiness. Verify the first account and an actual worker result using the local-development checklist. Check logs locally and redact secrets before sharing diagnostics. Do not publish docker compose config output: resolved configuration can contain credentials.

Keep .env out of Git. Local example credentials are not production secrets; set a unique SECRET_KEY, ENVIRONMENT=prod, and DEBUG=off for deployment, then validate the settings and integrations used by that deployment.

Configure recurring billing only if selected

For a generated app with Use Stripe, the bundled settings use STRIPE_PRICE_ID_MONTHLY and STRIPE_PRICE_ID_YEARLY for recurring plans, alongside STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET. Do not copy the hosted service's one-time price IDs below into those recurring-plan slots. Follow the generated-app Stripe preflight to check presence without printing values, then verify actual Checkout and webhook behavior in your Stripe test environment. Present values are not proof of a working billing integration.

Check generated Sentry before the first event

When you select Use Sentry, inspect <project_slug>/settings.py, <project_slug>/sentry_utils.py, and .env.example in your downloaded app. The bundled starter passes ENVIRONMENT to the SDK; the hosted-runtime SENTRY_ENVIRONMENT override listed later is not wired into generated settings. The sample .env sets SENTRY_ENABLED=True, so adding a DSN can enable collection in development as well as production. Review that flag before adding credentials.

Follow the generated-app Sentry preflight for activation, release identity and sampling, then verify a synthetic web and worker error in your own staging environment. Source defaults are not proof that an event arrived or that customer data is safe to capture.

Check generated logging before adding exporters

Choose DJANGO_LOG_FORMAT=json explicitly when you want JSON output. In the bundled starter checked November 8, 2026, the copied example's empty DJANGO_LOG_FORMAT= selects console even with ENVIRONMENT=prod; only an absent variable uses the production JSON default. DJANGO_LOG_LEVEL=INFO controls application records. The bundled console handlers write to stderr, so check that your collector accepts it.

Follow the generated-app first-record check with synthetic fields in a disposable local configuration. Apply environment changes to fresh web and worker processes using the recreation step above. A local JSON line is not evidence that PostHog or Sentry received it, and formatting does not remove sensitive fields for you.

Hosted Djass runtime reference

The remaining settings describe the Djass generator service. Generated customer apps do not need its template-source setting or one-time generation-access price IDs. Use your app's own example for its payment, AI, and optional integration variables.

For this service, .env.example is the source of truth:

cp .env.example .env

Core runtime variables

These should always be set intentionally.

  • ENVIRONMENT — dev or prod
  • DEBUG — keep off/False outside local development
  • SECRET_KEY — Django secret key
  • SITE_URL — canonical app URL
  • MEDIA_ROOT — path for generated artifacts and uploaded files

Database

  • POSTGRES_DB
  • POSTGRES_USER
  • POSTGRES_PASSWORD
  • POSTGRES_HOST
  • POSTGRES_PORT

These values configure the connection; they do not configure retention or prove recoverability. Use the Django database backup guide to define RPO/RTO, choose provider PITR and logical-dump layers, and run an isolated restore drill.

Redis + background jobs

  • REDIS_HOST
  • REDIS_PORT
  • REDIS_PASSWORD
  • REDIS_DB

Django Q2 uses Redis for queueing and worker communication.

Project generation

  • COOKIECUTTER_TEMPLATE_PATH — template source used for generated projects. Leave it unset to render the django-saas-starter template bundled in the repository under starter/. The retired LVTD-LLC/django-saas-starter and rasulkireev/django-saas-starter GitHub URLs resolve to the same bundled template, so no deploy key or network access is needed to generate a project.

Set it to a different local directory or remote Cookiecutter source only when you intentionally want to render another template.

Optional integrations

Enable only what you actively use.

Authentication

  • GITHUB_CLIENT_ID
  • GITHUB_CLIENT_SECRET

Storage

  • AWS_S3_ENDPOINT_URL
  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY

If AWS_S3_ENDPOINT_URL is empty, filesystem storage is used.

The hosted settings also derive the bucket name from djass and ENVIRONMENT; they do not read AWS_S3_BUCKET_NAME. For a downloaded app, use the generated-media checklist above rather than copying hosted settings.

Use the Django S3 storage guide to verify the generated backend against your provider, separate public and private media, and plan migration and rollback before changing production reads.

Email and newsletter

  • MAILGUN_API_KEY
  • MAILGUN_SENDER_DOMAIN (e.g. mg.gregagi.com)
  • MAILGUN_API_URL (hosted generator only; optional, set https://api.eu.mailgun.net/v3 for EU-region domains)
  • DEFAULT_FROM_EMAIL (optional sender override)
  • SERVER_EMAIL (optional error sender override)
  • BUTTONDOWN_API_KEY

Use the production Django email guide to connect these settings to commit-safe intent, queued dispatch, retries, provider webhooks, suppression policy, monitoring, and lifecycle tests.

For a generated app, the bundled settings read EMAIL_BACKEND as an override before choosing local SMTP, production console fallback or Mailgun. They do not read MAILGUN_API_URL from .env; configure the Anymail region in the generated Python settings if needed. Start with the generated-app email diagnostic before treating a successful send call as proof of delivery.

Customer support

  • CHATWOOT_BASE_URL (e.g. https://chatwoot.example.com)
  • CHATWOOT_WEBSITE_TOKEN (public website inbox token)

Observability

Use the Django Sentry production guide to choose these values as one release, privacy, sampling, worker, and incident-response contract instead of copying quickstart rates into production.

  • SENTRY_DSN
  • SENTRY_ENABLED (optional; defaults to enabled only when SENTRY_DSN is set in prod)
  • SENTRY_ENVIRONMENT (optional Sentry environment override)
  • SENTRY_RELEASE (optional release/version, ideally the deployed commit SHA)
  • SENTRY_TRACES_SAMPLE_RATE (default 1.0)
  • SENTRY_PROFILE_SESSION_SAMPLE_RATE (default 1.0)
  • SENTRY_ENABLE_LOGS (default True)
  • SENTRY_SEND_DEFAULT_PII (default False)
  • SENTRY_INCLUDE_LOCAL_VARIABLES (default False)
  • SENTRY_MAX_BREADCRUMBS (default 100)
  • SENTRY_AI_INCLUDE_PROMPTS (default False; set to True only if prompt/response capture is acceptable)
  • SENTRY_AI_HANDLED_TOOL_CALL_EXCEPTIONS (default True)
  • LOGFIRE_TOKEN
  • POSTHOG_API_KEY (project API key phc_... used by Djass capture calls)
  • POSTHOG_HOST (https://us.i.posthog.com or https://eu.i.posthog.com)

Payments

  • PAYMENTS_ENABLED (default True) — when enabled, project generation requires paid account access
  • GRANT_PRO_MEMBERSHIP_ON_SIGNUP (default False) — assigns new users subscribed/pro access immediately
  • STRIPE_SECRET_KEY
  • STRIPE_WEBHOOK_SECRET
  • STRIPE_PRICE_ID_ONE_TIME
  • STRIPE_PRICE_ID_LAUNCH_10
  • STRIPE_PRICE_ID_LAUNCH_100
  • STRIPE_PRICE_ID_LAUNCH_200
  • STRIPE_PRICE_ID_LAUNCH_999

AI provider

  • OPENAI_API_KEY

Optional model overrides:

  • OPENAI_MODEL_FAST, OPENAI_MODEL_BALANCED, OPENAI_MODEL_SMART
  • ANTHROPIC_MODEL_FAST, ANTHROPIC_MODEL_BALANCED, ANTHROPIC_MODEL_SMART
  • GEMINI_MODEL_FAST, GEMINI_MODEL_BALANCED, GEMINI_MODEL_SMART

Configuration sanity checklist

  • DEBUG is off outside local development
  • DB/Redis credentials are not default placeholders
  • secrets are managed securely and never committed
  • MEDIA_ROOT (or S3 config) is persistent for generated artifacts

Security notes

  • Never commit .env.
  • Rotate credentials immediately if exposed.
  • Prefer secret managers over plaintext files when possible.
  • Keep PostHog personal/management API keys out of app runtime config; Djass only needs the project API key for ingestion.