Metadata-Version: 2.4
Name: django-whiteneuron
Version: 0.4.1.0
Summary: A modern Django Admin extension with enhanced UI/UX, dashboard, feedback, file management, rate limiting, IP blacklisting, and advanced admin integrations built on django-unfold.
Author-email: White Neuron <anhnt@whiteneuron.ai>
License: MIT License
        
        Copyright (c) 2025 Nguyễn Tú Anh
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: homepage, https://whiteneuron.ai
Project-URL: repository, https://github.com/White-Neuron/django-whiteneuron
Project-URL: changelog, https://github.com/White-Neuron/django-whiteneuron/releases
Project-URL: Bug Tracker, https://github.com/White-Neuron/django-whiteneuron/issues
Project-URL: PyPI, https://pypi.org/project/django-whiteneuron/
Keywords: django,plugin,admin,dashboard,whiteneuron
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Framework :: Django
Classifier: Framework :: Django :: 6.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: django-debug-toolbar>=5.0.1
Requires-Dist: django<7.0.0,>=6.0.9
Requires-Dist: django-celery-beat>=2.7.0
Requires-Dist: django-guardian>=2.4.0
Requires-Dist: django-imagekit>=5.0.0
Requires-Dist: django-import-export>=4.3.3
Requires-Dist: django-modeltranslation>=0.19.11
Requires-Dist: django-ninja>=1.3.0
Requires-Dist: django-simple-history>=3.8.0
Requires-Dist: gunicorn>=23.0.0
Requires-Dist: hiredis>=3.1.0
Requires-Dist: markdown>=3.7
Requires-Dist: openai>=1.58.1
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: pandas>=2.2.3
Requires-Dist: pillow>=12.2.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: redis>=5.2.1
Requires-Dist: sentry-sdk==2.28.0
Requires-Dist: django-browser-reload>=1.18.0
Requires-Dist: whitenoise>=6.9.0
Requires-Dist: django-crispy-forms>=2.4
Requires-Dist: django-colorfield>=0.14.0
Requires-Dist: channels>=4.2.2
Requires-Dist: channels-redis>=4.2.1
Requires-Dist: uvicorn>=0.34.3
Requires-Dist: daphne>=4.2.0
Requires-Dist: twisted[tls]>=26.4.0rc2
Requires-Dist: django-ckeditor-5>=0.2.18
Requires-Dist: django-cors-headers>=4.3.0
Requires-Dist: django-unfold<0.111,>=0.109.0
Requires-Dist: djangoql>=0.18.1
Requires-Dist: pyopenssl>=26.4.0
Requires-Dist: md2html-tailwind4==1.5.3
Requires-Dist: psutil>=7.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Dynamic: license-file

# django-whiteneuron

