Installation¶

This guide covers installing Django Gentelella Widgets and configuring your project.

Requirements¶

Python 3.11 or higher
Django 5.2 or higher (the current LTS)

These are pulled in automatically as dependencies:

djangorestframework>=3.15.2
django_filter>=22.1
django-tree-queries>=0.11.0
Pillow
pycryptodome>=3.23.0

Basic Installation¶

Install from PyPI:

pip install djgentelella

Optional extras¶

pip install djgentelella[firmador]     # digital signature over websockets
pip install djgentelella[celery]       # queue-backed async_notification dispatch
pip install djgentelella[asr]          # voice dictation transcribed in-process
pip install djgentelella[asr-remote]   # voice dictation transcribed elsewhere
pip install djgentelella[dev]          # asset bundling and minification (pylp)

The two asr extras back the voice dictation widgets, and you need at most one of them. The widgets themselves ship with the package; only VoiceTranscribeView needs a speech recognition backend, and it imports it lazily, so a plain install neither pulls nor loads any of this.

asr is the local backend: Parakeet-v3 running in the Django process through onnx-asr, with av decoding the uploaded audio. It is the heavy one — the first request downloads a ~670 MB model from Hugging Face.
asr-remote is the remote backend, which forwards the audio to an external ASR API and therefore needs nothing but an HTTP client.

Without the matching extra the endpoint answers 501 naming the one to install, so a missing extra is a clear error and never an import failure.

The celery extra is genuinely optional: async_notification autodetects it. With Celery installed and CELERY_BROKER_URL set, notifications are dispatched through the queue; otherwise they fall back to SyncBackend and are sent in-process. Nothing to configure either way — set ASYNC_NOTIFICATION_BACKEND only to force one explicitly.

The firmador extra covers two separate concerns:

channels and wsproto — the signing websocket and its session authentication. Only the digital signature module needs them.
uvicorn and uvicorn-worker — serving the ASGI application. Any async Django deployment needs an ASGI server, not just digital signature. Replace them with your own if you already deploy under a different one.

Configuration¶

1. Add Required Apps¶

Add the following to your INSTALLED_APPS in settings.py:

INSTALLED_APPS = [
    # Django apps...
    'django.contrib.admin',
    'django.contrib.staticfiles',

    # Required apps
    'djgentelella',
    'rest_framework',

    # Optional apps (add as needed)
    'djgentelella.blog',
    'djgentelella.async_notification',

    # Your apps...
]

django.contrib.admin is not optional: the change tracking in djgentelella.history records through django.contrib.admin.models.LogEntry, which djgentelella/models.py imports at module level. Without it the project fails at startup with Model class django.contrib.admin.models.LogEntry doesn't declare an explicit app_label and isn't in an application in INSTALLED_APPS.

Only djgentelella.blog and djgentelella.async_notification are separate Django apps — they are the two that ship their own models, migrations, templates and static. The rest of the subpackages (notification, permission_management, chunked_upload, trash, history, voice, firmador_digital) are plain Python modules: their models, when they have any, belong to the djgentelella app and migrate with it, and their views are wired through djgentelella.urls. Adding them to INSTALLED_APPS does nothing.

2. Required Settings¶

Add these required settings:

JQUERY_URL = None

3. Recommended Settings¶

import os
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

# Static and media files
STATIC_URL = '/static/'
STATIC_ROOT = os.path.join(BASE_DIR, 'static/')
MEDIA_URL = '/media/'
MEDIA_ROOT = os.path.join(BASE_DIR, 'media/')

# TinyMCE upload path
TINYMCE_UPLOAD_PATH = os.path.join(MEDIA_ROOT, 'tinymce')

4. URL Configuration¶

Include djgentelella URLs in your urls.py:

from django.urls import path, include
from djgentelella.urls import urlpatterns as djgentelella_urls

urlpatterns = [
    # Your URLs...
    path('', include(djgentelella_urls)),
]

5. Run Migrations¶

python manage.py migrate

6. Load Static Files¶

