DjangoPlay Web

• Maintained by:

• Website:: https://djangoplay.org
• Application:: https://app.djangoplay.org
• Documentation:: https://docs.djangoplay.org
• Email: contact@djangoplay.org

It is intentionally structured to support long-lived systems, regulatory requirements, and complex organizational workflows.

#Table of Contents

• 1. Release Status

  • 1.1 Versioning Strategy

  • 1.2 Core Design Principles

• 2. DjangoPlay Architecture

  • 2.1 High-Level Architecture

• 3. Local Development

  • 3.1 System Requirements

• 4. Automated Installer (Recommended — Fresh Installs Only)

• 5. DjangoPlay Configuration

  • 5.1 Clone the repository

  • 5.2 Create a virtual environment

  • 5.3 Install dependencies

  • 5.4 Create the PostgreSQL database

  • 5.5 Generate an encryption key

  • 5.6 Create Environment Files

    • 5.6.1 DjangoPlay Environment Configuration References

    • 5.6.2 CDN Configuration

  • 5.7 Run database migrations

  • 5.8 Create the superuser

  • 5.9 Install djangoplay-cli

  • 5.10 Start the development server

• 6. Run application

• 7. DjangoPlay AI Assistant

• 8. DjangoPlay Application commands

  • 8.1 Serving the Website & Docs subdomains locally

• 9. System Documentation

• 10. App-Level Documentation

• 11. Contributing

• 12. License

#1. Release Status

Current Version: 1.2.2

Status: Production Deployed

DjangoPlay is a modular Django/DRF backend platform covering identity & permissions, finance (invoicing, credit notes, payments, tax profiles), CRM-style business entities, helpdesk/issue-tracker integration, a platform-wide audit trail, and an in-app, provider-agnostic AI assistant (aicore). The platform is intended for internal organizational systems and enterprise backend services where identity, auditability, and permission governance are critical, as well as for learning and building workflow platforms.

#1.1 Versioning Strategy

DjangoPlay follows Semantic Versioning.

#1.2 Core Design Principles

• Explicit Domain Ownership — each app owns its data, logic, permissions, and lifecycle
• Identity as a Protected Boundary — identity logic is isolated and cannot be bypassed
• Service-First Architecture — business logic lives in services, not views or serializers
• Auditability by Default — every meaningful state change is observable and attributable
• Fail-Closed Security — missing permission checks are treated as errors

#2. DjangoPlay Architecture

#2.1 High-Level Architecture

flowchart TD

    CLIENTS["<b>Clients</b><br/>Web Browser • REST API • SSO"]

    subgraph DJANGO["<b>DjangoPlay</b><br/><small>Modular Django / DRF Platform</small>"]
        WEB["Django Web UI"]
        API["DRF APIs"]
        APPS["Domain Apps<br/><small>Services • Policies • Background Jobs</small>"]
    end

    AUTHX["<b>AuthX</b><br/>Identity • Authentication • SSO"]

    subgraph INFRA["<b>Core Infrastructure</b>"]
        DB["PostgreSQL<br/><small>Application Data</small>"]
        REDIS["Redis<br/><small>Cache / Celery Broker</small>"]
        CELERY["Celery<br/><small>Background Workers</small>"]
    end

    subgraph EXT["<b>External Services</b>"]
        EMAIL["Email / SMTP"]
        R2["Cloudflare R2 / CDN"]
        AI["AI Providers"]
        APIs["External APIs"]
    end

    CLIENTS --> WEB
    CLIENTS --> API

    WEB --> APPS
    API --> APPS

    APPS --> AUTHX
    APPS --> DB
    APPS --> REDIS
    REDIS --> CELERY
    CELERY --> EXT

    APPS --> EMAIL
    APPS --> R2
    APPS --> AI
    APPS --> APIs

    classDef client fill:#f5f3ed,stroke:#777,stroke-width:2px,color:#444
    classDef django fill:#e6f1fb,stroke:#2474b5,stroke-width:2px,color:#174d7a
    classDef auth fill:#f3eafa,stroke:#7b4bb7,stroke-width:2px,color:#542d82
    classDef infra fill:#e5f6f1,stroke:#159a7a,stroke-width:2px,color:#075d4b
    classDef external fill:#fceee8,stroke:#d65a2a,stroke-width:2px,color:#7d321c

    class CLIENTS client
    class DJANGO,WEB,API,APPS django
    class AUTHX auth
    class INFRA,DB,REDIS,CELERY infra
    class EXT,EMAIL,R2,AI,APIs external

