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.

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 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 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 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 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 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 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 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 for the full version history.

Table of Contents

• Changelog
• Features
• Installation
• Quick Start
• Configuration
• Modules
• Middleware & Security
• Frontend
• Environment Variables
• Management Commands
• Building & Releasing
• Documentation
• Contact

Giới thiệu

Xem 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

Installation

From PyPI (recommended)

pip install django-whiteneuron

Or with uv:

uv add django-whiteneuron

Specific version from PyPI

uv add "django-whiteneuron==0.3.4.12"

From GitHub tag

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

From local source

uv pip install -e .

Quick Start

# 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

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):

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.

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.

# 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

Middleware & Security

Rate Limiting

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):

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:

UA_BLACKLIST=GPTBot,ClaudeBot,https://openai.com

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

Frontend (Tailwind 4 + daisyUI 5)

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

Or directly:

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:

See env.example for the full list.

Management Commands

Building & Releasing

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 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:

Documentation

• Giới thiệu: Xem 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 cho tài liệu module, model, middleware và cấu hình đầy đủ.
• Changelog: See CHANGELOG.md for full version history.
• CKEditor 5 Customization: See docs/CKEDITOR5_CUSTOMIZATION.md.

Contact

• Email: anhnt@whiteneuron.com
• Website: https://whiteneuron.ai
• GitHub: https://github.com/White-Neuron/django-whiteneuron

License

MIT License.