Download and set up frontend assets:

pip install requests
python manage.py loaddevstatic

7. Generate Base JavaScript¶

Generate the base JavaScript file for widgets:

python manage.py createbasejs

Optional Features¶

Chunked File Upload¶

For large file uploads with progress tracking:

Add to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    'djgentelella.chunked_upload',
]

Run migrations:

python manage.py migrate

Configure cleanup (optional):

# Delete expired uploads (run periodically via cron)
python manage.py delete_expired_uploads

Digital Signature Integration¶

For digital document signing with Firmador Libre:

Install additional dependencies:

pip install djgentelella[firmador]

This pulls channels and wsproto for the signing websocket, django-cors-headers, and uvicorn + uvicorn-worker to serve the ASGI application. The steps below assume the uvicorn worker; if you already run another ASGI server, keep it and skip asgi_worker.py.

Add to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    'corsheaders',
    'channels',
]

Add CORS middleware (must be first):

MIDDLEWARE = [
    'corsheaders.middleware.CorsMiddleware',
    'django.middleware.security.SecurityMiddleware',
    # other middleware...
]

Configure CORS:

CORS_ALLOW_ALL_ORIGINS = True
# Or for production:
# CORS_ALLOWED_ORIGINS = [
#     "https://yourdomain.com",
# ]

Add WebSocket and Firmador settings:

# WebSocket configuration
DJANGO_ASETTINGS_MODULE = "yourproject.asettings"
GUNICORN_BIND = "127.0.0.1:9022"
GUNICORN_ASGI_APP = "yourproject.asgi:application"
GUNICORN_WSGI_APP = "yourproject.wsgi:application"
GUNICORN_WORKERS = 2
GUNICORN_WORKER_CLASS = "yourproject.asgi_worker.UvicornWorker"

# Firmador Libre configuration
FIRMADOR_CORS = "http://127.0.0.1:8000"
FIRMADOR_WS = "ws://127.0.0.1:9022/async/"
FIRMADOR_WS_URL = FIRMADOR_WS + "sign_document"
FIRMADOR_DOMAIN = "http://localhost:9001"
FIRMADOR_VALIDA_URL = FIRMADOR_DOMAIN + "/valida/"
FIRMADOR_SIGN_URL = FIRMADOR_DOMAIN + "/firma/firme"
FIRMADOR_SIGN_COMPLETE = FIRMADOR_DOMAIN + "/firma/completa"
FIRMADOR_DELETE_FILE_URL = FIRMADOR_DOMAIN + "/firma/delete"
# Optional: Bearer token for firmador_api (its API_TOKEN). Unset = no header.
FIRMADOR_TOKEN = os.getenv("FIRMADOR_TOKEN")

Create ASGI configuration files:

asgi.py:

from djgentelella.firmador_digital.config.asgi_config import AsgiConfig
application = AsgiConfig("yourproject.settings").application

asgi_worker.py:

from uvicorn_worker import UvicornWorker as BaseUvicornWorker

class UvicornWorker(BaseUvicornWorker):
    CONFIG_KWARGS = {"lifespan": "off", "loop": "auto", "http": "auto"}

aurls.py:

urlpatterns = []

asettings.py:

from .settings import *
ROOT_URLCONF = "yourproject.aurls"

See the Advanced Widgets section for detailed Digital Signature widget documentation.

Notification System¶

For user notifications:

Add to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    'djgentelella.notification',
]

Run migrations:

python manage.py migrate

History/Audit Trail¶

For tracking model changes:

Add to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    'djgentelella.history',
]

Run migrations:

python manage.py migrate

Default JavaScript Imports¶

You can configure default JavaScript imports in settings:

DEFAULT_JS_IMPORTS = {
    'use_readonlywidgets': True,
}

Verification¶

To verify your installation, run the development server:

python manage.py runserver

Then visit http://localhost:8000/ and check that:

Static files are loading (Bootstrap styles applied)
JavaScript widgets are functional
No console errors in browser developer tools