Architecture details: DjangoPlay follows a modular monolith architecture with domain-oriented Django apps, service-layer business logic, centralized authorization, background processing, and dedicated integration boundaries.

For more details:DjangoPlay Architecture.

#3. Local Development

DjangoPlay uses djangoplay-cli to manage the local development environment. Once the prerequisites below are complete, the entire startup sequence — environment encryption, Redis, static files, SSL certificates, Celery, and server — runs in a single command.

Note: DjangoPlay itself is a web application, not a PyPI library. The badges at the top of this README point to the standalone PyPI packages it depends on/ships alongside — djangoplay-cli for local dev orchestration, authx-identity for OIDC identity, and genericissuetracker for the issue-tracker integration.

#3.1 System Requirements

macOS (Homebrew):

brew install postgresql redis openssl pyenv
brew services start postgresql
brew services start redis
brew install rclone

Ubuntu / Debian:

sudo apt install python3.11 postgresql redis-server openssl
sudo systemctl start postgresql redis
sudo apt install rclone

#4. Automated Installer (Recommended — Fresh Installs Only)

For a brand-new machine with no existing DjangoPlay database or checkout — the installer drops and recreates the database from scratch. If you already have an existing DB/checkout you want to keep, use DjangoPlay Configuration below instead.

Prerequisite — that's it, nothing else needs to be done by hand first:

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

• This config will create files: ~/.dplay/.secrets, ~/.dplay/.authx, ~/.dplay/config.yaml, and ~/.dplay/.appdata.
• Update all with relevant values.

Once that's done, run the installer for your platform:

🍎 macOS

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

🐧 Ubuntu

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

🪟 Windows

Run the following command in PowerShell:

irm https://install.djangoplay.org/windows | iex

The script reads DB name/user from ~/.dplay/config.yaml, clones djangoplay-web (via SSH if ~/.ssh/config has a gitlab.com entry, falling back to the public GitHub mirror otherwise — safe for contributors without GitLab write access), creates a virtualenv, installs dependencies, creates the PostgreSQL database, runs migrations, then clones and sets up AuthX Identity the same way (its own DB, venv, and Alembic migrations) before creating the Django superuser.

Full output is logged to setup.log in the cloned project root.

• Please note, to run djangoplay-website and djangoplay-documentation websites locally, you would need write access to repositories. You can reach out to contact@djangoplay.org.

Prefer full manual, step-by-step control instead? Continue with DjangoPlay Configuration below.

#5. DjangoPlay Configuration

#5.1 Clone the repository

git clone https://gitlab.com/djangoplay/djangoplay-web.git
cd djangoplay-web

#5.2 Create a virtual environment

python3.11 -m venv .venv
source .venv/bin/activate

#5.3 Install dependencies

pip install -e ".[dev]"

#5.4 Create the PostgreSQL database

Run the following in psql:

CREATE USER db_user WITH PASSWORD 'db_password';
CREATE DATABASE db_name OWNER db_user;
GRANT ALL PRIVILEGES ON DATABASE db_name TO db_user;
CREATE EXTENSION IF NOT EXISTS pg_trgm;

#5.5 Generate an encryption key

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Copy the output — you will use it as ENCRYPTION_KEY in the next step.

#5.6 Create Environment Files

DjangoPlay uses four environment/configuration files under ~/.dplay/:

Create the configuration files using the public DjangoPlay configuration installer:

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

The installer creates the ~/.dplay/ configuration structure and does not overwrite existing configuration files.

To intentionally overwrite existing configuration files:

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

Security: Configuration files containing passwords, API keys, service credentials, or private keys must never be committed to source control or exposed publicly.

5.6.1 DjangoPlay Environment Configuration References

• The complete configuration reference is provided here.
• It is the authoritative reference for individual configuration keys, including their values, examples, requirement classification, consuming service/tooling, and feature-specific usage.

The configuration reference distinguishes between:

• Setup — Required
• Runtime — Required
• Setup + Runtime — Required
• Runtime — Optional
• Tooling — Optional

This distinction is important because a value needed during initial setup is not necessarily required by the running application, and optional integrations should not require credentials that are unrelated to the features being used.

For example, optional integrations such as Google OAuth, Cloudflare Turnstile, AbuseIPDB, Cloudflare R2, and AI providers only need their corresponding credentials when those integrations are enabled or used.

AuthX is part of the DjangoPlay identity architecture. When AuthX is enabled, ~/.dplay/.authx must contain the configuration required by the AuthX service. AuthX provides the identity authority for authentication flows such as login, signup, password reset, and SSO. The configuration reference documents the AuthX requirements separately from DjangoPlay's own environment configuration.

