DjangoPlay Environment Configuration Reference

curl -fsSL https://install.djangoplay.org/config | sudo bash

Every key is marked Required or Optional. Optional means it is not needed for a normal installation; it becomes relevant when its feature or integration is enabled.

This document is the complete key-by-key reference for the four configuration files used by DjangoPlay:

~/.dplay/
├── .secrets
├── .authx
├── config.yaml
└── .appdata
`

This is a configuration reference, not a deployment checklist.

Each configuration key is classified according to when it is needed:

Optional configuration should only be populated when the corresponding feature is actually being used.

Security: .secrets and .authx contain sensitive values. Never commit them to source control or expose private keys and service credentials to clients.

#1. Configuration Files

The files are intentionally separated by responsibility.

• .secrets contains sensitive DjangoPlay configuration.
• .authx contains the environment configuration expected by AuthX.
• config.yaml contains structured, non-secret DjangoPlay configuration.
• .appdata contains optional reference-data configuration.

The scaffold creates these files with restrictive permissions:

~/.dplay/              700
configuration files   600

#2. ~/.dplay/.secrets

.secrets contains DjangoPlay's sensitive application configuration.

#DjangoPlay Core

#Initial Superuser

These values are required for the initial bootstrap flow. They should not be interpreted as credentials that DjangoPlay requires for every subsequent runtime process.

#Platform Administration

Leave both values empty when additional platform administrators are not required.

#Redis

The Redis host, port, and database are configured in config.yaml.

#Google OAuth / SSO

Google OAuth redirect URIs must match the host and port configured for the environment in which the OAuth flow is used.

#Email

The non-secret email configuration is stored under email in config.yaml.

#Abuse Detection

A normal DjangoPlay installation does not require an AbuseIPDB account.

#Cloudflare Turnstile

All Turnstile values are optional. Only the key pair for an environment where Turnstile is enabled needs to be populated.

These values are needed only when Cloudflare Turnstile bot protection is enabled for the corresponding environment.

#Cloudflare R2

These values are only needed when the frontend/CDN workflow performs authenticated operations against Cloudflare R2.

#AI Providers

AI_CUSTOM_BASE_URL and AI_CUSTOM_MODEL are relevant only when aicore is configured to use the custom provider.

#3. ~/.dplay/.authx

.authx contains the configuration consumed by the standalone AuthX Identity service.

It uses AuthX's actual environment-variable names.

AuthX has its own PostgreSQL database and its own JWT signing authority.

#AuthX Application

#AuthX PostgreSQL

Important: POSTGRES_PASSWORD is AuthX's PostgreSQL password. It is separate from DjangoPlay's DB_PASSWORD.

Do not introduce or use an AUTHX_DB_PASSWORD key.

#AuthX JWT Signing

AuthX is the sole JWT signing authority for the DjangoPlay AuthX identity architecture.

AuthX
  │
  │ signs JWT
  ▼
JWT
  │
  │ verified by DjangoPlay
  ▼
DjangoPlay

DjangoPlay does not sign AuthX identity JWTs and does not require JWT_PRIVATE_KEY for normal verification.

#DjangoPlay → AuthX Authentication

#AuthX CORS

#4. AuthX URL and JWT Issuer

APP_BASE_URL and JWT_ISSUER have different purposes.

They do not have to be the same URL.

For example:

APP_BASE_URL=http://127.0.0.1:8100
JWT_ISSUER=https://auth.djangoplay.org

can be intentional.

#5. ~/.dplay/config.yaml

config.yaml contains structured, non-secret DjangoPlay configuration.

#site

site.ssl_port and site.http_port are only needed when the corresponding serving mode requires an explicit port.

#subdomains

#repository

#database

The DjangoPlay database values must remain consistent with the DjangoPlay DATABASE_URL and DB_PASSWORD.

They are separate from AuthX's POSTGRES_* settings.

#redis

Redis authentication is controlled separately by the optional REDIS_PASSWORD in .secrets.

#email

The SMTP password belongs in .secrets as EMAIL_HOST_PASSWORD.

#support

#social

#django

Production example:

django:
  settings_module: paystream.settings.prod

#cdn

The cdn section is only relevant when the frontend/CDN workflow uses Cloudflare R2.

R2 credentials are stored separately in .secrets.

#6. ~/.dplay/.appdata

.appdata is entirely optional.

It is used by reference-data tooling for datasets such as:

• locations
• entities/businesses
• industries/classifications

It can be left unused for normal DjangoPlay application development.

#Reference Data

#Industry / Classification Sources

#Compiled Data Source

The scaffold provides DATA_SOURCE_URL as a default source.

#7. Credential Boundaries

DjangoPlay and AuthX intentionally use separate credentials.

Do not mix these credentials.

DB_PASSWORD          != POSTGRES_PASSWORD
JWT_SIGNING_KEY      != JWT_PRIVATE_KEY
AUTHX_SERVICE_TOKEN  != database password
APP_BASE_URL         != JWT_ISSUER

In particular, there is no AUTHX_DB_PASSWORD configuration key.

#8. Development vs Production

Some configuration values vary by environment.

Do not reuse development private keys or backend service credentials in production.

#9. AuthX RSA Key Generation

AuthX uses an RSA key pair for RS256 JWT signing.

Generate a new pair when creating a new AuthX environment:

openssl genrsa -out jwt_private.pem 2048

openssl rsa \
  -in jwt_private.pem \
  -pubout \
  -out jwt_public.pem

Validate the private key:

openssl rsa -in jwt_private.pem -check -noout

Expected output:

RSA key ok

Verify that the public key corresponds to the private key:

openssl rsa \
  -in jwt_private.pem \
  -pubout \
  -outform PEM | diff - jwt_public.pem

No output and exit status 0 means the public/private pair matches.

#PEM values in .authx

The PEM values stored in environment configuration need to preserve their line breaks using literal \n sequences.

Generate the private-key value with:

awk 'NF {printf "%s\\n", $0}' jwt_private.pem

Generate the public-key value with:

awk 'NF {printf "%s\\n", $0}' jwt_public.pem

The resulting value should contain literal:

\n

between PEM lines.

Do not modify the Base64 key material or introduce arbitrary backslashes into the encoded key body.

JWT_PRIVATE_KEY is an AuthX secret and must never be committed to Git or shared with consuming applications.

#10. Configuration Creation

The repository scaffold creates the four configuration files:

bash scripts/installation/create_env.sh

The public installer provides the same configuration scaffolding remotely:

curl -fsSL https://install.djangoplay.org/config | sudo bash

To intentionally overwrite existing configuration files:

bash scripts/installation/create_env.sh --force

or:

curl -fsSL https://install.djangoplay.org/config | sudo bash -s -- --force

Without --force, existing configuration files are not overwritten.

#11. Configuration Maintenance

This document shall ALWAYS remain synchronized with create_env.sh for below:

Whenever a configuration key is:

• added
• removed
• renamed
• moved between files
• changed from setup-only to runtime
• changed from required to optional
• associated with a new integration

The generated configuration files are the operational configuration.

This document is the human-readable reference explaining:

• where each key belongs
• when each key is required
• which service or tooling consumes it
• what each key does
• which integrations are optional
• which values are environment-specific
• which credentials belong to DjangoPlay
• which credentials belong to AuthX