Metadata-Version: 2.1
Name: django-lux
Version: 1.8.1
Summary: DjangoLux - A modern UX/UI framework for Django: a themeable, multilingual design system plus batteries-included app infrastructure (auth, CRUD, audit, navigation).
Author-email: DeBeski <debeski1@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/debeski/django-lux
Keywords: django,dlux,permissions,authentication
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5
Classifier: Framework :: Django :: 6
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=5.1
Requires-Dist: django-crispy-forms>=2.4
Requires-Dist: django-tables2>=2.7
Requires-Dist: django-filter>=24.3
Requires-Dist: crispy-bootstrap5>=2025.6
Requires-Dist: psutil>=7.0.0
Requires-Dist: pyotp>=2.9
Requires-Dist: qrcode>=8.2
Requires-Dist: pillow>=11.0
Requires-Dist: babel>=2.1
Requires-Dist: cryptography>=42.0
Requires-Dist: openpyxl>=3.1
Requires-Dist: packaging>=24.0
Provides-Extra: updater
Requires-Dist: pypi-attestations>=0.0.29; extra == "updater"
Provides-Extra: sso
Requires-Dist: django-lux-sso>=0.1.0; extra == "sso"

# DjangoLux — A Modern UX/UI Framework for Django

[![PyPI version](https://img.shields.io/pypi/v/django-lux?color=blue)](https://pypi.org/project/django-lux/)
[![Python versions](https://img.shields.io/pypi/pyversions/django-lux)](https://pypi.org/project/django-lux/)
[![Django versions](https://img.shields.io/badge/Django-5.1%20%7C%206-092E20?logo=django&logoColor=white)](https://www.djangoproject.com/)
[![License](https://img.shields.io/pypi/l/django-lux?color=green)](https://github.com/debeski/django-lux/blob/main/LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/django-lux?color=orange)](https://pypi.org/project/django-lux/)

<p align="center">
  <img src="https://raw.githubusercontent.com/debeski/django-lux/main/dlux/static/img/login_logo.svg" alt="DjangoLux Logo" width="450"/>
</p>

<p align="center">
  <a href="https://chatgpt.com/g/g-6a14ac8cbb0c8191aad3b3619e5bef21-dlux-agent"><strong>Open DjangoLux Agent on ChatGPT</strong></a><br/>
  <sub>Specialized custom GPT for django-lux integration, configuration, extension, and troubleshooting.</sub>
</p>

DjangoLux is an extensive UX/UI framework for Django — a complete, design-first playground for building modern web apps. It ships a polished, themeable design system on top of Bootstrap 5 (multiple built-in themes, full RTL/LTR + multilingual support, custom font management, and theme/language/direction-aware components) and pairs it with the batteries a real application needs: a first-launch setup wizard, user management and security, scopes, navigation, activity logging, guided onboarding, data export, and zero-boilerplate CRUD tooling.

Think of it as a cohesive foundation rather than a themed admin shell — instead of assembling auth, theming, tables, forms, navigation, and auditing yourself, you get them wired together and configurable at runtime, so you can focus on your app's actual features. The package keeps the landing README short; long-form operating and integration guidance lives at [`docs/`](docs/README.md).

## Built with DjangoLux

DjangoLux powers complete products as well as reusable application foundations. These projects show the framework across business workflows, fleet operations, and content-driven applications:

| Project | What it showcases |
|:--|:--|
| [**Switch POS**](https://github.com/debeski/Sales-CRM)<br><sub>Sales CRM · POS · Catalog · Finance</sub> | A centralized sales system covering product catalogs, inventory, hybrid-currency pricing, invoices, finance, and role-controlled sales workflows. It demonstrates DjangoLux as the foundation for a substantial day-to-day business application. |
| [**DLUX Control Plane**](https://github.com/debeski/dlux-panel)<br><sub>Fleet management · Secure operations · Deployment</sub> | A scoped control plane for monitoring and safely operating fleets of DjangoLux Compose deployments through outbound agents. It showcases enrollment, typed operational commands, update orchestration, audit history, and security-focused administration. |
| **dHub**<br><sub>Portfolio · Document archive · Public and scoped content</sub><br>[Container image](https://hub.docker.com/r/debeski/dhub) | A combined public portfolio and scoped document archive. It demonstrates public-facing pages alongside protected document workflows, runtime customization, Caddy deployment, verified updates, and project-level release automation. |

Each project is a working example of DjangoLux conventions applied to a different product shape. Explore the public source and artifacts to see how the shared UI, permissions, scoping, configuration, deployment, and update architecture extend into project-owned features.

## Composer — Deployment and Operations Layer

For generated Compose deployments, [**Composer**](https://github.com/debeski/composer) is DjangoLux's containerized operations companion. It resolves deployment secrets, starts and updates the stack, runs service and Django management commands, waits for health checks, and publishes atomic deployment status and logs without requiring a local Python or Compose toolchain.

The resident `composer-agent` extends that local workflow with registry image discovery, durable operation replay, and an optional outbound-only connection to the DLUX Control Plane. Docker write authority is isolated in a separate, non-network-facing `composer-executor` (the sole holder of the socket); the agent keeps only read-only Docker access through a `POST=0`/`EXEC=0` `docker-socket-proxy`, so a compromise of the network-facing agent can inspect but never mutate. The responsibilities remain deliberately separated:

| DjangoLux | Composer | DLUX Control Plane |
|:--|:--|:--|
| Owns application policy: backups, maintenance, update admission and locking, migration safety, permissions, and final application state. | Owns container execution: secret handoff, registry checks, constrained Compose lifecycle, health verification, deployment status, and durable agent relay. | Owns fleet coordination: enrollment, authorization, typed command routing, batches, audit history, and relayed snapshots. |

DjangoLux decides whether an application operation may proceed; Composer performs the corresponding container work. The agent has no inbound listener, and its remote surface accepts only typed, allowlisted operations—never arbitrary shell access, destructive stack commands, database restarts, or remote backup restoration. Local DjangoLux operations continue when the Control Plane is unavailable.

Generated projects include `start.sh` and `start.ps1` wrappers plus the resident agent:

```bash
./start.sh             # start the production stack
./start.sh -d          # start with the development override
./start.sh update    # pull and safely recreate updated services
```

[Composer source](https://github.com/debeski/composer) · [Docker image](https://hub.docker.com/r/debeski/composer) · [DjangoLux integration guide](docs/inline-updater.md#deployment-architecture)

## What DjangoLux gives you

- A complete, themeable design system on Bootstrap 5: multiple built-in themes with a shared theme registry, full RTL/LTR and multilingual rendering, custom font management, responsive layouts, reusable components (tables, forms, modals, selectors, sidebar, navbar, titlebar global search, tutorials), and theme/language/direction-aware surfaces — all driven by a single `dlux` token vocabulary.
- A 17-step first-launch setup wizard at `/sys/setup/` with category-owned identity, localization, homepage, email, security, login, sidebar, navigation, titlebar, search, notifications, themes/typography, layout, logging, profile, backup, and optional-feature settings.
- A runtime system UI for users and superusers, including Options, user management, profiles, 2FA, activity logs, scopes, and system settings.
- A disabled-by-default public registration playground for email-first local signup with mandatory email verification, Dlux email readiness checks, public-account provenance badges, throttles, and optional approval.
- A database-backed `SystemSettings` singleton layered over `DLUX_CONFIG`, so projects can seed defaults in code and refine them in the UI later.
- A framework-owned `django_tables2` platform that auto-adopts stock tables, ships built-in pagination and per-page controls, exposes a public `DluxTable` base class, and supports per-table `dlux_table`, `dlux_density`, `dlux_per_page`, and `dlux_actions` overrides.
- A `ScopedModel` base with audit fields, soft-delete behavior, actor tracking, filtered managers, and automatic scope handling.
- Zero-boilerplate sections and dynamic modal CRUD flows for auxiliary models, plus a reusable context-menu/event model for richer interactions.
- A built-in audit trail with signal-based logging, merged User/Profile updates, diff capture, masked sensitive fields, and download/export log entries.
- Universal data helpers such as `fetch_file`, `fetch_excel`, sticky-form autofill, tutorial overlays, and persistent UI preferences.

## Requirements

The runtime dependencies below are installed automatically with `django-lux`.

- Python 3.11+
- Django 5.1+
- `django-crispy-forms`
- `crispy-bootstrap5`
- `django-tables2`
- `django-filter`
- `pillow` "for image handling"
- `babel` "for translations"
- `psutil` "for system monitoring"
- `pyotp` "for TOTP 2FA"
- `qrcode` "for TOTP 2FA QR codes"
- `cryptography` "for encrypted TOTP and SMTP secret storage"
- `openpyxl` "for XLSX exports"
- `packaging` "for version and requirement validation"

Generated Compose projects install the optional `django-lux[updater]` extra for
PyPI provenance verification. Manual and non-Compose installs do not need that
extra unless they deliberately adopt the generated updater architecture.

## Installation

```bash
pip install django-lux
# OR
pip install git+https://github.com/debeski/django-lux.git
```

## Scaffold a New Project or App

```bash
python -m dlux startproject myproject --image acme/myproject --repo acme/myproject
cd myproject
python -m dlux startapp billing --register
```

`python -m dlux startproject` creates a new Django project already wired for DjangoLux. `python -m dlux startapp` creates a DjangoLux-native app skeleton with models, forms, filters, tables, translations, templates, tests, and optional project registration.

`startproject` takes two release settings, and on a terminal it **prompts** for them (press Enter to accept the default):

- `--image name[:tag]` — the Docker image the deployment pulls and the generated release workflow pushes (e.g. `acme/myproject:latest`). It is written to `.secrets/.env` as `WEB_IMAGE`, the single value every `compose.yml` reference defers to. It defaults to the bare project name, which exists in no registry — set it, or the updater's image-digest check silently never reports an update.
- `--repo owner/name` — the GitHub repository (a full `https://github.com/owner/name` URL is also accepted), used for the release URL in `release-manifest.json`. Optional; left blank it writes an obvious `OWNER/REPO` placeholder.
- `--no-input` — never prompt; use the flag values or their defaults (for CI/non-interactive use).

Generated projects include a baseline Docker stack — `compose.yml`, `compose.dev.yml`, a `config/celery.py` worker entrypoint, a `/health/` endpoint via `django-health-check`, Composer's outbound-only agent, isolated executor, and read-only Docker proxy with a persistent runtime volume, and a Caddy reverse proxy (nginx fallback) with a maintenance/progress page — plus a tag-driven release pipeline: `release-manifest.json`, a `.github/workflows/release.yml` that builds and pushes `--image` and bakes the version labels, and `tools/validate_project_release_manifest.py`.
They also generate `.secrets/.env` with the bootstrap secrets used by the standard startup flow.
The scaffolded settings baseline now also includes `django-cors-headers` and `django-csp` with their apps, middleware, and starter CORS/CSP policy settings.

Inline updates are enabled only by the recognized generated Compose baseline,
and the development override turns them off again. Other installations keep
`DLUX_INLINE_UPDATES_ENABLED=False` unless they are explicitly migrated with the guarded bootstrap described in the
[Verified Inline Updater guide](docs/inline-updater.md).

## Minimal Quick Start

1. Add the DjangoLux helper at the end of your project `settings.py`.

```python
from dlux.utils import dlux_settings

dlux_settings(globals())
```

That helper prepends the required apps, inserts `django.middleware.locale.LocaleMiddleware` and `dlux.middleware.DluxMiddleware` in the supported order, adds the Dlux context processor, sets the Crispy Bootstrap 5 defaults, adds a Bootstrap-friendly `MESSAGE_TAGS` error mapping, and seeds the standard DjangoLux runtime defaults for language, timezone, i18n/tz flags, `FORMAT_MODULE_PATH`, and charset unless your project already defines them.

__Proceed to [Getting Started](docs/getting-started.md) if you prefer to wire everything manually.__

Public registration is documented separately at [Public Registration Playground](docs/registration.md). It is disabled by default and is not part of the optional SSO packages.


2. Mount `dlux.urls` at project root so the bundled auth and system routes stay at `/accounts/...` and `/sys/...`.

```python
from django.urls import include, path

urlpatterns = [
    path("", include("dlux.urls")),
]
```

With that root include in place, dlux provides `/accounts/...` and `/sys/...`. If your project does not define its own `/` view, dlux falls back from an unresolved `/` request into its login/setup flow instead of leaving a 404. On a fresh and unconfigured install, Dlux also guards ordinary anonymous requests so a public root page cannot bypass first-time setup; once setup is complete, your existing root view continues to behave normally.

3. Run the setup command.

```bash
python manage.py dlux_setup
```

4. Sign in as a superuser and complete the first-launch wizard at `/sys/setup/`. On a fresh install, an anonymous request may be sent through `/sys/setup/` and then to login before the wizard can be completed. After setup, the main runtime UI lives under `user_hub`.

For a fuller setup path, prefix-mount guidance, and first-launch expectations, use the [Getting Started guide](docs/getting-started.md).


## Key Capabilities

- Onboarding and runtime configuration:
  first-launch setup wizard, Options view, runtime System Settings modal, source-tabbed translation overrides, setup import/export, language/theme defaults, and a global Home destination.
- User and security operations:
  interactive user wizard, grouped translated permissions, four-tier staff authorization (superuser, Global Staff, Central Staff, Scoped Staff), permission-based sidebar visibility, profile management, multiple 2FA flows (App, Email, Backup), trusted device tracking for 30 days, and runtime preference persistence.
- Generic CRUD infrastructure:
  dynamic sections, AJAX-driven modal CRUD, automatic form/table/filter discovery, context-menu actions, and reusable event dispatch.
- Navigation and UI infrastructure:
  resolver-driven sidebar builder with permission-based visibility, runtime tree rendering, optional user-level reordering, configurable sidebar toolbar visibility, a shared theme registry, tutorial overlays, theme-aware system surfaces, and template injection hooks.
- Data movement and productivity helpers:
  universal file download, Excel export, smart autofill, sticky-form cloning, and generic list/filter helpers.
- Audit and governance:
  signal-based activity logging with configurable IP resolution (direct/proxy/header), diff capture, masked sensitive fields, deduplicated entries, download/export logging, and scoped visibility.
- Optional SSO:
  `django-lux-sso` and `django-lux-sso-client` live as separate optional packages for OIDC provider/client deployments without changing core Dlux runtime behavior.
- Standalone backup viewer:
  `tools/dlb-viewer/` is a dependency-free, cross-platform binary for inspecting encrypted `.dlb` system backups offline — browse models, rows, and stored files without a running instance. Prebuilt binaries ship with each release.
- Full-system backup policy:
  superusers can configure scheduled encrypted backups, storage-relative export targets, and age/count rotation from System Settings; inline updates and rollbacks require a verified pre-maintenance backup.
- Framework-level automation:
  translation patches, scoped-model auto-injection, actor tracking, soft-delete, and config layering across defaults, project settings, and runtime UI.
- Verified generated-Compose updates:
  daily stable-release checks, superuser-approved staged updates, maintenance/backup handling, process generation restarts, and compatible code/static rollback without rebuilding the project image.

## Documentation

- [Documentation Hub](docs/README.md)
- [Security Policy](SECURITY.md)
- [Contributing Guide](CONTRIBUTING.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Getting Started](docs/getting-started.md)
- [Admin Guide](docs/admin-guide.md)
- [Developer Guide](docs/developer-guide.md)
- [Customization Guide](docs/customization-guide.md)
- [Reference](docs/reference.md)
- [DSRP-1 Security Standard](docs/security-dsrp-1.md)
- [Optional SSO Packages](docs/sso.md)
- [Standalone .dlb Backup Viewer](tools/dlb-viewer/README.md)
- [Verified Inline Updater](docs/inline-updater.md)
- [Releasing](docs/RELEASING.md) — tag-driven PyPI + GitHub release flow
- [Migrating from django-microsys](docs/migrating-from-microsys.md) — in-place upgrade for existing deployments
- [Features](docs/FEATURES.md) — complete feature inventory
- [Changelog](CHANGELOG.md)