A modern Django Admin extension focused on UI/UX, dashboard, feedback, file management, and advanced admin integrations — built on top of [django-unfold](https://github.com/unfoldadmin/django-unfold).

[![PyPI version](https://img.shields.io/pypi/v/django-whiteneuron)](https://pypi.org/project/django-whiteneuron/)
[![Python](https://img.shields.io/pypi/pyversions/django-whiteneuron)](https://pypi.org/project/django-whiteneuron/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/django-whiteneuron)](https://pypi.org/project/django-whiteneuron/)

![django-whiteneuron](https://raw.githubusercontent.com/White-Neuron/django-whiteneuron/main2.0/docs/images/main.png)

## Current Version
v0.4.1.0

## Changelog

### Latest: v0.4.1.0 (2026-10-16)
**Feature release: admin About page (application / base versions and release dates)**
- **Added**: admin **About** page (`/admin/about/`, sidebar *System → About*, URL name `admin:about`). Every staff user sees the application name, version, release date and short build id (`VERSION`, `RELEASE_DATE`, `BUILD_ID` / `GIT_COMMIT`, cut to 12 characters) and the django-whiteneuron version and release date with a changelog link; superusers also see Python/Django/Unfold versions, database engine, debug mode, time zone, server time, process start and uptime.
- **Added**: `APP_INFO_CALLBACK` setting (`"path.to.func"`, `func(request) -> [(label, value), ...]`) for project rows on the About page; a failing callback is logged and skipped.
- **Added**: `whiteneuron.__version__` and `whiteneuron.__release_date__`; a test keeps them in sync with `pyproject.toml` and this changelog.
- **Security**: the About page never shows host name, OS/kernel, IP addresses, paths, database server version, connection settings or a dependency list (fingerprinting / CVE lookup); runtime details are superuser-only.
- **Upgrade**: `pip install -U django-whiteneuron==0.4.1.0`, `collectstatic`. No migrations. Optional settings: `RELEASE_DATE`, `BUILD_ID`, `APP_INFO_CALLBACK`. Projects that define their own `UNFOLD["SIDEBAR"]` add the link themselves (`reverse_lazy("admin:about")`). Docker base images `v0.4.1.0` are published by the release workflow.

### v0.4.0.2 (2026-10-15)
**Patch release: dependency security updates in the locked set (and the Docker base images)**
- **Security (dependencies)**: locked django 6.0.9, gunicorn 26.2.0, cryptography 50.0.2, hiredis 3.4.2, msgpack 1.2.3, Markdown 3.11.1 and ujson 6.0.0 (all patched releases). The Docker base images install exactly this lock, so projects building `FROM django-whiteneuron-*:v0.4.0.2` no longer need to pin these packages above the base. `django>=6.0.9` is now the minimum.
- **Upgrade**: `pip install -U django-whiteneuron==0.4.0.2`. No code, template or migration changes. Docker base images `v0.4.0.2` are published by the release workflow.

### v0.4.0.1 (2026-10-14)
**Patch release: Vietnamese translations lost in 0.4.0.0, daisyUI modals under Unfold, announcement endpoint**
- **Fixed**: translations that 0.4.0.0 dropped from the Vietnamese catalog. Strings translated with `_()` *inside f-strings* are invisible to `makemessages`, so regenerating the catalog for 0.4.0.0 marked them obsolete and left them out of `django.mo`, so 0.4.0.0 showed them in English: user badges (Inactive / Admin / Bot), every "… has been updated by user …" notification, M2M change notes (added / removed) and the dashboard KPI cards ("progress from last", "in"). The `_()` calls are moved out of the f-strings and the translations restored.
- **Fixed**: dashboard KPI cards are whole translatable sentences (`%(object)s in %(period)s`, `%(count)s successful (%(rate)s%%)`); "day" and "successful" were hard-coded English; no change now shows as a green +0 instead of a red -0; the color classes are literal so Tailwind compiles them.
- **Fixed**: notification bodies ("… has been updated by user … with the following changes") were hard-coded English.
- **Fixed**: an open daisyUI `ui-modal` (announcement, feedback resolve, markdown preview) rendered as a narrow white column without overlay: Unfold's unlayered `dialog { … }` rule beats daisyUI's layered `.ui-modal`. `dialog.ui-modal` now restores the full-screen modal.
- **Fixed**: `/announcement/` returned a 500 when the project-provided `ANNOUNCEMENT_CONTENT_HTML_FILE` template is missing or the setting is empty; it now returns empty content and logs a warning.
- **Tests**: no `_()` inside f-strings; every literal msgid in the package's Python code must be in the compiled Vietnamese catalog (catches strings dropped by `makemessages`); dashboard KPI translated; `dialog.ui-modal` override present; announcement endpoint without a template.
- **Upgrade**: `pip install -U django-whiteneuron==0.4.0.1`, `collectstatic`. No migrations. Docker base images `v0.4.0.1` are published by the release workflow.

### v0.4.0.0 (2026-10-13)
**Feature release: daisyUI multi-theme admin, server monitoring dashboard, django-unfold 0.109, security hardening and performance work**
- **Added**: 35 daisyUI themes selectable from the user menu (**Themes**); each theme also re-colors Unfold and drives its dark mode. `WN_ADMIN_THEMES` limits the picker (`[]` hides it); `WN_THEMES="nord,dracula" bash scripts/tailwind.sh` builds a smaller CSS bundle.
- **Added**: `whiteneuron.monitoring` — Grafana-style **Server monitoring** dashboard (CPU, memory, disk, load, network, disk I/O, request throughput, p50/p95/p99 latency, error rate, Apdex, slowest endpoints, DB/cache latency) with time ranges, auto-refresh, host selector and shared crosshair. Collect with `manage.py monitoring_collector` or the Celery task `whiteneuron.monitoring.tasks.collect_metrics`; configure with `WN_MONITORING`. New dependency: `psutil`.
- **Added**: Docker base images `django-whiteneuron-{alpine,debian}:v<version>` built from this repository (`docker/`, moved from WN-Sense); `.github/workflows/docker-base.yml` builds and pushes them on every GitHub Release (secrets `DOCKERHUB_USERNAME` / `DOCKERHUB_TOKEN`).
- **Changed**: `django-unfold>=0.109.0,<0.111` (the cap is raised after each Unfold release is re-tested against the template overrides); template overrides ported; uses the avatar badge (unread notifications), sidebar sub-navigation (Celery "Schedules"), `SITE_VERSION`, theme-aware dashboard charts.
- **Security**: escaped notification/grid HTML (stored XSS), whitelisted `?display_fields` (a GET could call `obj.delete()`) and limited the column picker to fields shown on the change form (never `password`; extra exclusions via `ModelAdmin.field_selection_exclude`), staff-only per-user notification WebSocket with origin check, sandboxed uploaded-HTML preview, private exports scoped to the selected rows, `X-Forwarded-For` read from the right (`TRUSTED_PROXY_COUNT`, `IGNORE_X_FORWARDED_FOR`), open-redirect fix in guest login, new-user signal no longer overwrites passwords, `secrets`-based passwords redacted after sending (never passed to the task broker), POST-only feedback resolve, notification IDOR fix.
- **Security (dependencies)**: locked anyio 4.15.1, urllib3 2.8.0, autobahn 26.7.1, soupsieve 2.10, tablib 3.10.0 (stored XSS in HTML export) and virtualenv 21.14.5 (dev) to patched versions; Tailwind build tooling patched (`npm audit fix`) and the unused `@tailwindcss/typography` removed. `pip-audit` and `npm audit` report no known vulnerabilities.
- **Performance**: activity logging 1 INSERT per request (was 3–4 queries), dashboard 4 queries (was ~16) + 60s cache, one `bulk_create` + one broadcast per notification, new indexes, atomic rate-limit counters, request-scoped admin state (grid view / page size no longer shared between users), thumbnails built at upload (regenerated if the file is missing), N+1 fixes, 14KB logo instead of 187KB.
- **Fixed**: dashboard date ranges overlapped by a day, `App.__str__` crash on create, export action signature, `readonly_fields` growing per request, header horizontal overflow on phones, `_(f"…")` strings that could never be translated, Chart.js crash on oklch theme colors, notification WebSocket reconnect loops, monitoring collector stopping when the cache is down, missing site branding (sidebar logo/title) on the monitoring dashboard and admin index, flash messages shown twice on the admin index, changelist toolbar (filter / grid / page-size) hidden for admins without `search_fields`, "Next" enabled on the last page and Previous/Next stuck disabled when Django ignores `?all`, unreadable monitoring colors under several themes, markdown preview styles (md2html_tailwind4 classes were never compiled); Vietnamese translations updated.
- **Compatibility**: `ModelAdmin.request` still works (now request-scoped, not stored on the shared instance); the *Server monitoring* sidebar link follows the `monitoring.view_metricsample` permission; in the default light/dark modes daisyUI components take their base/primary colors from `UNFOLD["COLORS"]`.
- **Validation**: 42 package tests pass (`manage.py test whiteneuron`, also under the package's own settings via `whiteneuron.base.testing.package_test_settings`, and from a clean wheel install with django-unfold 0.110.0), `check` clean, `makemigrations` reports no changes, no untranslated Vietnamese strings, Tailwind build and `uv build` succeed; 101 admin URLs swept in a README-style project; changelists, add/change forms, the monitoring dashboard under all 35 themes and the theme picker checked in Chromium (desktop + mobile).
- **Breaking / behavior changes**:
  - `SECRET_KEY` is required when `DEBUG=False` (build commands such as `collectstatic` are exempt).
  - `WN_ASYNC_TASKS` (Celery for email, export, GPT translation) is opt-in; without it these run inline.
  - Client IP: auto mode uses the right-most public `X-Forwarded-For` hop — set `TRUSTED_PROXY_COUNT`, or `IGNORE_X_FORWARDED_FOR=True` when the app is not behind a proxy.
  - Whole-page cache middleware only with `USE_CACHE_MIDDLEWARE=True`; `EXTENSIONS.modeltranslation` and `compressed_fields` removed (dropped by Unfold); new notifications store plain-text titles and JSON `changed_data`.
  - Project overrides of `unfold/helpers/navigation_user.html` should be compared with Unfold 0.109.
- **Upgrade Guidance**: `pip install --upgrade django-whiteneuron`, add `"whiteneuron.monitoring"` to `INSTALLED_APPS`, run `migrate` (indexes + monitoring table), `compilemessages`, and start `monitoring_collector` on each host.
- **Rollback**: revert to v0.3.8.0 after `migrate monitoring zero`, `migrate base 0027` and `migrate notification 0012` (index-only migrations; no data loss).

See [CHANGELOG.md](CHANGELOG.md) for the full version history.

### Latest: v0.3.8.0 (2026-09-25)
**Bugfixes: Django 6 format_html crash in Image previews, app mosaic thumbnail URLs, SHOW_FILE_MANAGEMENT sidebar flag**
- **Fixed**: `Image.imgThumbnail()` and `Image.imgPreview()` admin methods — replaced f-string interpolation inside `format_html()` with the proper template + args pattern; resolves the rendering crash on Django 6 and ensures interpolated values are HTML-escaped.
- **Fixed**: App changelist mosaic thumbnails (`templates/admin/base/app_change_list.html`) — relative `thumbnail_url` paths are now wrapped in `{% static %}` while absolute/protocol-relative URLs pass through unchanged, fixing broken thumbnail images.
- **Fixed**: `SHOW_FILE_MANAGEMENT=False` is no longer silently ignored — the Unfold sidebar is built conditionally at definition time instead of post-processing by title match; when disabled, File Management items merge into the System section before Notifications config.
- **Compatibility**: No breaking changes; safe for all v0.3.x users. Django 6.0.x only.

See [CHANGELOG.md](CHANGELOG.md) for the full version history.

### Latest: v0.3.7.0 (2026-08-23)
**Security: Patch 6 CVEs across django, cryptography, sqlparse, setuptools**
- **Fixed**: Upgraded `django` lower bound to patch CVE-2026-15830 (GeoDjango DoS).
- **Fixed**: Upgraded `pyopenssl` to `>=26.4.0` — patches CVE-2026-69247 (Bleichenbacher oracle attack).
- **Fixed**: Added `sqlparse >=0.6.0` via transitive deps — patches 3 DoS CVEs (CVE-2026-71491, CVE-2026-54284, CVE-2026-59893).
- **Fixed**: Added `setuptools >=75.1.0` to build-system — patches CVE-2025-47273.
- **Compatibility**: No breaking changes; safe for all v0.3.x users. Django 6.0.x only.

### Latest: v0.3.5 (2026-07-15)
**Feature: Public/private file access control and HTML file support**
- **Added**: `is_public`, `allowed_users`, `allowed_groups` fields to `BaseFile` model — files can now be marked public or restricted to specific users/groups.
- **Added**: `_check_access()` permission logic in download/preview views — enforces access control before serving files.
- **Added**: `HTMLFile` model with inline preview support.
- **Improved**: Admin UI — public/private badge column, conditional Access Control fieldset for private files.
- **Compatibility**: No breaking changes; safe for all v0.3.x users.

See [CHANGELOG.md](CHANGELOG.md) for the full version history.

### Latest: v0.3.4.12 (2026-06-27)
**Cleanup: Remove .DS_Store from tracking, feedback list in admin, remove md2html-tailwind4 uv source**
- **Removed**: 7 `.DS_Store` files removed from git tracking — added `*/.DS_Store` to `.gitignore`.
- **Added**: `FeedbackBaseAdmin.render_change_form()` loads and passes `feedback_list` context for displaying feedback entries per model instance in admin change form.
- **Removed**: `[tool.uv.sources]` block for `md2html-tailwind4` from `pyproject.toml`.
- **Updated**: Tailwind CSS regenerated with v4.1.16.
- **Compatibility**: No breaking changes; safe for all v0.3.x users.

See [CHANGELOG.md](CHANGELOG.md) for the full version history.

### Latest: v0.3.4.10 (2026-06-12)
**Security patch: Upgrade Django to 6.0.6+ (CVE-2026-8404, CVE-2026-48587, CVE-2026-6873)**
- **Fixed**: Upgraded `django` lower bound from `>=6.0.6` to `>=6.0.6,<7.0.0` — patches 5 security vulnerabilities: CVE-2026-8404 (CVSS 5.3), CVE-2026-48587 (CVSS 5.3), CVE-2026-6873 (CVSS 4.3), CVE-2026-7666 (CVSS 2.3), CVE-2026-35193 (CVSS 2.3).
- **Compatibility**: No breaking changes; safe for all v0.3.x users. Django 6.0.x only — pinned upper bound `<7.0.0`.

See [CHANGELOG.md](CHANGELOG.md) for the full version history.

### Latest: v0.3.4.8 (2026-05-24)
**Feature: Badge callback caching layer for dashboard performance optimization**
- **Added**: Django cache-backed badge callbacks for dashboard model badges with 60s TTL to reduce database queries.
- **Added**: Per-user cached notification badge with 60s TTL and unauthenticated user guard.
- **Improved**: Replaced `timezone.now()` with `timezone.localtime()` across all badge queries.
- **Compatibility**: No breaking changes; safe for all v0.3.x users. Requires Django cache backend configured.

See [CHANGELOG.md](CHANGELOG.md) for the full version history.

### Latest: v0.3.4.6.2 (2026-05-14)
**Improvement: Configurable rate-limit exempt paths and user activity exclude paths**
- **Improved**: `RateLimitMiddleware` now reads `RATE_LIMIT_EXEMPT_PATHS` from Django settings — comma-separated list of additional path prefixes to exclude from rate limiting.
- **Improved**: `UserActivityMiddleware` now reads `USER_ACTIVITY_EXCLUDE_PATHS` from Django settings — semicolon-separated list of `path,condition` pairs for excluding paths from activity tracking and rate limiting.
- **Compatibility**: No breaking changes; safe for all v0.3.x users. New settings are optional.

See [CHANGELOG.md](CHANGELOG.md) for the full version history.

### Latest: v0.3.3.4 (2026-04-30)
**Patch release: Remove synchronization module, add language switcher template, update Vietnamese i18n**
- **Removed**: `synchronization/` module — cleaned up unused sync models, admin, views, tests, and migrations
- **Added**: Language switcher template for Unfold admin (`language_switch.html`) with multi-language support via `show_languages` context variable
- **Improved**: Vietnamese translations updated — removed stale synchronization references, added new entries for user profile and HTML editor
- **Compatibility**: No breaking changes; safe for all v0.3.3.x users
- **Validation**: Build, migrations (no changes), and manual admin UI/UX validation performed
- **Upgrade Guidance**: No manual migration required; upgrade recommended for all users on v0.3.3.x
- **Rollback**: Safe to revert to v0.3.3.3; no schema changes introduced

See [CHANGELOG.md](CHANGELOG.md) for the full version history.

## Table of Contents

- [Changelog](#changelog)
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Modules](#modules)
- [Middleware & Security](#middleware--security)
- [Frontend](#frontend)
- [Environment Variables](#environment-variables)
- [Management Commands](#management-commands)
- [Building & Releasing](#building--releasing)
- [Documentation](#documentation)
- [Contact](#contact)

## Giới thiệu

Xem [docs/INTRODUCTION.md](docs/INTRODUCTION.md) để tìm hiểu chi tiết về django-whiteneuron — tại sao nên dùng, tính năng nổi bật và ai phù hợp.

## Features

| Category | Feature | Description |
|---|---|---|
| **Core** | Custom User Model | UUID-based user model with bot support, avatar, biography |
| **Core** | Soft Delete System | `BaseModel` with soft delete, restore, and audit trail (`created_by`, `updated_by`) |
| **Core** | Auto Notifications | Real-time WebSocket notifications on CRUD operations via `BaseModel.save()` |
| **Dashboard** | Admin Dashboard | Custom dashboard callback with badge system, cache-backed for performance |
| **Security** | Rate Limiting | IP-based and user-based rate limiting with Redis backend (429 responses) |
| **Security** | IP Blacklist | Static (`.env` CIDR) + dynamic (admin-managed, Redis TTL) blocking |
| **Security** | UA Blacklist | User-Agent substring/regex matching via admin panel or `.env` |
| **Tracking** | Activity Logs | `UserActivity`, `AnonymousActivity`, `VisitProfile` — full request audit trail |
| **Files** | File Management | Excel/PDF upload with SHA-256 integrity verification |
| **Feedback** | Feedback System | Per-model feedback collection, viewable in admin change forms |
| **Admin** | Grid View | Card-based user listing with avatar, badges, and role indicators |
| **Admin** | Import/Export | `django-import-export` integration for data portability |
| **Admin** | Simple History | `django-simple-history` tracking on all models |
| **Admin** | Guardian Integration | Object-level permissions via `django-guardian` |
| **Editor** | CKEditor 5 | Rich text editing with Tailwind-styled output |
| **Email** | Login Notifications | Auto-generate password + send login email on user creation |

## Installation

### From PyPI (recommended)

```bash
pip install django-whiteneuron
```

Or with [uv](https://github.com/astral-sh/uv):

```bash
uv add django-whiteneuron
```

### Specific version from PyPI

```bash
uv add "django-whiteneuron==0.3.4.12"
```

### From GitHub tag

```bash
uv add "git+https://github.com/White-Neuron/django-whiteneuron.git@v0.3.4.12"
```

### From local source

```bash
uv pip install -e .
```

## Quick Start

```bash
# 1. Add to INSTALLED_APPS (top of list)
# settings.py
INSTALLED_APPS = [
    "whiteneuron",
    "whiteneuron.base",
    "whiteneuron.feedbacks",
    "whiteneuron.file_management",
    "whiteneuron.contrib",
    "whiteneuron.dashboard",
    # ... your other apps
]

# 2. Set custom user model
AUTH_USER_MODEL = "base.User"

# 3. Add middleware (order matters)
MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "whiteneuron.base.middleware.RateLimitMiddleware",   # ← immediately after SecurityMiddleware
    "whitenoise.middleware.WhiteNoiseMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.middleware.common.CommonMiddleware",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    "django.middleware.clickjacking.XFrameOptionsMiddleware",
    "whiteneuron.base.middleware.ReadonlyExceptionHandlerMiddleware",
    "whiteneuron.base.middleware.UserActivityMiddleware",  # ← after AuthenticationMiddleware
    "whiteneuron.base.middleware.ThreadLocalMiddleware",
]

# 4. Run migrations
python manage.py migrate

# 5. Create superuser and start
python manage.py createsuperuser
python manage.py runserver
```

Access the admin at: `http://127.0.0.1:8000/admin/`

## Configuration

### UNFOLD Settings Example

```python
from django.templatetags.static import static
from django.utils.translation import gettext_lazy as _

UNFOLD = {
    "SITE_HEADER": _("White Neuron"),
    "SITE_TITLE": _("White Neuron Admin"),
    "SITE_SUBHEADER": _("Admin panel"),
    "SITE_ICON": {
        "light": lambda request: static("base/images/logo/WhiteNeuron-128.png"),
        "dark": lambda request: static("base/images/logo/WhiteNeuron-128.png"),
    },
    "SITE_FAVICONS": [
        {
            "rel": "icon",
            "sizes": "32x32",
            "type": "image/png",
            "href": lambda request: static("base/images/logo/WhiteNeuron-32.png"),
        },
    ],
    "SHOW_HISTORY": False,
    "SHOW_LANGUAGES": True,
    "SHOW_VIEW_ON_SITE": True,
    "SHOW_BACK_BUTTON": True,
    "DASHBOARD_CALLBACK": "whiteneuron.dashboard.views.dashboard_callback",
    "LOGIN": {
        "image": lambda request: static("base/images/login-bg.jpg"),
    },
    "STYLES": [
        lambda request: static("base/css/styles.css"),
        lambda request: static("base/css/btn-styles.css"),
        lambda request: static("base/css/loading.css"),
    ],
    "SCRIPTS": [
        lambda request: static("base/js/loading.js"),
        lambda request: static("base/js/whiteneuron.js"),
    ],
    "BORDER_RADIUS": "6px",
}
```

### Server monitoring dashboard

`whiteneuron.monitoring` adds a Grafana-style dashboard at **System → Server monitoring**
(superusers, or staff with the `view_metricsample` permission):

- **Overview**: uptime, CPU, memory, disk, load, throughput, 5xx error rate and p95 latency,
  with sparklines and green / orange / red thresholds.
- **System**: CPU / memory / disk gauges, per-core heatmap, CPU, load, memory, disk I/O,
  network and disk space time series.
- **Application** (from the request logs `UserActivityMiddleware` already writes): requests
  per minute by outcome, p50 / p95 / p99 latency, status-code breakdown, Apdex score, and the
  slowest endpoints (IDs are grouped, e.g. `/user/:id/change/`).
- **Process & dependencies**: database and cache round-trip time, app memory and threads.
- Time range 5m–7d, auto-refresh (off–5m), host selector, shared crosshair across charts,
  shareable URLs (`?range=6h&refresh=30s&host=web-1`), follows the selected admin theme.

Add `"whiteneuron.monitoring"` to `INSTALLED_APPS`, run `migrate`, then collect samples on
each host (the dashboard also stores a sample while it is open, at most once per interval):

```bash
python manage.py monitoring_collector              # long-running, e.g. a systemd service
python manage.py monitoring_collector --once       # single sample (cron)
```

or schedule the Celery task `whiteneuron.monitoring.tasks.collect_metrics` with celery beat.

```python
WN_MONITORING = {
    "INTERVAL": 15,          # seconds between samples
    "RETENTION_DAYS": 7,     # older samples are pruned automatically
    "DISK_PATH": "/",        # filesystem shown in the disk panels
    # "HOST": "web-1",       # defaults to the machine hostname
}
```

### Admin themes (daisyUI)

All 35 daisyUI themes are compiled into `base/css/styles.css` and selectable from the user menu (**Themes**). The selected theme also re-colors Unfold (primary/base palettes), and its light/dark scheme drives Unfold's dark mode. The choice is stored per browser.

```python
# Optional: limit the themes offered in the picker (Light/Dark/System are always available)
WN_ADMIN_THEMES = ["corporate", "nord", "dracula", "forest"]  # [] hides the picker
```

To ship a smaller CSS bundle, compile only some themes: `WN_THEMES="nord,dracula" bash scripts/tailwind.sh`.

## Modules

| Module | Description | Key Models |
|---|---|---|
| `whiteneuron.base` | Core models, admin, middleware, utilities | `User`, `BaseModel`, `Image`, `Mail`, `App`, `IPBlacklist`, `UABlacklist` |
| `whiteneuron.dashboard` | Dashboard callback and badge system | — |
| `whiteneuron.notification` | WebSocket real-time notifications | `Notification`, `NotificationConfig` |
| `whiteneuron.file_management` | File upload with integrity verification | `ExcelFile`, `PDFFile` |
| `whiteneuron.feedbacks` | Per-model feedback collection | — |

## Middleware & Security

### Rate Limiting

```python
RATE_LIMIT_REQUESTS = 60   # max requests per window (by IP)
RATE_LIMIT_WINDOW     = 60  # in seconds
USER_RATE_LIMIT_REQUESTS = 60  # by authenticated user
USER_RATE_LIMIT_WINDOW   = 60
```

When limit exceeded:
- API (`/api/` or `Accept: application/json`) → JSON `{"detail": "Too many requests."}` (429)
- Browser → renders `429.html` with `Retry-After` header

### IP Blacklist

**Static** — `.env` (CIDR ranges, loaded at startup):
```env
IP_BLACKLIST=185.220.101.5,194.165.16.0/22,2001:db8::/32
```

**Dynamic** — Admin panel + Redis (real-time):
- Permanent block: leave `blocked_until` empty
- Temporary block: set `blocked_until` → Redis TTL auto-expires

### UA Blacklist

Static via `.env`:
```env
UA_BLACKLIST=GPTBot,ClaudeBot,https://openai.com
```

Dynamic via admin — supports regex patterns with real-time cache rebuild.

## Frontend (Tailwind 4 + daisyUI 5)

```bash
npm install -D @tailwindcss/cli@next daisyui@latest
bash scripts/tailwind.sh
```

Or directly:
```bash
npx @tailwindcss/cli -i styles.css -o whiteneuron/static/base/css/styles.css --minify
```

## Environment Variables

Copy `env.example` to `.env` and configure. Key variables:

| Variable | Description | Default |
|---|---|---|
| `SECRET_KEY` | Django secret key | — |
| `DEBUG` | Debug mode | `True` |
| `DATABASE` | Database type (`sqlite`/`postgres`) | `sqlite` |
| `REDIS` / `CACHE_REDIS_LOCATION` | Redis connection | `redis://127.0.0.1:6379` |
| `CELERY_BROKER_URL` | Celery broker URL | `redis://localhost:6379/0` |
| `RATE_LIMIT_REQUESTS` | IP rate limit count | `60` |
| `IP_BLACKLIST` | Static IP blocks (CIDR) | — |
| `UA_BLACKLIST` | Static UA blocks | — |

See `env.example` for the full list.

## Management Commands

| Command | Description |
|---|---|
| `init_admin` | Create initial admin user |
| `init_guest` | Create guest user account |
| `init_groupuser` | Initialize group users |
| `cleanup_old_activities` | Remove old activity records |
| `update_visit_profiles` | Update visit profile data |

## Building & Releasing

```bash
bash scripts/build.sh
```

This builds Tailwind CSS assets, runs migrations, and creates the Python package via `uv build`.

Publishing a **GitHub Release** (tag `v<version>`, equal to `version` in `pyproject.toml`) runs two
workflows: `python-publish.yml` uploads the package to PyPI, and `docker-base.yml` builds and pushes
the Docker base images.

### Docker base images

`anhneuron/django-whiteneuron-alpine:v<version>` and `anhneuron/django-whiteneuron-debian:v<version>`
contain Python 3.13 with this package installed. Its dependencies are pinned from `uv.lock`, the
same set CI tests. The images run as `appuser` (uid 100, gid 101, home `/app`). Projects build
`FROM` them, for example WN-Sense's web (Alpine) and core (Debian) images.

Every build goes through `docker/build-base.sh`:
- The source is a `git archive` of the chosen ref, never local files.
- Dependencies come from that ref's `uv.lock` (`uv export`).
- The Dockerfiles come from the current checkout, so older tags can be built too.
- Pushing is only allowed for the release tag `v<version>`, which must match `pyproject.toml`.
  A published tag is never rebuilt from other code.
- Each image fails to build if the installed version differs from its tag.

**CI/CD**: `.github/workflows/docker-base.yml` builds and pushes both images when a GitHub
Release is published.
- Required repository secrets: `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN` (a Docker Hub access
  token with write access).
- Optional repository variable: `DOCKERHUB_NAMESPACE` (default `anhneuron`).
- *Actions → Docker base images → Run workflow* builds any ref. Pushing from there also needs a
  release tag.
- Pull requests that touch `docker/`, `pyproject.toml` or `uv.lock` only build the images.

**By hand** (needs git, uv and docker buildx):

```bash
bash docker/build-base.sh                     # HEAD, load into local docker
GIT_REF=v0.3.8.0 bash docker/build-base.sh    # a tag / branch / commit
GIT_REF=v0.4.1.0 bash docker/push-base.sh     # push a release, with provenance and SBOM
VARIANTS=alpine IMAGE_NAMESPACE=myorg WN_PYTHON_VERSION=3.13 bash docker/build-base.sh
```

## Error Pages

Templates in `whiteneuron/templates/` are used automatically when `DEBUG=False`:

| Template | Error |
|---|---|
| `400.html` | Bad Request |
| `403.html` | Forbidden |
| `404.html` | Not Found |
| `429.html` | Too Many Requests |
| `500.html` | Server Error |

## Documentation

- **Giới thiệu**: Xem [docs/INTRODUCTION.md](docs/INTRODUCTION.md) — tài liệu giới thiệu dự án, tính năng nổi bật và ai nên dùng.
- **Hướng dẫn chi tiết**: Xem [docs/GUIDE.md](docs/GUIDE.md) cho tài liệu module, model, middleware và cấu hình đầy đủ.
- **Changelog**: See [CHANGELOG.md](CHANGELOG.md) for full version history.
- **CKEditor 5 Customization**: See [docs/CKEDITOR5_CUSTOMIZATION.md](docs/CKEDITOR5_CUSTOMIZATION.md).

## Contact

- Email: [anhnt@whiteneuron.com](mailto:anhnt@whiteneuron.com)
- Website: [https://whiteneuron.ai](https://whiteneuron.ai)
- GitHub: [https://github.com/White-Neuron/django-whiteneuron](https://github.com/White-Neuron/django-whiteneuron)

## License

MIT License.
