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.3.8.0

Changelog

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.png"),
        "dark": lambda request: static("base/images/logo/WhiteNeuron.png"),
    },
    "SITE_FAVICONS": [
        {
            "rel": "icon",
            "sizes": "32x32",
            "type": "image/svg+xml",
            "href": lambda request: static("base/images/logo/WhiteNeuron.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",
}

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.

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.