5.6.2 CDN Configuration

Only needed if you're testing the CDN path locally or deploying. Local dev works without this — CDN_ENABLED is forced off in dev.py, and {% cdn_static %} falls back to serving dist//assets//vendor/ the normal way via runserver.

• (Optional) Push frontend assets to Cloudflare R2

bash frontend/packaging/minify.sh r2

This builds as usual, then pushes dist/, assets/, vendor/ (and generated/, if present) to the R2 bucket configured in config.yaml under a version-tagged prefix (dist/<asset_version>/...).

#5.7 Run database migrations

cd webapp
python manage.py migrate

#5.8 Create the superuser

python manage.py create_superuser

Credentials are read automatically from ~/.dplay/.secrets. The superuser is created with a verified email address and the DJGO role. If the superuser already exists the command exits safely without error.

#5.9 Install djangoplay-cli

pip install djangoplay-cli

#5.10 Start the development server

HTTPS (recommended):

bash webapp/frontend/packaging/minify.sh
dplay ssl

HTTP:

bash webapp/frontend/packaging/minify.sh
dplay http

Running dplay without a subcommand defaults to HTTP.

On first run with dplay ssl, sign in at https://app.lvh.me:9999/accounts/login/

#6. Run application

After configuring DjangoPlay successfully, run below command to start application:

bash webapp/frontend/packaging/minify.sh
dplay ssl

#7. DjangoPlay AI Assistant

DjangoPlay includes a multi-provider, streaming chat assistant for authenticated users — business logic stays in services, API keys stay server-side (or never touch the server at all, for BYOK), and the LLM backend is swappable per-session, not just per-deployment.

Highlights: a free-model picker sourced live from OpenRouter's catalog, bring-your-own-key for both local dev (two switchable profiles) and production (session/tab-scoped, key never persisted), an admin usage dashboard, and usage guardrails (per-tab throttling, per-provider-tier token budgets) that scale with the added flexibility.

For fully local — no per-token bill unless you point AI_PROVIDER at a paid cloud API, or a user opts into the free OpenRouter catalog / brings their own key from the chat widget.

Full documentation — architecture, request flow, every setting, the BYOK security model, rate-limit/token-budget design, and the usage dashboard — lives in the docs repo, not here:

#8. DjangoPlay Application commands

bash frontend/packaging/minify.sh   # Build DjangoPlay frontend
dplay ssl                           # Start DjangoPlay with SSL mode
dplay http                          # Start DjangoPlay with http mode
dplay worker                        # Celery worker jobs
dplay system doctor                 # check environment health
dplay system reset                  # stop Celery, flush Redis
ruff check .                        # lint

#8.1 Serving the Website & Docs subdomains locally

app.lvh.me/issues.lvh.me are served by dplay ssl, but site.lvh.me and docs.lvh.me are static and served separately — they aren't part of the Django process. Use the bundled serve_static.py wrapper (not python -m http.server, which has no TLS support pre-3.14) so both subdomains resolve over https:// to match the app:

python /scripts/cert/serve_static.py "$(yq '.repository.site_root' ~/.dplay/config.yaml)" 4001 --ssl
python /scripts/cert/serve_static.py "$(yq '.repository.docs_root' ~/.dplay/config.yaml)" 4002 --ssl

Run these in separate terminals alongside dplay ssl, before opening the footer's Website / Product Docs links.

#9. System Documentation

You can find all documentations at: https://docs.djangoplay.org/projects/djangoplay-web/

Technical reference for the DjangoPlay platform.

#10. App-Level Documentation

Deep-dive reference for each Django app — architecture, functionality, data models, cross-app integration points, and known gaps. Generated for engineering onboarding and AI-assisted development.

Complete app documentation:: DjangoPlay Apps Documentation

#11. Contributing

For contributor guidelines and architectural invariants see governance/CONTRIBUTING.md in the repository.

#12. License

DjangoPlay is licensed under the Apache License, Version 2.0.

You are free to use, modify, distribute, and sublicense DjangoPlay subject to the terms and conditions of the Apache License, Version 2.0.

When redistributing DjangoPlay or derivative works, the applicable copyright, attribution, and license notices must be preserved as required by the Apache License, Version 2.0.

The DjangoPlay name, logo, and branding are not licensed under the Apache License, Version 2.0. Use of DjangoPlay branding does not imply endorsement of modified or derivative works.

See LICENSE for the complete license terms and NOTICE for DjangoPlay attribution and branding notices.