DEV Community: Aidas Bendoraitis

Setting Up DNS for SaaS Emails

Aidas Bendoraitis — Sat, 26 Sep 2026 12:11:32 +0000

When you create a Software as a Service (SaaS) or a social web platform, one of the often-overlooked parts of it is the email DNS configuration. I learned this too late with my own projects, and as a result, many of my initial emails landed in spam folders. Also, incorrect DNS records can make it easier for attackers to send emails pretending to be from your domain. Here are my learnings about it from 5 years of running a SaaS business.

Consider using separate subdomains for different types of email

The emails you send generally fall into these categories:

direct - emails that you send manually.
transactional - emails that your website sends for signup confirmations, two-factor authentications, password resets, etc.
marketing - onboarding emails, mailing-list newsletters, birthday greetings, etc.

Marketing emails are frequent and not always wanted, so recipients may mark them as spam, which can hurt your sender reputation. Deliverability also depends on factors such as authentication, engagement, list quality, and sending practices (You can check your existing email spamminess at SpamHaus or MxToolbox).

For this reason, it can be useful to separate marketing emails from direct and transactional emails using different subdomains.

If example.com is your marketing website, and app.example.com is your SaaS, your main emails could be:

info@hello.example.com - for marketing / newsletters
hello@mail.example.com - for transactional and direct emails

MX records for receiving emails

An MX record (Mail eXchange record) is a type of DNS record that specifies which mail server is responsible for accepting email on behalf of a domain. When somebody sends an email to you, the sending mail server looks up the MX record for your domain to find out where to deliver that message.

In the host field you would set your subdomain (or @ for the root domain).
The values contain the domain of the mail server and the priority of that server (a lower preference number means higher priority). If the server with higher priority is unreachable, the mail will fall back to the secondary one.
TTL (Time To Live) controls how long DNS resolvers are allowed to cache a record before checking back for updates. While configuring and testing the server you can set it to a low value like 5 min, but when everything is working reliably, you can switch to Automatic.

Here is an example setup pointing to FastMail servers.

Type	Host	Value	TTL
MX Record	hello	in1-smtp.messagingengine.com. 10	Automatic
MX Record	hello	in2-smtp.messagingengine.com. 20	Automatic
MX Record	mail	in1-smtp.messagingengine.com. 10	Automatic
MX Record	mail	in2-smtp.messagingengine.com. 20	Automatic

Note that Fastmail does not allow its service to be used for automated or transactional emails, but you might need these settings for receiving your direct emails and replies.

SMTP setup for outgoing emails

SMTP (Simple Mail Transfer Protocol) is the protocol used to transfer email between mail servers and from mail clients or applications to mail servers. SMTP will be used no matter whether you send a direct email from an email client like FastMail, or a transactional email from Amazon SES, Postmark, Brevo, Mailjet, Resend, SendGrid, Mailgun, or Postal.

SPF records for outgoing emails: Which senders are allowed?

An SPF record (Sender Policy Framework) is a type of DNS TXT record that specifies which mail servers are allowed to send email on behalf of your domain. It's one of the core mechanisms used to prevent email spoofing. SPF has one record per domain or subdomain and multiple senders must be combined into one line.

Type	Host	Value	TTL
TXT Record	hello	`v=spf1 include:spf.messagingengine.com include:spf.mailjet.com -all`	Automatic
TXT Record	mail	`v=spf1 include:spf.messagingengine.com include:spf.mailjet.com -all`	Automatic

Here:

v=spf1 - declares this is an SPF record, version 1.
include:domain.com - delegate to another domain's SPF record.
-all - hard fail - SPF fails for unauthorized senders.
~all - soft fail - SPF fails, but the receiver may still accept the message.
?all - neutral - SPF makes no policy statement.

Some of the well known includes:

include:spf.messagingengine.com - FastMail
include:_spf.google.com - Google Workspace
include:spf.mailjet.com - Mailjet
include:spf.brevo.com - Brevo
include:servers.mcsv.net - MailChimp
include:amazonses.com - Amazon SES or Resend (which is built on top of Amazon SES)
include:sendgrid.net - SendGrid
include:mailgun.org - Mailgun

DKIM records for outgoing emails: Is the sender valid?

A DKIM record (DomainKeys Identified Mail) is a DNS TXT record containing a public cryptographic key that lets receiving mail servers verify that an email genuinely came from your domain and wasn't altered in transit. Sometimes, it's a CNAME record pointing to the servers of the mail service, which contains the DNS TXT records with the cryptographic keys. Typically, the Host is <prefix>._domainkey.<your_subdomain>.

Here is an example Mailjet config:

Type	Host	Value	TTL
TXT Record	mailjet._domainkey.hello	`k=rsa; p=<unique_id>`	Automatic
TXT Record	mailjet._domainkey.mail	`k=rsa; p=<unique_id>`	Automatic

For FastMail, it would be:

Type	Host	Value	TTL
CNAME Record	fm1._domainkey.hello	`fm1.hello.<root_domain>.dkim.fmhosted.com.`	Automatic
CNAME Record	fm1._domainkey.mail	`fm1.mail.<root_domain>.dkim.fmhosted.com.`	Automatic
CNAME Record	fm2._domainkey.hello	`fm2.hello.<root_domain>.dkim.fmhosted.com.`	Automatic
CNAME Record	fm2._domainkey.mail	`fm2.mail.<root_domain>.dkim.fmhosted.com.`	Automatic
CNAME Record	fm3._domainkey.hello	`fm3.hello.<root_domain>.dkim.fmhosted.com.`	Automatic
CNAME Record	fm3._domainkey.mail	`fm3.mail.<root_domain>.dkim.fmhosted.com.`	Automatic

DMARC records for outgoing emails: What to do with unauthorized senders?

DMARC (Domain-based Message Authentication, Reporting & Conformance) is a DNS TXT record that ties SPF and DKIM together into a single policy, telling receiving mail servers what to do when a message fails authentication, and optionally sending you reports about it.

Type	Host	Value	TTL
TXT Record	_dmarc.mail	`v=DMARC1; p=reject; pct=100; rua=mailto:dmarc-reports@mail.<root_domain>`	Automatic
TXT Record	_dmarc.hello	`v=DMARC1; p=reject; pct=100; rua=mailto:dmarc-reports@mail.<root_domain>`	Automatic

Here:

v=DMARC1 - declares this is an DMARC record, version 1.
p - stands for Policy and defines what receivers should do on failure:
- none (monitor only, no action),
- quarantine (send to spam),
- reject (block outright).
pct= - the percentage of messages to which the policy should be applied.
rua=mailto:... - tells where to send aggregate reports as daily XML summaries of pass/fail volumes.

The daily aggregate reports are a little annoying, but they are required for the emails to have little probability to land in a Spam directory.

Brevo setup as an exception

Brevo requires its own set of CNAME and TXT records to authenticate your domain and improve email deliverability. You would get the setup instructions while onboarding.

BIMI records for the outgoing emails: What brand logo will be shown?

BIMI (Brand Indicators for Message Identification) is a DNS TXT record that lets your logo appear as the sender avatar next to your emails in supporting email clients and services such as Gmail, Yahoo Mail, Apple Mail, and Fastmail.

Here is an example of BIMI records:

Type	Host	Value	TTL
TXT Record	default._bimi.mail	`v=BIMI1; l=https://www.<root_domain>/static/0/email/img/bimi-logo.svg; a=<cert_url>;`	Automatic
TXT Record	default._bimi.hello	`v=BIMI1; l=https://www.<root_domain>/static/0/email/img/bimi-logo.svg; a=<cert_url>;`	Automatic

BIMI defines not just a simple favicon, but rather the official logo of the brand. To fully support such an image, you would need to buy a certificate that costs from 650 to 1500 USD per year at the time of writing. There are two types: VMC (Verified Mark Certificate) for registered trademarks, and CMC (Common Mark Certificate) (cheaper one) for any logo. DigiCert and Entrust Datacard are the active BIMI-authorized certificate authorities.

If you set the BIMI record without the certificate, the image might still show up in some email clients, like the FastMail. It's just important that the used SVG file is of the SVG Tiny Portable/Secure (SVG Tiny PS). You can use https://makebimi.com/ to generate the SVG of an appropriate size and upload the logo to your website, e.g. under site_static/email/img/bimi-logo.svg.

Also, for BIMI, DMARC must use an enforcement policy (p=quarantine or p=reject) with pct=100.

Final words

So if you want to maximize your email deliverability, have two subdomains for the SaaS or web platform, and make sure to set all the guardrails as recommended:

Record/Setting	Direction	Purpose
MX record	Incoming	Tells senders where to deliver mail to your domain
SMTP server setting (in your email client)	Outgoing	Where you connect to send mail from your account
SPF record	Outgoing (verification)	Tells receivers which servers are authorized to send mail claiming to be from your domain
DKIM record	Outgoing (verification)	Cryptographically signs outgoing mail so receivers can verify it wasn't tampered with
DMARC record	Both (policy)	Tells receivers what to do if SPF/DKIM checks fail
BIMI record	Outgoing	Lets you display your brand's logo next to your emails in supporting inboxes

Cover picture by cottonbro studio

When Python is Too Slow

Aidas Bendoraitis — Sun, 23 Aug 2026 12:17:08 +0000

Python is a perfect language for Agile development, where requirements might change on the go. Especially if you are in a startup business, you will need to experiment and change things fast. However, Python is an interpreted language, and in certain situations you might need faster performance than what an interpreted language can provide. A common practice in these cases is using python-to-binary bindings, where the binary code is built with Rust, C++, or Go. In this article, I will explore bindings to Rust-based code.

How do the bindings work

The idea behind bindings is that you create a module with functions of a specific domain in a language that compiles to binary, and build it as a C-compatible dynamic library (.so on Linux, .dylib on macOS, .dll on Windows). Then a Python wrapper is built as a Python package and installed together with the dynamic library, allowing you to import and use functions that pass control to the corresponding functions in the dynamic library. On some occasions, classes can be used instead of functions. If any parameters are complex, they must be serialized in the wrapper and passed to the dynamic library as a JSON string or as a set of individual primitive parameters.

An experiment with benchmarks

To try this Python-Rust communication, I vibe coded an experiment that reads a large CSV file and builds a new one with duplicates stripped out based on specified column indexes. In my test case, it was a 3 MB CSV file with data about European NGOs for the donation platform I am building, where I wanted to remove the NGOs that don't have website URLs listed. As benchmarked, the file was processed 4.3x faster with the Rust binding than directly with Python.

Here is the repo to get a first glimpse into the code and structure.

What is there to know about Rust

A few things about Rust: Rust packages are built with Cargo, which is the equivalent of pip, virtualenv, and setuptools combined. A single package is called a crate, and it can be published to crates.io, the equivalent of PyPI. To create a Python-to-Rust binding, the standard approach is to use Rust's PyO3 library together with maturin, a build tool installable as a PyPI package.

Rust syntax is not the most developer-friendly compared to Python or Go, but with today's AI agents, most Python-native code can be ported to it fairly easily. The good thing about Rust and Go compared to C++ is that you don't have to manage memory at a low level or work with pointers directly.

The package structure

The common file structure can be:

thepackage_rs/           # the package — self-contained and installable
├── Cargo.toml           # crate manifest (pyo3, etc.)
├── pyproject.toml       # maturin build backend config
├── src/lib.rs           # Rust implementation
└── python/
    └── thepackage_rs/
        └── __init__.py  # Python wrapper

Once the code is ready, you build it with:

(.venv) maturin develop --release

This builds the Python package and installs it into the current virtual environment. You can also get the wheel at thepackage_rs/target/*.whl, built for your specific operating system.

Rust in Django

When developing Django websites, the biggest bottlenecks are usually not in the language itself, but in the connections to databases, file systems or object storage, and APIs. Still, in cases where you need to process large amounts of data or do heavier calculations, using a binary instead of Python makes sense. The orjson library, and DRF renderers built on top of it such as django-orjson or drf-orjson-renderer, are good examples of this — Rust boosts the speed of building or parsing JSON 2-10x compared to a Python-native implementation. The best places to use Rust replacements are background tasks, management commands, template parsing (see the experimental django-rusty-templates), and occasionally views or middleware.

Final words

So Python itself is good enough, especially when it comes to code readability and speed of development. However, when needed, certain parts can be boosted 2 to 10x just by rewriting them as Python-Rust bindings. Just keep in mind that when it comes to views with data from the database or Elasticsearch, post-processing — such as reordering in Python or Rust — is an antipattern; do that directly in the queries instead. Finally, keep in mind, that building with Rust will need extra dependencies and maintenance in your workflows.

Cover photo by Alex Tepetidis

Understanding Memory Usage in Django Webserver Workers

Aidas Bendoraitis — Sun, 14 Jun 2026 13:07:50 +0000

If you are coming from the PHP world, you might be used to thinking that when a request reaches the web server, everything is parsed and processed from scratch. In Python, however, the behavior is a little different.

A Python web server (for example, Gunicorn) starts one or more worker processes and then continuously accepts and processes requests as a running server application. In this article, I will explore how memory is managed in that environment.

Startup time vs. request execution

When you run a Django web server (either the development server or a Gunicorn-based deployment), there are two phases of execution: startup, when the server application is initialized, and the request/response cycle, when a request is received and processed to return a response.

During startup, wsgi.py and get_wsgi_application() are executed once per worker at boot time, Django settings are evaluated, applications listed in INSTALLED_APPS are imported and registered, ready() methods of app configs are called, and URL patterns are compiled.

During request execution, the middleware chain processes the request, the URL is resolved, the view is executed, context managers run within the view, the template is rendered, the middleware chain processes the response, and the response is returned.

The Django development server runs a single worker process but uses threads to handle concurrent requests. Gunicorn runs multiple worker processes (separate copies of the server application). A common rule of thumb for Gunicorn configuration is (2 × number_of_CPU_cores) + 1 workers.

Little demo of shared memory between requests

If you have mutable globals in your Django code, they will be shared within the same worker process, even across threads.

Here's a simple example for demonstration purposes (note that this is an antipattern and should never be used in production):

from django.http import JsonResponse
from django.utils.timezone import now

TIMESTAMPS = []

def show_timestamps(request):
    TIMESTAMPS.append(now())
    return JsonResponse({"timestamps": TIMESTAMPS})

The output would be (manually indented for readability):

{"timestamps": [
  "2026-06-08T19:48:42.044Z", 
  "2026-06-08T19:48:43.875Z", 
  "2026-06-08T19:48:44.776Z"
]}

If you serve this application with Gunicorn using multiple workers and open the view in several tabs, refreshing them a few times, you will see that the timestamp list keeps growing. However, because each request may be served by a different worker, the timestamps returned by each worker will differ.

How RAM is managed

1. Compilation/setup state is persistent

When Django starts and the application server is initialized, the following objects live in process memory for the lifetime of the worker process:

django.apps.registry.Apps (the app registry with all models)
URL resolvers (urlpatterns)
Middleware instances (if instantiated at startup)
Cached template engines
Database connection configurations (not connections themselves)

This memory normally remains allocated until the worker process restarts.

2. Execution state lives per-request

Each request creates objects that are local to that request's call stack—views, forms, querysets, serializers, and so on. Once the response is sent:

Python's garbage collector normally reclaims those objects.
There is no explicit Django cleanup; Django relies on Python's normal memory management.
Request-scoped objects are cleaned up only after they go out of scope and no references to them remain.

Common bugs to avoid

1. Mutable module-level state

A mutable object defined at the module level persists across all requests handled by that worker process and will accumulate data from every user.

❌ BAD:

_recent_users = []

def dashboard(request):
    # leaks across requests!
    _recent_users.append(request.user.id)
    return render(
        request, 
        "dashboard.html", 
        {"recent": _recent_users}
    )

✅ GOOD — state belongs in the DB, cache, or session:

def dashboard(request):
    recent_users = get_recent_users_from_db()
    return render(
        request, 
        "dashboard.html", 
        {"recent": recent_users}
    )

2. Storing per-request data on a shared instance

Middleware instances live for the lifetime of the worker process. Storing anything request-specific on self means it will be shared across every request handled by that worker.

❌ BAD:

class AuditMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response
        # shared across all requests!
        self.current_user = None

    def __call__(self, request):
        # User A's data visible when User B's request runs
        self.current_user = request.user
        return self.get_response(request)

✅ GOOD — attach data to the request object, which is scoped to a single request:

class AuditMiddleware:
    def __init__(self, get_response):
        # only immutable config on self
        self.get_response = get_response

    def __call__(self, request):
        # scoped to this request's lifetime
        request.current_user = request.user
        return self.get_response(request)

3. Class-level cache shared across instances

A class attribute is shared across all instances of that class and therefore across all requests. The first user's data may be cached and returned to everyone else.

❌ BAD:

class ReportGenerator:
    # class attribute, shared across all instances and all requests!
    _cache = {}

    def get_data(self, user):
        if "data" not in self._cache:
            # first user's data cached for everyone
            self._cache["data"] = expensive_query(user)  
        return self._cache["data"]

✅ GOOD — use the cache framework with a user-scoped key:

from django.core.cache import cache

class ReportGenerator:
    def get_data(self, user):
        key = f"report:{user.id}"
        return cache.get_or_set(
            key, 
            lambda: expensive_query(user), 
            timeout=300,
        )

Mental model

Before writing module-level code, ask yourself:

"If 1000 different users hit this worker, and this variable exists for all of them, is that safe?"

Location	Lifetime	Safe for user data?
Local variable in a view/function	Single request	✅ Yes
`request` object attributes	Single request	✅ Yes
`threading.local()`	Single thread	✅ Yes
Database / cache with scoped keys	Persistent but keyed	✅ Yes
`self` on a middleware/class instance	Worker lifetime	⚠️ Only immutable config
Module-level mutable variable	Worker lifetime	❌ Never user data
Class-level mutable attribute	Worker lifetime	❌ Never user data

Rule of thumb: immutable configuration (numbers, booleans, strings, bytes, tuples, frozensets, and None) belongs at module level; anything that varies by request, user, or time belongs in the request cycle.

Conclusion

A Django worker process has two separate memory areas: a startup state that lives for the lifetime of the worker process (app registry, URL resolvers, middleware instances, template engines) and a request state that exists only while handling a request (views, querysets, forms) and is reclaimed by Python's garbage collector afterward.

The main rule is that immutable configuration can live at the module level, but anything that depends on the current user or request should stay inside the request cycle, such as local variables or the request object.

That's because module-level variables, class attributes, and middleware instance state are shared by all requests handled by the same worker, making them unsafe for user-specific data and a common cause of memory leaks and data exposure bugs.

Cover Picture by Jon Tyson

Browser Push Notifications for a Django Website

Aidas Bendoraitis — Sat, 06 Jun 2026 14:58:29 +0000

For DjangoTricks, and some other websites, I intentionally didn't set email notifications when a feedback message arrived – I didn't want to pay for an email server or spam my inbox. While checking the messages in the database from time to time, sometimes I found out about them too late.

Last weekend, I decided to implement Web Push notifications to get notified about the feedback in my OS, just like in this example:

This tutorial walks through adding Web Push notifications to a Django project from scratch. When a visitor submits a feedback form the site owner receives a native browser notification — even if the admin tab is closed — thanks to a service worker and a Huey background task.

How it works

Push Notifications work in such a way: at first, people who want to get notifications need to subscribe to the notifications in their browser. The subscribers are stored on the push notification servers and also their identifiers are stored in Django website database. Whenever we need to send the messages to those subscribers, we send them to push notification server that passes the message to all subscribers if their browsers are open at the moment. If the browsers are closed at that moment, the message's TTL (time to live) in seconds set long enough, and the message is not expired yet, they will get the message later.

The push service depends on the browser:

Chrome - Google's FCM (Firebase Cloud Messaging) — fcm.googleapis.com
Firefox - Mozilla Autopush — updates.push.services.mozilla.com
Safari - Apple Push Notification Service (APNs)

The two standard Web Push prerequisites are a VAPID key pair (identifies your server
to the push service) and a service worker (a background JS script that receives the
push and shows the notification even when the tab is closed).

The workflow would be as follows:

I as a superuser visit the Django administration page that has sw.js file with a service worker and a JavaScript to subscribe to notifications.
JavaScript request Notification permission. I accept it.
JS calls pushManager.subscribe() with the VAPID public key.
JS POSTs the subscription to /notifications/push/subscribe/.
Django stores it in PushSubscription model.

Visitor submits feedback form

A view saves FeedbackMessage to the database.
transaction.on_commit queues a Huey task.
Huey task calls pywebpush - browser's push service (FCM / Mozilla).
Push service wakes the service worker.
Service worker shows a native OS notification.
Clicking it opens the Django admin change page.

Prerequisites

Django project using Huey for background tasks
Python virtual environment

Install two dependencies:

(.venv)$ pip install pywebpush py-vapid

pywebpush is the library to communicate with the Push Notification server.
py-vapid will only be needed once to generate keys.

You'll need HTTPS to test the Web Push notifications if your host is not 127.0.0.1. If you use a custom domain in your /etc/hosts, such as djangotricks.localhost, you will also need to set up HTTPS with mkcert.

Step 1. The Feedback App

Create feedback app with FeedbackMessage model that will store submitted feedback messages:

# myproject/apps/feedback/models.py
from django.conf import settings
from django.db import models
from django.utils.translation import gettext_lazy as _


class FeedbackMessage(models.Model):
    created_at = models.DateTimeField(_("Created at"), auto_now_add=True)
    submitter_name = models.CharField(_("Submitter name"), max_length=200)
    submitter_email = models.EmailField(_("Submitter email")
    content = models.TextField(_("Content")

    class Meta:
        verbose_name = _("Feedback Message")
        verbose_name_plural = _("Feedback Messages")
        ordering = ("-created_at",)

    def __str__(self):
        return _("Feedback message from {}").format(self.submitter_name)

Create the form:

# myproject/apps/feedback/forms.py
from django import forms
from django.utils.translation import gettext_lazy as _
from .models import FeedbackMessage


class FeedbackMessageForm(forms.ModelForm):
    class Meta:
        model = FeedbackMessage
        fields = [
            "content",
            "submitter_name",
            "submitter_email",
        ]
        widgets = {
            "content": forms.Textarea(
                attrs={
                    "rows": 5, 
                    "placeholder": _("Your message")
                }
            ),
        }
        labels = {
            "submitter_name": _("Your name"),
            "submitter_email": _("Your email"),
        }

Create a view to handle that form:

# myproject/apps/feedback/views.py
from django.db import transaction
from django.shortcuts import render, redirect
from django.urls import reverse
from .forms import FeedbackMessageForm
from .tasks import send_feedback_push_notification


def feedback_form(request):
    if request.method == "POST":
        form = FeedbackMessageForm(data=request.POST)
        if form.is_valid():
            message = form.save(commit=False)
            if request.user.is_authenticated:
                message.user = request.user
            message.save()

            transaction.on_commit(
                lambda: send_feedback_push_notification(message.pk)
            )

            return redirect(reverse("feedback:complete"))
    else:
        form = FeedbackMessageForm()

    return render(request, "feedback/form.html", {"form": form})


def feedback_complete(request):
    return render(request, "feedback/complete.html")

Create the app config, migrations, templates, URLs, and Django administration for it.

Step 2. VAPID keys

Generate the key pair once. These stay on the server and are never committed to version
control.

(.venv)$ vapid --gen
(.venv)$ vapid --applicationServerKey --private-key private_key.pem

--gen writes private_key.pem and public_key.pem to the current directory.

The private_key.pem file will contain the key like:

-----BEGIN PRIVATE KEY-----
<Multiline private key data>
-----END PRIVATE KEY-----

--applicationServerKey prints the base64url-encoded public key the browser needs, such as:

Application Server Key = <Public key data as base64url>

For the secrets.json or .env file where you store your secrets, you will need the content of <Private key data with newlines removed> and <Public key data as base64url>.

{
    ...
    "VAPID_PRIVATE_KEY": "<Private key data with newlines removed>",
    "VAPID_PUBLIC_KEY": "<Public key data as base64url>"
}

Don't commit the *.pem files or the secrets to the Git repo!

Step 3. Django settings

# myproject/settings.py

### WEB PUSH ###

VAPID_PRIVATE_KEY = get_secret("VAPID_PRIVATE_KEY")
VAPID_PUBLIC_KEY  = get_secret("VAPID_PUBLIC_KEY")
VAPID_ADMIN_EMAIL = "admin@mydomain.com"

Step 4. The Notifications App

Create notifications app with the PushSubscription model to track the Push notification subscribers:

# myproject/apps/notifications/models.py
from django.conf import settings
from django.db import models
from django.utils.translation import gettext_lazy as _


class PushSubscription(models.Model):
    """One browser push subscription for one device."""

    created_at  = models.DateTimeField(_("Created at"), auto_now_add=True)
    user = models.ForeignKey(
        _("User"),
        settings.AUTH_USER_MODEL,
        on_delete=models.CASCADE,
        related_name="push_subscriptions",
    )
    endpoint = models.TextField(_("Endpoint"), unique=True)
    p256dh = models.TextField(_("Browser ECDH public key"))
    auth = models.TextField(_("16-byte auth secret")) 

    class Meta:
        verbose_name = _("Push Subscription")
        verbose_name_plural = _("Push Subscriptions")
        ordering = ("-created_at",)

    def __str__(self):
        return f"{self.user} — {self.endpoint[:60]}"

Create app configuration, migrations, and Django administration for it.

Step 5. Subscribe / unsubscribe views

Create the views that will be called after the user subscribes or unsubscribes to Push notifications. Also a view for the service worker sw.js:

# myproject/apps/notifications/views.py
import json

from django.contrib.auth.decorators import login_required
from django.contrib.staticfiles import finders
from django.http import HttpResponse, JsonResponse
from django.views.decorators.http import require_POST

from .models import PushSubscription


@login_required
@require_POST
def push_subscribe(request):
    try:
        data     = json.loads(request.body)
        endpoint = data["endpoint"]
        p256dh   = data["keys"]["p256dh"]
        auth     = data["keys"]["auth"]
    except (KeyError, json.JSONDecodeError):
        return JsonResponse({"error": "Invalid subscription data"}, status=400)

    PushSubscription.objects.update_or_create(
        endpoint=endpoint,
        defaults={"user": request.user, "p256dh": p256dh, "auth": auth},
    )
    return JsonResponse({"status": "subscribed"})


@login_required
@require_POST
def push_unsubscribe(request):
    try:
        endpoint = json.loads(request.body)["endpoint"]
    except (KeyError, json.JSONDecodeError):
        return JsonResponse(
            {"error": "Invalid data"}, 
            status=400
        )

    PushSubscription.objects.filter(
        user=request.user, 
        endpoint=endpoint,
    ).delete()
    return JsonResponse({"status": "unsubscribed"})


def service_worker(request):
    """Serve sw-feedback.js as sw.js at the admin root"""
    path = finders.find("admin/js/sw-feedback.js")
    with open(path) as fh:
        content = fh.read()
    return HttpResponse(
        content, 
        content_type="application/javascript"
    )

Step 6. Wire URLs into myproject/urls.py

Plug the notification views into URLs:

# myproject/apps/notifications/urls.py
from django.urls import path
from . import views

app_name = "notifications"

urlpatterns = [
    path("push/subscribe/", views.push_subscribe,   name="push_subscribe"),
    path("push/unsubscribe/", views.push_unsubscribe, name="push_unsubscribe"),
]

The service worker URL must be mounted at the same prefix as ADMIN_URL so its scope
covers the admin. Add both patterns before the admin.site.urls line:

# myproject/urls.py
from notifications import views as notifications_views

urlpatterns = [
    # ...
    path(
        f"{settings.ADMIN_URL}sw.js",
        notifications_views.service_worker,
        name="admin_service_worker",
    ),
    path(
        "notifications/",
        include("notifications.urls", namespace="notifications"),
    ),
    path(settings.ADMIN_URL, admin.site.urls),
    # ...
]

Step 7. Service worker JavaScript

Save as myproject/static/admin/js/sw-feedback.js:

self.addEventListener("push", function (event) {
  const data    = event.data ? event.data.json() : {};
  const title   = data.title || "New feedback message";
  const options = {
    body: data.body || "",
    icon: "/static/admin/img/icon-yes.svg",
    data: { url: data.url || "/" },
  };
  event.waitUntil(
    self.registration.showNotification(title, options)
  );
});

self.addEventListener("notificationclick", function (event) {
  event.notification.close();
  event.waitUntil(
    clients.openWindow(event.notification.data.url)
  );
});

Step 8. Admin subscription JavaScript

Save as myproject/static/admin/js/push-subscribe.js:

(function () {
  "use strict";

  // Injected by the Django template override in Part 9.
  const VAPID_PUBLIC_KEY = window.VAPID_PUBLIC_KEY;
  const SUBSCRIBE_URL    = window.PUSH_SUBSCRIBE_URL;
  const UNSUBSCRIBE_URL  = window.PUSH_UNSUBSCRIBE_URL;
  const ADMIN_URL        = window.ADMIN_URL;

  // Tracks the endpoint last registered on the server so we can delete it even
  // when the browser subscription has already been silently revoked (e.g. user
  // cleared site data or the push subscription expired without blocking).
  const STORAGE_KEY = "pushSubscriptionEndpoint";

  // Read the CSRF token from the hidden input injected by {% csrf_token %}.
  // Do not use the cookie: this project has CSRF_USE_SESSIONS = True.
  const CSRF_TOKEN = document.querySelector("[name=csrfmiddlewaretoken]")?.value || "";

  function urlBase64ToUint8Array(base64String) {
    const padding = "=".repeat((4 - (base64String.length % 4)) % 4);
    const base64  = (base64String + padding).replace(/-/g, "+").replace(/_/g, "/");
    const rawData = atob(base64);
    return Uint8Array.from([...rawData].map((c) => c.charCodeAt(0)));
  }

  function post(url, body) {
    return fetch(url, {
      method:  "POST",
      headers: { "Content-Type": "application/json", "X-CSRFToken": CSRF_TOKEN },
      body:    JSON.stringify(body),
    });
  }

  async function syncSubscription() {
    if (!VAPID_PUBLIC_KEY) return;
    if (!("serviceWorker" in navigator) || !("PushManager" in window)) return;

    const registration = await navigator.serviceWorker.register(
      "/" + ADMIN_URL + "sw.js",
      { scope: "/" + ADMIN_URL }
    );
    await navigator.serviceWorker.ready;

    const storedEndpoint = localStorage.getItem(STORAGE_KEY);
    const existing = await registration.pushManager.getSubscription();

    // The browser subscription was revoked (user blocked notifications, cleared
    // site data, or the subscription expired) but the server record still exists
    // — delete it using the endpoint we stored at subscription time.
    if (storedEndpoint && (!existing || existing.endpoint !== storedEndpoint)) {
      await post(UNSUBSCRIBE_URL, { endpoint: storedEndpoint });
      localStorage.removeItem(STORAGE_KEY);
    }

    // Already subscribed and the server already knows about this endpoint.
    if (existing && existing.endpoint === storedEndpoint) return;

    const permission = await Notification.requestPermission();
    if (permission !== "granted") return;

    const subscription = await registration.pushManager.subscribe({
      userVisibleOnly:      true,
      applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC_KEY),
    });

    await post(SUBSCRIBE_URL, subscription.toJSON());
    localStorage.setItem(STORAGE_KEY, subscription.endpoint);
  }

  document.addEventListener("DOMContentLoaded", syncSubscription);
})();

localStorage is the key to reliable unsubscription. Notification.permission alone cannot detect silent revocations — when a user clears site data or a push subscription expires, the permission may still read "granted" while the browser-side subscription is gone. By storing the endpoint at subscribe time and comparing it on every page load, the script can call UNSUBSCRIBE_URL with the old endpoint even after the browser subscription object has disappeared.

Step 9. Context processor

A context processor injects the VAPID globals into every admin template response.

Create myproject/apps/notifications/context_processors.py:

from django.conf import settings
from django.urls import reverse


def push_notifications(request):
    """Inject push-notification globals into every admin page."""

    if not request.path.startswith(f"/{settings.ADMIN_URL}"):
        return {}

    if not settings.VAPID_PUBLIC_KEY:
        return {}

    return {
        "push_vapid_public_key": settings.VAPID_PUBLIC_KEY,
        "push_subscribe_url": reverse("notifications:push_subscribe"),
        "push_unsubscribe_url": reverse("notifications:push_unsubscribe"),
        "push_admin_url": settings.ADMIN_URL,
    }

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [
            os.path.join(BASE_DIR, "myproject", "templates"),
        ],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                # ...
                "myproject.apps.notifications.context_processors.push_notification_settings",
            ],
        },
    },
]

Step 10. Inject globals via admin/base_site.html

Override myproject/templates/admin/base_site.html. If one already exists, add the extrahead block; otherwise create the file extending Django's built-in template:

{% extends "admin/base_site.html" %}
{% load static %}

{% block extrahead %}
  {# ... any existing content such as a favicon include ... #}
  {% if push_vapid_public_key %}
    {% csrf_token %}
    <script nonce="{{ request.csp_nonce }}">
      window.VAPID_PUBLIC_KEY = "{{ push_vapid_public_key }}";
      window.PUSH_SUBSCRIBE_URL =  "{{ push_subscribe_url }}";
      window.PUSH_UNSUBSCRIBE_URL = "{{ push_unsubscribe_url }}";
      window.ADMIN_URL = "{{ push_admin_url }}";
    </script>
    <script src="{% static 'admin/js/push-subscribe.js' %}"></script>
  {% endif %}
{% endblock %}

Step 11. Huey task

# myproject/apps/feedback/tasks.py
import json

from django.conf import settings
from django.urls import reverse
from huey.contrib.djhuey import db_task


@db_task()
def send_feedback_push_notification(feedback_message_id):
    from pywebpush import webpush, WebPushException

    from feedback.models import FeedbackMessage
    from notifications.models import PushSubscription

    private_key = settings.VAPID_PRIVATE_KEY
    if not private_key:
        return

    if not (message := FeedbackMessage.objects.filter(
        pk=feedback_message_id
    ).first()):
        return

    admin_url = settings.WEBSITE_URL + reverse(
        "admin:feedback_feedbackmessage_change",
        args=(message.pk,)
    )
    content = message.content
    body = content[:120] + (
        "..." if len(content) > 120 else ""
    )
    payload = json.dumps({
        "title": f"{message.submitter_name}:",
        "body":  body,
        "url":   admin_url,
    })

    dead_endpoints = []
    for sub in PushSubscription.objects.all():
        try:
            webpush(
                subscription_info={
                    "endpoint": sub.endpoint,
                    "keys": {"p256dh": sub.p256dh, "auth": sub.auth},
                },
                data=payload,
                vapid_private_key=private_key,
                vapid_claims={"sub": f"mailto:{settings.VAPID_ADMIN_EMAIL}"},
            )
        except WebPushException as exc:
            # 410 Gone / 404 Not Found means the subscription has expired
            if exc.response is not None and exc.response.status_code in (404, 410):
                dead_endpoints.append(sub.endpoint)

    if dead_endpoints:
        PushSubscription.objects.filter(
            endpoint__in=dead_endpoints,
        ).delete()

The Huey task is already called from the view in feedback app via transaction.on_commit. Using
on_commit ensures the task is only queued after the database row is fully committed, so the task always finds the message when it runs.

Step 12. Content Security Policy

If the project uses Django CSP, two directives need adjusting:

CSP_WORKER_SRC  = ["'self'"]   # allows service worker registration from this origin
CSP_CONNECT_SRC = ["'self'"]   # allows the subscribe POST fetch

The pywebpush HTTP call to the external push service (FCM, Mozilla) runs server-side
inside the Huey worker process and is not subject to the browser's CSP.

User experience

It' safest to keep the body of the message up to 120 characters long - the rest will likely be cut on different OSes or browsers.

You can check the current status of notification permissions by:

Notification.permission // should be "granted", not "default" or "denied"

Based on that you can write a specific message in the User Interface what to do if the permission has been denied.

If you have many different types of notifications, you would set the configuration in a Django website. And let the visitor subscribe to the notifications in the browser once. Then your Huey tasks would check the notification settings and trigger send according messages to the subscribers.

For example, for DjangoTricks website, I would allow subscribing to new tricks, blog posts, and goodies in the notification configuration, and the visitors would grant permission to Web Push notifications just once.

Privacy and security

Messages themselves are stored on the Web Push servers encrypted, but back in the OS they are shown in plain text, and can be seen by people standing behind the user or possibly read out by other apps (or viruses) which have permissions to access OS notifications.

Practical recommendations for sensitive content:

Send a generic notification ("You have a new message") and make the user open the app to see the actual content — this is what most banking/healthcare apps do.
If you do include content, keep it minimal — avoid full message text, Personally Identifiable Information (PII), medical info, etc.
Make sure your VAPID keys are securely stored and rotated if compromised.
Set a short TTL (time-to-live) on the push message so it doesn't sit on Google's servers long if the device is offline.

For anything regulated (HIPAA, GDPR, financial data), the safest approach is the generic notification pattern, since you have no control over how the OS handles notification display and history once it leaves the browser.

OS permissions

For notification receivers, the permissions can be denied for the Browser globally as well.

One can set or unset them on MacOS at Settings ➔ Notifications ➔ Google Chrome (or another browser analogically) or on Windows at Focus Assist / Notification settings.

Marketing perspective

Opt-in: When asking for push notifications without context, only 5–25% would grant the permission. If the permission is asked in the UI at first and the reason is given, about 60% would grant the permission.

Opt-out: On average, nearly 8–10% of subscribers opt out from web push notifications per year. Even just 1 push notification per week leads to 10% of users disabling notifications. 46% of users disable notifications if they receive more than 6 notifications.

Final words

The technique of Web Push is not trivial, but with the help of py-vapid and pywebpush, it becomes manageable. The best use cases for push notifications are those where a SaaS project or a web platform suggests to use this technique intentionally: when waiting for something to happen, such as a new comment, a reply to a message, a new task to do from another person, or a new post of a favorite author who writes irregularly.

Cover picture by cottonbro studio

Improving First Byte and Contentful Paint on a Django Website

Aidas Bendoraitis — Mon, 11 May 2026 11:03:25 +0000

Recently I have been experimenting with http streaming and realized how it can improve page performance. If you come from the PHP world, you might know the command flush(). It immediately sends to the visitor what has been echoed to the buffer, and doesn't wait for the full page to be rendered on the server side. That allows the browser to start rendering the website before the whole document is rendered on the server and transferred. On the other hand, the usual Django HttpResponse renders the whole HTML document on the server first, and only then sends it to the visitor. So the initial HTML document rendering is always the bottleneck for the full page load. Here comes StreamingHttpResponse, which can be used to mimic what flush() does in PHP.

`HttpResponse` vs. `StreamingHttpResponse` in Action

When using a normal HttpResponse, the HTML document is first rendered on the server side, then sent to the browser, then static files are downloaded in parallel if possible, and lastly rendering in the browser happens.

When you use StreamingHttpResponse, you can send the <head> and the content above the fold as the first part of the document, so that static files can be located and start downloading while the rest of the HTML document is being sent in parts. The first paint of the document would happen just after the CSS file is downloaded, and the rest of the HTML document would be drawn at a later point.

Generic HTML Streaming View

Here is a generic HTMLStreamingView that expects a list of template files, get_document_context_data() for the global context, and get_template_context_data() for the template-specific context:

from django.http.response import StreamingHttpResponse
from django.conf import settings
from django.template.loader import render_to_string
from django.views.generic.base import View


class HTMLStreamingView(View):
    # templates for different parts of the document
    template_names = []  
    extra_context = None

    def get(self, request, *args, **kwargs):
        # Capture the nonce before StreamingHttpResponse is returned. 
        # CSP middleware writes the nonce into the response header during
        # process_response, then replaces request.csp_nonce with 
        # an error-raising lazy object. generate() restores the plain value
        # so templates can access it during streaming.
        self._csp_nonce = (
            str(request.csp_nonce)
            if hasattr(request, "csp_nonce") 
            else None
        )
        context = self.get_document_context_data(**kwargs)
        return StreamingHttpResponse(
            self.generate(context), 
            content_type="text/html"
        )

    def generate(self, context):
        if self._csp_nonce is not None:
            self.request.csp_nonce = self._csp_nonce
        for template_name in self.template_names:
            template_context = {
                **context, 
                **self.get_template_context_data(template_name)
            }
            yield render_to_string(
                template_name, 
                template_context, 
                request=self.request
            )

    def get_document_context_data(self, **kwargs):
        kwargs.setdefault("view", self)
        if self.extra_context is not None:
            kwargs.update(self.extra_context)
        return kwargs

    def get_template_context_data(self, template_name, **kwargs):
        return {}

Use Case with the Strategic Prioritizer "1st things 1st"

The start page of the decision support system and strategic prioritizer 1st things 1st has been implemented as a multi-section landing page. The cookie consent widget only showed up after the whole page had rendered, resulting in a delay of a few seconds.

This is how I used HTMLStreamingView to reorganize the page into parts:

class StartPageView(HTMLStreamingView):
    template_names = [
        "startpage_index_top.html",
        "startpage/includes/description.html",
        "startpage/includes/tutorial.html",
        "startpage/includes/benefits.html",
        "startpage/includes/social_proof.html",
        "startpage/includes/testimonials.html",
        "startpage/includes/about_us.html",
        "startpage/includes/questions_and_answers.html",
        "startpage/includes/pricing.html",
        "startpage/includes/cause.html",
        "startpage/includes/call_to_action.html",
        "startpage/includes/footer.html",
        "startpage_index_bottom.html",
    ]

    def get_template_context_data(self, template_name, *args, **kwargs):
        if template_name == "startpage_index_top.html":
            return {
                "structured_data": settings.JSON_LD_STRUCTURED_DATA,
            }
        if template_name == "startpage/includes/social_proof.html":
            from django.contrib.auth import get_user_model

            User = get_user_model()
            return {
                "active_user_count": User.objects.filter(is_active=True).count(),
            }
        ...

        return super().get_template_context_data(template_name, **kwargs)

To transform a normal Django view into an HTTP streaming view, I cut the base.html template into two pieces:

everything before {% block content %} as base_top.html — the head and content above the fold.
everything after {% endblock content %} as base_bottom.html — the closing HTML tags and the footer.

For example, here's base_top.html:

<!DOCTYPE html>
{% load static %}
<html lang="en">
<head>
    <meta charset="utf-8" />
    <title>{% block title %}1st things 1st{% endblock %}</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="stylesheet" href="{% static 'css/styles.css' %}" />
    {% block extra_head %}{% endblock %}
</head>
<body>
    {% block top_navigation %}
        <nav>
            <a href="/">Logo</a>
        </nav>
    {% endblock %}
    <main id="main_content">
    {% block content %}{% endblock %}
    {% include "startpage/includes/extra_js.html" %}

And here is base_bottom.html:

    {% block content %}{% endblock %}
    </main>
    <footer>
        ...
    </footer>
</body>
</html>

I moved the JS from base_bottom.html to the body section of base_top.html, where it will start downloading immediately after the content above the fold is shown. I did that to reduce the delay for the cookie consent widget.

Then I prepared the templates for all parts of the start page:

startpage_index_top.html extends base_top.html
content templates provide the HTML directly without extending anything.
startpage_index_bottom.html extends base_bottom.html.

The Optimization Results

I used the Lighthouse plugin to measure performance for the start page on an emulated slow mobile network, before and after applying StreamingHttpResponse.

In the updated version, the content above the fold and the static files needed to render it are retrieved earlier. These include the static file requirements for the cookie consent widget, which can now be loaded from the initial part of the stream, so the widget appears sooner.

Final Words

HTTP streaming is a relatively simple technique that can make a noticeable difference in perceived page performance, particularly when it comes to metrics like First Byte and Contentful Paint. By sending the top of the document early, the browser can begin fetching static assets and rendering above-the-fold content while the server is still working on the rest of the page.

A faster Time To First Byte (TTFB) is also worth considering for LLM crawlers such as GPTBot or ClaudeBot. These bots often work with short timeouts, and if your server doesn't respond quickly enough, they may abandon the request before reading your content. HTTP streaming helps here too, since it gets the most important parts of your HTML out early — right at the top of the document where crawlers are most likely to see them.

That said, it does require splitting your templates into parts and thinking more carefully about which context data is needed where. If your page is lightweight and fast to render, the added complexity probably isn't worth it. The technique really shines on heavier pages that involve bigger database queries or external API calls — those are exactly the cases where server-side delay is most significant, and where streaming can therefore have the greatest impact.

It is also worth noting that HTTP streaming works with both WSGI and ASGI, so it fits into most standard Django deployment setups without requiring any major infrastructure changes.

Thanks to Famitsay Tamayo for the cover photo!

Wagtail Routable Pages and Layout Configuration

Aidas Bendoraitis — Sat, 21 Mar 2026 11:07:32 +0000

If you are familiar with Wagtail CMS for Django, you know that you can create Wagtail pages and control their content and layout with blocks inside of stream fields. But what if you have entries coming from normal Django models through a routable page? In this article, I will explore how you can control the dynamic layout of a detail view in a routable page.

Routable pages in Wagtail are dynamic pages of your CMS page tree that can have their own URL subpaths and views. You can use them for filtered list and detail views, multi-step forms, multiple formats for the same data, etc. Here I will show you a routable ArticleIndexPage with a list and detail views for Article instances rendering the detail views based on the block layout in a detail_layout stream field.

1. Project Setup

Create a Wagtail project myproject and articles app:

pip install wagtail
wagtail start myproject
cd myproject
python manage.py startapp articles

Add to INSTALLED_APPS in your Django project settings:

INSTALLED_APPS = [
    ...
    "wagtail.contrib.routable_page",  # required for RoutablePage
    "myproject.apps.articles",
]

2. File Structure

The articles app:

myproject/apps/articles/
├── __init__.py
├── apps.py
├── models.py          # Article, Category, ArticleIndexPage
├── blocks.py          # All StreamField block definitions
└── admin.py           # Register Article and Category in Django admin

The articles templates:

myproject/templates/articles/
├── article_list.html           # List view
├── article_detail.html         # Detail view
└── blocks/
    ├── cover_image_block.html
    ├── description_block.html
    └── related_articles_block.html

3. Models

`myproject/apps/articles/models.py`

Create the Category and Article Django models, and the ArticleIndexPage routable Wagtail page with article list and detail views:

from django.core.paginator import EmptyPage, PageNotAnInteger, Paginator
from django.db import models
from django.shortcuts import get_object_or_404
from django.utils.translation import gettext_lazy as _

from wagtail.admin.panels import FieldPanel, ObjectList, TabbedInterface
from wagtail.contrib.routable_page.models import RoutablePageMixin, path
from wagtail.fields import StreamField
from wagtail.models import Page

from .blocks import article_detail_layout_blocks


class Category(models.Model):
    name = models.CharField(max_length=100, verbose_name=_("name"))
    slug = models.SlugField(unique=True, verbose_name=_("slug"))

    class Meta:
        verbose_name = _("category")
        verbose_name_plural = _("categories")

    def __str__(self):
        return self.name


class Article(models.Model):
    title = models.CharField(max_length=255, verbose_name=_("title"))
    slug = models.SlugField(unique=True, verbose_name=_("slug"))
    category = models.ForeignKey(
        Category,
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
        related_name="articles",
        verbose_name=_("category"),
    )
    cover_image = models.ForeignKey(
        "wagtailimages.Image",
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
        related_name="+",
        verbose_name=_("cover image"),
    )
    description = models.TextField(blank=True, verbose_name=_("description"))
    created_at = models.DateTimeField(auto_now_add=True, verbose_name=_("created at"))

    class Meta:
        verbose_name = _("article")
        verbose_name_plural = _("articles")

    def __str__(self):
        return self.title


class ArticleIndexPage(RoutablePageMixin, Page):
    """
    A single Wagtail page that owns:
      - /articles/          → paginated list of all Articles
      - /articles/<slug>/   → detail view for one Article

    The StreamField is edited once in the Wagtail admin and
    defines the layout for every detail view.
    """

    articles_per_page = models.IntegerField(default=10, verbose_name=_("articles per page"))

    detail_layout = StreamField(
        article_detail_layout_blocks(),
        blank=True,
        use_json_field=True,
        verbose_name=_("detail layout"),
        help_text=_(
            "Configure the layout for all article detail pages. "
            "Add, remove, and reorder blocks to change what appears "
            "on every article detail view."
        ),
    )

    # TabbedInterface gives List View and Detail View their own tabs.
    # promote_panels and settings_panels must be added explicitly here
    # because edit_handler takes full ownership of the admin UI structure.
    edit_handler = TabbedInterface([
        ObjectList(Page.content_panels + [FieldPanel("articles_per_page")], heading=_("List View")),
        ObjectList([FieldPanel("detail_layout")], heading=_("Detail View")),
        ObjectList(Page.promote_panels, heading=_("SEO / Promote")),
        ObjectList(Page.settings_panels, heading=_("Settings")),
    ])

    class Meta:
        verbose_name = _("article index page")
        verbose_name_plural = _("article index pages")

    @path("")
    def article_list(self, request):
        all_articles = Article.objects.select_related("category", "cover_image").order_by("-created_at")
        paginator = Paginator(all_articles, self.articles_per_page)
        page_number = request.GET.get("page")

        try:
            articles = paginator.page(page_number)
        except PageNotAnInteger:
            articles = paginator.page(1)
        except EmptyPage:
            articles = paginator.page(paginator.num_pages)

        return self.render(
            request,
            context_overrides={"articles": articles, "paginator": paginator},
            template="articles/article_list.html",
        )

    @path("<slug:article_slug>/")
    def article_detail(self, request, article_slug):
        article = get_object_or_404(
            Article.objects.select_related("category", "cover_image"),
            slug=article_slug,
        )
        return self.render(
            request,
            context_overrides={"article": article},
            template="articles/article_detail.html",
        )

4. StreamField Blocks

`myproject/apps/articles/blocks.py`

Create Wagtail stream-field blocks for the cover image, description, and the related articles of an actual article. Each block can have some settings on how to represent the content of the block.

from django.utils.translation import gettext_lazy as _

from wagtail import blocks


class CoverImageBlock(blocks.StructBlock):
    aspect_ratio = blocks.ChoiceBlock(
        choices=[
            ("16-9", _("16:9 Widescreen")),
            ("4-3", _("4:3 Standard")),
            ("1-1", _("1:1 Square")),
            ("3-1", _("3:1 Banner")),
        ],
        default="16-9",
        label=_("Aspect ratio"),
        help_text=_("Controls the cropping of the cover image."),
    )

    class Meta:
        template = "articles/blocks/cover_image_block.html"
        icon = "image"
        label = _("Cover Image")


class DescriptionBlock(blocks.StructBlock):
    max_lines = blocks.IntegerBlock(
        min_value=0,
        default=0,
        label=_("Maximum lines"),
        help_text=_("Clamp the description to this many lines. Set to 0 to show all."),
        required=False,
    )

    class Meta:
        template = "articles/blocks/description_block.html"
        icon = "pilcrow"
        label = _("Description")


class RelatedArticlesBlock(blocks.StructBlock):
    sort_order = blocks.ChoiceBlock(
        choices=[
            ("newest", _("Newest first")),
            ("oldest", _("Oldest first")),
            ("title_asc", _("Title A → Z")),
            ("title_desc", _("Title Z → A")),
        ],
        default="newest",
        label=_("Sort order"),
        help_text=_("Order in which related articles are listed."),
    )

    def get_context(self, value, parent_context=None):
        context = super().get_context(value, parent_context=parent_context)
        article = (parent_context or {}).get("article")
        if not article or not article.category_id:
            context["related_articles"] = []
            return context

        from .models import Article

        sort_map = {
            "newest": "-created_at",
            "oldest": "created_at",
            "title_asc": "title",
            "title_desc": "-title",
        }

        context["related_articles"] = (
            Article.objects.select_related("category", "cover_image")
            .filter(category=article.category)
            .exclude(pk=article.pk)
            .order_by(sort_map.get(value["sort_order"], "-created_at"))[:3]
        )
        return context

    class Meta:
        template = "articles/blocks/related_articles_block.html"
        icon = "list-ul"
        label = _("Related Articles")


def article_detail_layout_blocks():
    """
    Returns the list of (name, block) tuples used in ArticleIndexPage.detail_layout.
    Defined as a function so models.py can import it without circular issues.
    """
    return [
        ("cover_image", CoverImageBlock()),
        ("description", DescriptionBlock()),
        ("related_articles", RelatedArticlesBlock()),
    ]

The RelatedArticlesBlock here also has a customized context where we pass related_articles variable with 3 other articles of the same category sorted by the sorting order defined in the block.

5. Templates

`articles/article_list.html`

This will be the template for the paginated article list. Later you could augment it with a search form and filters.

{% extends "base.html" %}
{% load wagtailcore_tags wagtailimages_tags i18n wagtailroutablepage_tags %}

{% block content %}
<main class="article-index">
  <h1>{{ page.title }}</h1>
  <ul class="article-list">
    {% for article in articles %}
      <li class="article-card">
        {% if article.cover_image %}{% image article.cover_image width-400 as img %}
          <img src="{{ img.url }}" alt="{{ article.title }}">
        {% endif %}
        <h2>
          <a href="{% routablepageurl page "article_detail" article.slug %}">{{ article.title }}</a>
        </h2>
        {% if article.category %}<span class="badge">{{ article.category.name }}</span>{% endif %}
        <p>{{ article.description|truncatewords:30 }}</p>
      </li>
    {% empty %}
      <li>{% trans "No articles yet." %}</li>
    {% endfor %}
  </ul>
  {% if articles.has_other_pages %}
    <nav class="pagination" aria-label="{% trans 'Article pagination' %}">
      {% if articles.has_previous %}
        <a href="?page={{ articles.previous_page_number }}">{% trans "← Previous" %}</a>
      {% endif %}
      <span>{% blocktrans with num=articles.number total=articles.paginator.num_pages %}Page {{ num }} of {{ total }}{% endblocktrans %}</span>
      {% if articles.has_next %}
        <a href="?page={{ articles.next_page_number }}">{% trans "Next →" %}</a>
      {% endif %}
    </nav>
  {% endif %}
</main>
{% endblock %}

`articles/article_detail.html`

The detail page would use the {% include_block page.detail_layout with article=article page=page %} to pass the article to the context of each block:

{% extends "base.html" %}
{% load i18n wagtailcore_tags wagtailroutablepage_tags %}

{% block content %}
<article class="article-detail">
  <header>
    <h1>{{ article.title }}</h1>
    {% if article.category %}<span class="badge">{{ article.category.name }}</span>{% endif %}
  </header>
  {% include_block page.detail_layout with article=article page=page %}
  <p>
    <a href="{% routablepageurl page "article_list" %}">{% trans "← Back to all articles" %}</a>
  </p>
</article>
{% endblock %}

`articles/blocks/cover_image_block.html`

Cover image block would show the article cover image with the aspect ratio set in the block:

{% load wagtailimages_tags %}

{% if article.cover_image %}
  <div class="cover-image cover-image--{{ value.aspect_ratio }}">
    {% image article.cover_image width-1200 as img %}
    <img src="{{ img.url }}" alt="{{ article.title }}">
  </div>
{% endif %}

`articles/blocks/description_block.html`

Description block would hide the article description text overflow based on the max lines set in the block:

<section class="article-description">
  <p{% if value.max_lines > 0 %} class="line-clamp" style="-webkit-line-clamp: {{ value.max_lines }};"{% endif %}>
    {{ article.description }}
  </p>
</section>

`articles/blocks/related_articles_block.html`

The related articles block would list the related articles as defined in the extra context of the block:

{% load i18n wagtailimages_tags wagtailroutablepage_tags %}

{% if related_articles %}
  <section class="related-articles">
    <h2>{% trans "Related Articles" %}</h2>
    <ul class="related-articles__list">
      {% for rel in related_articles %}
        <li class="related-card">
          {% if rel.cover_image %}{% image rel.cover_image width-400 as img %}
            <img src="{{ img.url }}" alt="{{ rel.title }}">
          {% endif %}
          <div class="related-card__body">
            {% if rel.category %}<span class="badge">{{ rel.category.name }}</span>{% endif %}
            <h3>
              <a href="{% routablepageurl page "article_detail" rel.slug %}">{{ rel.title }}</a>
            </h3>
            <p>{{ rel.description|truncatewords:20 }}</p>
          </div>
        </li>
      {% endfor %}
    </ul>
  </section>
{% endif %}

6. Django Admin Registration

`articles/admin.py`

Let's not forget to register admin views for the categories and articles so that we can add some data there:

from django.contrib import admin
from .models import Article, Category


@admin.register(Category)
class CategoryAdmin(admin.ModelAdmin):
    list_display = ("name", "slug")
    prepopulated_fields = {"slug": ("name",)}


@admin.register(Article)
class ArticleAdmin(admin.ModelAdmin):
    list_display = ("title", "category", "created_at")
    list_filter = ("category",)
    search_fields = ("title", "description")
    prepopulated_fields = {"slug": ("title",)}

7. Migrations and Initial Data

python manage.py makemigrations articles
python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

8. Wagtail Admin Setup

Open http://localhost:8000/cms/ and log in.
In the Pages explorer, create an Article Index Page as a child of the root page.
- Set the Slug to articles.
On the List View tab, set Articles per page (e.g. 24).
On the Detail View tab, open the Detail Layout StreamField and add blocks in your preferred order:
- Cover Image — choose an aspect ratio.
- Description — optionally set a maximum line count to clamp long descriptions.
- Related Articles — choose the sort order for the three related articles shown.
Publish the page.
In the Django admin (/django-admin/), create some Categories and Articles with cover images and descriptions.
Visit http://localhost:8000/articles/ for the paginated list.
Click any article to see the detail view rendered using the StreamField layout you configured in step 4.

Final words

Using stream fields we can render not only editorial content, for example, images or rich-text descriptions, but also dynamic content based on values from other models and/or the context of the given template.

The approach illustrated in this article allows us to create Wagtail pages where content editors have freedom to adjust the layouts of the pages or insert blocks, such as ads or info texts, into specific places based on real-time events.

How to Show a Waitlist Until Your Wagtail Site Is Ready

Aidas Bendoraitis — Sat, 21 Mar 2026 11:02:14 +0000

This year, I want to bring my centralized gamified donation platform www.make-impact.org to life (at least technically). Earlier I had the version I was developing separate from the waiting list, but I decided to merge them and have a switch between the waitlist and an early preview.

This allows me to have no data duplication, the possibility to create user accounts immediately, and saves hosting and maintenance costs.

This guide walks through a pattern that lets you ship a temporary waitlist page while your Wagtail site is still being built, with the ability to show your progress to chosen people. If you are building a Software as a Service (SaaS) or a web platform with Django, this article is for you.

The Concept

A custom start page view will check for a specific cookie value. If it is unset, the visitor will be redirected to a waitlist form at /waitlist/. If it is set, the visitor will be served the Wagtail home page.

All views under development will have a decorator that checks the cookie value and redirects to the start page if it is unset.

There will be a special view at /preview-access/ with a passphrase form that allows the visitor to gain preview access by setting the mentioned cookie. This view will also allow preview access to be deactivated.

These are the steps to implement this:

1. Generate and store two secrets

You will need two secret values, either set manually or generated with a cryptographically secure random generator (e.g. Python's secrets module):

PREVIEW_ACCESS_PASSPHRASE — the human-readable passphrase typed into the form. Share this with the people who need site access.
PREVIEW_ACCESS_TOKEN — the opaque random value stored in the cookie. Never exposed to users; only the server compares against it.

>>> import secrets
>>> print(secrets.token_urlsafe(16))  # passphrase
dI5nGNftZOBx8m-r0m6glg
>>> print(secrets.token_hex(32))      # cookie token
c1b7a76e3ad5cbfb1657fa4e9885a3c8baa6a5a869f49a136abd0e873a9be9ee

Add both to environment variables or a secrets file untracked by Git, and load them in the Django project settings:

# myproject/settings/_base.py
PREVIEW_ACCESS_PASSPHRASE = get_secret("PREVIEW_ACCESS_PASSPHRASE")
PREVIEW_ACCESS_TOKEN = get_secret("PREVIEW_ACCESS_TOKEN")

The get_secret() here is my custom function to retrieve a secret from the secrets source.

2. Create the access-control decorator

Create myproject/apps/misc/decorators.py. Every protected view will import from here.

# myproject/apps/misc/decorators.py
from functools import wraps

from django.conf import settings
from django.shortcuts import redirect


def preview_access_required(view_func):
    @wraps(view_func)
    def wrapper(request, *args, **kwargs):
        if request.COOKIES.get("preview_access") == settings.PREVIEW_ACCESS_TOKEN:
            return view_func(request, *args, **kwargs)
        return redirect("misc:home_page")
    return wrapper

The decorator compares the cookie against the opaque unguessable token from settings, so unless the token value is known, a random attacker cannot gain access by setting the cookie manually in DevTools.

3. Create the passphrase form

Create myproject/apps/misc/forms.py. The form will have a single required password field. Validation will reject any value that does not match the setting.

# myproject/apps/misc/forms.py
from django import forms
from django.conf import settings
from django.utils.translation import gettext_lazy as _


class PreviewAccessForm(forms.Form):
    passphrase = forms.CharField(
        label=_("Passphrase"),
        widget=forms.PasswordInput(
            attrs={"autocomplete": "current-password"}
        ),
        required=True,
    )

    def clean_passphrase(self):
        value = self.cleaned_data["passphrase"]
        if value != settings.PREVIEW_ACCESS_PASSPHRASE:
            raise forms.ValidationError(
                _("Incorrect passphrase.")
            )
        return value

4. Build the cookie toggle view

Point your browser to /preview-access/. When access is off it shows a passphrase form; when access is on it shows a disable button.

# myproject/apps/misc/views.py
from django.conf import settings
from django.shortcuts import redirect, render

from .forms import PreviewAccessForm


def preview_access(request):
    has_access = request.COOKIES.get("preview_access") == settings.PREVIEW_ACCESS_TOKEN

    if request.method == "POST":
        if has_access:
            response = redirect("misc:home_page")
            response.delete_cookie("preview_access")
            return response

        form = PreviewAccessForm(request.POST)
        if form.is_valid():
            response = redirect("misc:home_page")
            response.set_cookie(
                "preview_access",
                settings.PREVIEW_ACCESS_TOKEN,
                httponly=True,
                samesite="Strict",
            )
            return response
    else:
        form = PreviewAccessForm()

    return render(
        request, 
        "preview_access/preview_access.html", 
        {"has_access": has_access, "form": form}
    )

Key points:

Disabling never requires the passphrase — the cookie is already proof of prior access.
The cookie is set with httponly=True (not readable by JavaScript) and samesite="Strict" (not sent on cross-site requests).
The cookie value is the opaque token, not "1", so it cannot be guessed.

The template renders the passphrase input only when not has_access, and shows field-level errors from the form if the passphrase is wrong.

5. Wrap the Wagtail catch-all with the decorator

Replace the default Wagtail catch-all route handler with a thin wrapper that enforces the same cookie check.

# myproject/apps/misc/views.py
from myproject.apps.misc.decorators import preview_access_required
from wagtail.views import serve as wagtail_serve


@preview_access_required
def serve_wagtail_page(request, path=""):
    return wagtail_serve(request, path)

Without this, a visitor who knows any Wagtail page URL could bypass the gate by typing it directly into the browser.

6. Build the proxy home page view

This view is the only entry point to the site. It decides what every visitor sees first.

# myproject/apps/misc/views.py
from django.conf import settings

from wagtail.models import Site
from wagtail.views import serve as wagtail_serve


def home_page(request):
    if request.COOKIES.get("preview_access") == settings.PREVIEW_ACCESS_TOKEN:
        # serve Wagtail directly
        site = Site.find_for_request(request)
        return wagtail_serve(request, "")  

    # redirect to waiting list
    return redirect("waiting_list")

Key point: the waiting_list view and a Wagtail Site and page must exist and be matched to the request domain before wagtail_serve is called.

7. Wire up the URLs

Django project URL rules:

# myproject/urls.py
from django.conf.urls.i18n import i18n_patterns
from django.urls import re_path

from wagtail.coreutils import WAGTAIL_APPEND_SLASH

from myproject.apps.misc import views as misc_views

if WAGTAIL_APPEND_SLASH:
    wagtail_serve_pattern = r"^((?:[\w\-]+/)*)$"
else:
    wagtail_serve_pattern = r"^([\w\-/]*)$"

urlpatterns += i18n_patterns(
    # ... all your other app URLs above ...

    # Catch-all — must be last
    re_path(
        wagtail_serve_pattern,
        misc_views.serve_wagtail_page,
        name="wagtail_serve"
    ),
)

The misc app URLs:

# myproject/apps/misc/urls.py
from django.urls import path

from . import views

app_name = "misc"

urlpatterns = [
    path("", views.home_page, name="home_page"),
    path("preview-access/", views.preview_access, name="preview_access"),
]

The waiting_list app URLs:

# myproject/apps/waiting_list/urls.py
from django.urls import path

from . import views

urlpatterns = [
    path("waitlist/", views.show_waiting_list_form, name="waiting_list"),
]

8. Protect every other app view

Import and apply @preview_access_required to every view that belongs to the real site. Class-based views can be wrapped at assignment time:

from myproject.apps.misc.decorators import preview_access_required

# Function-based view
@preview_access_required
def event_list(request): 
    ...

# Class-based view
event_list = preview_access_required(
    EventListView.as_view()
)

Waiting-list views, API views, social authentication views, and static/legal pages (/imprint/, /privacy/, etc.) must not receive this decorator — they need to remain publicly accessible.

Final words

You get a lot of benefits from this setup. The waitlist measures demand for your website while you are still building. Invited test users can evaluate your progress at any time. While you are developing the website, you do not necessarily need multiple servers. Launching later is also easier — no hassle or delays with domain IP updates and SSL certificates.

Using tox to Test a Django App Across Multiple Django Versions

Aidas Bendoraitis — Fri, 27 Feb 2026 18:53:25 +0000

Recently, I developed a reusable Django app django-clearplaintext for normalizing plain text in Django templates. And to package and test it properly, I had a fresh look at Tox.

Tox is the standard testing tool that creates isolated virtual environments, installs the exact dependencies you specify, and runs your test suite in each one — all from a single command.

This post walks through a complete, working setup using a minimal example app called django-shorturl.

The Example App: django-shorturl

django-shorturl is a self-contained Django app with one model and one view.

shorturl/models.py

from django.db import models
from django.utils.translation import gettext_lazy as _

class ShortLink(models.Model):
    slug = models.SlugField(_("slug"), unique=True)
    target_url = models.URLField(_("target URL"))
    created_at = models.DateTimeField(_("created at"), auto_now_add=True)

    class Meta:
        verbose_name = _("short link")
        verbose_name_plural = _("short links")

    def __str__(self):
        return self.slug

shorturl/views.py

from django.shortcuts import get_object_or_404, redirect

from .models import ShortLink

def redirect_link(request, slug):
    link = get_object_or_404(ShortLink, slug=slug)
    return redirect(link.target_url)

shorturl/urls.py

from django.urls import path

from . import views

urlpatterns = [
    path("<slug:slug>/", views.redirect_link, name="redirect_link"),
]

shorturl/admin.py

from django.contrib import admin
from .models import ShortLink

admin.site.register(ShortLink)

Project Layout

django-shorturl/
├── src/
│   └── shorturl/
│       ├── __init__.py
│       ├── admin.py
│       ├── models.py
│       ├── views.py
│       └── urls.py
├── tests/
│   ├── __init__.py
│   └── test_views.py
├── pyproject.toml
├── test_settings.py
└── tox.ini

The source lives under src/ and the tests are at the top level, separate from the package. This separation prevents the tests from accidentally being shipped inside the installed package.

Packaging: pyproject.toml

Tox needs a properly packaged app to install into each environment. With isolated_build = true (more on that below), Tox builds a wheel from your pyproject.toml before running any tests.

pyproject.toml

[project]
name = "django-shorturl"
version = "1.0.0"
requires-python = ">=3.8"
dependencies = [
    "Django>=4.2",
]

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[tool.setuptools.packages.find]
where = ["src"]

The dependencies list here declares the runtime minimum — your app needs Django, but you don't pin a specific version because that is Tox's job during testing.

For the [build-system] section, we can also use uv_build to gain some performance improvements:

[build-system]
requires = ["uv_build >= 0.10.0, <0.11.0"]
build-backend = "uv_build"

[tool.uv.build-backend]
module-name = "shorturl"

Here module-name lets uv_build not to get confused between django-shorturl and shorturl.

Test Settings: test_settings.py

Django requires a settings module to run. As we don't have an associated project, we have to create a minimal one by defining project settings in the project's settings, create a minimal one dedicated to testing. It lives at the repo root so it's easy to point to from anywhere.

test_settings.py

SECRET_KEY = "test"

INSTALLED_APPS = [
    "shorturl",
]

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": ":memory:",
    }
}

ROOT_URLCONF = "shorturl.urls"

DEFAULT_AUTO_FIELD = "django.db.models.AutoField"

A few deliberate choices here:

SECRET_KEY = "test" — A fixed value, fine for tests, but never use this in production.
INSTALLED_APPS — Only include apps that your tests actually need. No django.contrib.admin, no auth, nothing extra.
SQLite in-memory database — ":memory:" means the database is created fresh for every test run and disappears when the process exits. No files left behind, no teardown needed, and it is fast.
ROOT_URLCONF — The test client resolves URLs through this setting. Without it, reverse() raises NoReverseMatch and the test client has no URL configuration to dispatch against. Point it at your app's urls.py.
DEFAULT_AUTO_FIELD — Suppresses Django's system check warning about the implicit primary key type. Setting it explicitly keeps the test output clean and makes the expectation clear.

The Core: tox.ini

This is where Tox is configured.

tox.ini

[tox]
envlist =
    py{38,39,310,311,312}-django42,
    py{310,311,312}-django50,
    py{310,311,312,313}-django51,
    py{310,311,312,313,314}-django52,
    py{312,313,314}-django60

isolated_build = true

[testenv]
deps =
    django42: Django>=4.2,<4.3
    django50: Django>=5.0,<5.1
    django51: Django>=5.1,<5.2
    django52: Django>=5.2,<6.0
    django60: Django>=6.0,<6.1
commands =
    python -m django test
setenv =
    DJANGO_SETTINGS_MODULE = test_settings

envlist — the matrix

py{38,39,310,311,312}-django42 is a shortcut used in Tox.

The numbers inside {} are expanded automatically. Tox combines each Python version with django42, creating 5 environments:

py38-django42
py39-django42
py310-django42
py311-django42
py312-django42

The full envlist simply lists all Python and Django combinations you want to test, so you can check that your project works in each setup.

Each part separated by a dash in an environment name is called a "factor". You can have as many factors as you like, and they can be named anything. py* factors are a convention for Python versions. Others need to be defined in the [testenv] deps section.

isolated_build = true

This tells tox to build a proper wheel from your pyproject.toml before installing into each environment. Without it, tox would try to install your package with pip install -e ., which bypasses the build system and can hide packaging bugs. With it, each environment tests the package exactly as a user would receive it after pip install django-shorturl.

deps — conditional dependencies

The django42: prefix is a Tox factor condition: the dependency on that line is only installed when the environment name contains the django42 factor. This is how a single [testenv] block handles all Django versions without needing a separate section for each one.

Tox also installs your package itself into each environment (because of isolated_build), so you don't need to list it here.

commands

commands =
    python -m django test

python -m django test is Django's built-in test runner. It discovers tests by looking for files matching test*.py under the current directory, which picks up everything in your tests/ folder automatically.

setenv

setenv =
    DJANGO_SETTINGS_MODULE = test_settings

Django refuses to run without a settings module. This environment variable tells it where to find yours. Because test_settings.py is at the repo root and tox runs from the repo root, the module name test_settings resolves correctly without any path manipulation.

Writing the Tests

Create test cases for each (critical) component of your app. For example, if you have models, views, and template tags, create tests/test_models.py, tests/test_views.py, and tests/test_templatetags.py.

tests/test_views.py

from django.test import TestCase
from django.urls import reverse

from shorturl.models import ShortLink


class RedirectLinkViewTest(TestCase):
    def setUp(self):
        ShortLink.objects.create(
            slug="dt",
            target_url="https://www.djangotricks.com",
        )

    def test_redirects_to_target_url(self):
        response = self.client.get(
            reverse(
                "redirect_link", kwargs={"slug": "dt"}
            )
        )
        self.assertRedirects(
            response,
            "https://www.djangotricks.com",
            fetch_redirect_response=False,
        )

    def test_returns_404_for_unknown_slug(self):
        response = self.client.get(
            reverse(
                "redirect_link", kwargs={"slug": "nope"}
            )
        )
        self.assertEqual(response.status_code, 404)

Installing Python Versions with pyenv

Tox needs the actual Python binaries for every version in your envlist. If you try to run tox without them installed, it will fail immediately with an InterpreterNotFound error. pyenv is the standard way to install and manage multiple Python versions side by side.

Install pyenv

Use Homebrew on macOS (or follow the official instructions for Linux):

brew install pyenv

Add the following to your shell config (~/.zshrc, ~/.bashrc, etc.) and restart your shell:

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

Install each Python version

Install every version that appears in your envlist:

pyenv install 3.8
pyenv install 3.9
pyenv install 3.10
pyenv install 3.11
pyenv install 3.12
pyenv install 3.13
pyenv install 3.14

Make them all reachable at once

Tox resolves py312 by looking for a binary named python3.12 on PATH. The trick is pyenv global, which accepts multiple versions and places all of their binaries on your PATH simultaneously:

pyenv global 3.14 3.13 3.12 3.11 3.10 3.9 3.8

List the first (the one python3 and python resolve to) and work downward. After running this, confirm every interpreter is visible:

python3.8 --version   # Python 3.8.x
python3.9 --version   # Python 3.9.x
python3.10 --version   # Python 3.10.x
python3.11 --version   # Python 3.11.x
python3.12 --version   # Python 3.12.x
python3.13 --version   # Python 3.13.x
python3.14 --version   # Python 3.14.x

Now tox can find all of them and the full matrix will run without InterpreterNotFound errors.

Running tox

Run the full matrix:

tox

Or run a single environment:

tox -e py312-django52

tox will print a summary at the end showing which environments passed and which failed.

  py38-django42: OK (3.25=setup[2.32]+cmd[0.93] seconds)
  py39-django42: OK (2.88=setup[2.16]+cmd[0.72] seconds)
  py310-django42: OK (2.61=setup[2.02]+cmd[0.59] seconds)
  py311-django42: OK (2.70=setup[2.09]+cmd[0.61] seconds)
  py312-django42: OK (3.28=setup[2.46]+cmd[0.82] seconds)
  py310-django50: OK (2.67=setup[2.09]+cmd[0.58] seconds)
  py311-django50: OK (2.61=setup[2.02]+cmd[0.59] seconds)
  py312-django50: OK (2.85=setup[2.25]+cmd[0.60] seconds)
  py310-django51: OK (2.81=setup[2.27]+cmd[0.54] seconds)
  py311-django51: OK (2.85=setup[2.30]+cmd[0.55] seconds)
  py312-django51: OK (2.70=setup[2.09]+cmd[0.61] seconds)
  py313-django51: OK (2.97=setup[2.29]+cmd[0.68] seconds)
  py310-django52: OK (3.03=setup[2.31]+cmd[0.72] seconds)
  py311-django52: OK (2.88=setup[2.22]+cmd[0.66] seconds)
  py312-django52: OK (2.80=setup[2.13]+cmd[0.67] seconds)
  py313-django52: OK (4.70=setup[3.66]+cmd[1.04] seconds)
  py314-django52: OK (6.41=setup[5.18]+cmd[1.23] seconds)
  py312-django60: OK (5.13=setup[4.06]+cmd[1.07] seconds)
  py313-django60: OK (5.35=setup[4.15]+cmd[1.21] seconds)
  py314-django60: OK (6.01=setup[4.65]+cmd[1.37] seconds)
  congratulations :) (70.59 seconds)

Final Words

What makes this setup robust?

No shared state between environments. Each Tox environment is its own virtualenv with its own Django installation.
The package is built, not symlinked. isolated_build = true catches packaging mistakes before they reach users.
The database never persists between runs. SQLite in-memory means no stale data, no cleanup scripts, no CI-specific teardown.
The test settings are minimal by design. Fewer installed apps means faster startup, fewer implicit dependencies, and tests that fail for clear, local reasons rather than configuration noise from elsewhere in the project.

This setup is not the only way to test a Django app with Tox, but it is a solid starting point that balances comprehensiveness with maintainability. With a little effort upfront, you can ensure your app works across a wide range of Python and Django versions — and catch packaging bugs before they hit real users.

Understanding the Different POST Content Types

Aidas Bendoraitis — Sun, 16 Nov 2025 23:54:35 +0000

After more than 20 years of building for the web, this topic somehow kept slipping past me. It always felt obvious, so I never looked deeper. Recently I finally took the time to explore it properly, did some quick research, and now I’m sharing the results. Here’s a simple walkthrough of the different content types you can send in POST requests.

Standard Form Data

When you submit a basic HTML form like <form method="post" action=""></form>, for example a login form, the browser sends the data using the application/x-www-form-urlencoded content type. The body of the request looks like a URL-encoded query string, the same format typically used in GET requests.

Example: username=john_doe&password=pass123.

A POST request with this content type using the fetch API looks like this:

async function sendURLEncoded() {
    const params = new URLSearchParams();
    params.append('username', 'john_doe');
    params.append('email', 'john@example.com');
    params.append('password', 'Secret123');
    params.append('bio', 'This is a multi-line\nbio text.\nIt supports newlines!');

    const response = await fetch('/api/urlencoded/', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'X-CSRFToken': getCSRFToken()
        },
        body: params
    });
    const result = await response.json();
    console.log(result);
}

On the Django side, validation with a Django form is the usual approach:

from django import forms
from django.http import JsonResponse
from django.views.decorators.http import require_http_methods
from .forms import URLEncodedForm


class URLEncodedForm(forms.Form):
    username = forms.CharField(
        max_length=150,
        required=True,
        min_length=3,
    )
    email = forms.EmailField(
        required=True,
        error_messages={
            "required": "Email is required",
            "invalid": "Please enter a valid email address",
        },
    )
    password = forms.CharField(
        required=True,
        min_length=8,
    )
    bio = forms.CharField(
        required=False,
        max_length=500,
        widget=forms.Textarea,
        error_messages={"max_length": "Bio cannot exceed 500 characters"},
    )


@require_http_methods(["POST"])
def handle_urlencoded(request):
    """Handle application/x-www-form-urlencoded requests"""
    form = URLEncodedForm(request.POST)

    if not form.is_valid():
        return JsonResponse(
            {
                "status": "error",
                "errors": form.errors,
                "content_type": request.content_type,
            },
            status=400,
        )

    return JsonResponse(
        {
            "status": "success",
            "form_data": form.cleaned_data,
            "content_type": request.content_type,
        }
    )

Form Data with Files

If your form includes file uploads, the browser switches to multipart/form-data. You enable it in HTML like this:

<form method="post" action="" enctype="multipart/form-data">

A fetch-based upload looks like:

async function sendMultipart() {
    const formData = new FormData();
    formData.append('username', 'john_doe');
    formData.append('email', 'john@example.com');

    const fileInput = document.getElementById('file-input');
    if (fileInput.files[0]) {
        formData.append('avatar', fileInput.files[0]);
    }

    const response = await fetch('/api/multipart/', {
        method: 'POST',
        headers: {
            'X-CSRFToken': getCSRFToken()
        },
        body: formData
    });
    const result = await response.json();
    console.log(result);
}

The Django view works the same way, just with request.FILES added.

from django import forms
from django.http import JsonResponse
from django.views.decorators.http import require_http_methods


class MultipartForm(forms.Form):
    username = forms.CharField(
        max_length=150,
        required=True,
        min_length=3,
    )
    email = forms.EmailField(
        required=True,
    )
    avatar = forms.FileField(
        required=False,
    )

    def clean_avatar(self):
        avatar = self.cleaned_data.get("avatar")
        if avatar:
            if avatar.size > 5 * 1024 * 1024:
                raise forms.ValidationError("File size cannot exceed 5MB")

            allowed_types = ["image/jpeg", "image/png", "image/gif", "image/webp"]
            if avatar.content_type not in allowed_types:
                raise forms.ValidationError(
                    f'Invalid file type. Allowed types: {", ".join(allowed_types)}'
                )
        return avatar



@require_http_methods(["POST"])
def handle_multipart(request):
    """Handle multipart/form-data requests (forms with files)"""
    form = MultipartForm(request.POST, request.FILES)

    if not form.is_valid():
        return JsonResponse(
            {
                "status": "error",
                "errors": form.errors,
                "content_type": request.content_type,
            },
            status=400,
        )

    form_data = {}

    for key, value in form.cleaned_data.items():
        if hasattr(value, "read"):
            form_data[key] = {
                "name": value.name,
                "size": value.size,
                "content_type": value.content_type,
            }
        else:
            form_data[key] = value

    return JsonResponse(
        {
            "status": "success",
            "form_data": form_data,
            "content_type": request.content_type,
        }
    )

JSON String

A very common modern content type is application/json. Single-Page Applications and most JavaScript-heavy frontends rely on it.

Frontend example:

async function sendJSON() {
    const data = { 
        name: "John Doe", 
        email: "john@example.com", 
        age: 30
    };
    const response = await fetch('/api/json/', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-CSRFToken': getCSRFToken()
        },
        body: JSON.stringify(data)
    });
    const result = await response.json();
    console.log(result)
}

For validation, you can use Pydantic, which is a nice alternative to Django-REST-Framework serializers.

from django.http import JsonResponse
from django.views.decorators.http import require_http_methods
from pydantic import BaseModel, EmailStr, Field, ConfigDict, ValidationError


class JSONDataSchema(BaseModel):
    model_config = ConfigDict(
        json_schema_extra={
            "example": {
                "name": "John Doe", 
                "email": "john@example.com", 
                "age": 30,
            }
        }
    )

    name: str = Field(min_length=2, max_length=100, description="User's full name")
    email: EmailStr = Field(description="Valid email address")
    age: int = Field(ge=0, le=150, description="User's age")


@require_http_methods(["POST"])
def handle_json(request):
    """Handle application/json requests"""
    try:
        data = json.loads(request.body)
        validated = JSONDataSchema(**data)

        return JsonResponse(
            {
                "status": "success",
                "received": validated.model_dump(),
                "content_type": request.content_type,
            }
        )
    except json.JSONDecodeError:
        return JsonResponse(
            {
                "status": "error",
                "error": "Invalid JSON",
                "content_type": request.content_type,
            },
            status=400,
        )
    except ValidationError as e:
        return JsonResponse(
            {
                "status": "error",
                "errors": e.errors(),
                "content_type": request.content_type,
            },
            status=400,
        )

Newline-Delimited JSON

application/x-ndjson (or simply NDJSON) is an experimental but handy format where each line is a separate JSON object. It’s useful for bulk imports – logs, analytics, and other large datasets.

async function sendNDJSON() {
    const ndjsonData = (
`{"name":"John","age":30}
{"name":"Jane","age":25}
{"name":"Bob","age":35}`
);
    const response = await fetch('/api/ndjson/', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-ndjson',
            'X-CSRFToken': getCSRFToken()
        },
        body: ndjsonData
    });
    const result = await response.json();
    console.log(result);
}

The processing logic is standard: split, parse, validate.

import json
from django.http import JsonResponse
from django.views.decorators.http import require_http_methods


@require_http_methods(["POST"])
def handle_ndjson(request):
    """Handle application/x-ndjson requests"""
    try:
        ndjson_content = request.body.decode("utf-8")
        lines = [
            json.loads(line) for line in ndjson_content.strip().split("\n") if line
        ]

        return JsonResponse(
            {
                "status": "success",
                "lines_count": len(lines),
                "data": lines,
                "content_type": request.content_type,
            }
        )
    except json.JSONDecodeError:
        return JsonResponse({"error": "Invalid NDJSON"}, status=400)

Plain Text

Some systems accept plain text via text/plain, especially object storage services or endpoints meant for raw logs or unstructured content.

async function sendTextPlain() {
    const textData = `This is plain text content.
It can span multiple lines.
Line 3 of the content.`;

    const response = await fetch('/api/text/', {
        method: 'POST',
        headers: {
            'Content-Type': 'text/plain',
            'X-CSRFToken': getCSRFToken()
        },
        body: textData
    });
    const result = await response.json();
    console.log(result);
}

The Django view is minimal and functional:

from django.http import JsonResponse
from django.views.decorators.http import require_http_methods


@require_http_methods(["POST"])
def handle_text_plain(request):
    """Handle text/plain requests"""
    text_content = request.body.decode("utf-8")
    return JsonResponse(
        {
            "status": "success",
            "received": text_content,
            "length": len(text_content),
            "content_type": request.content_type,
        }
    )

HTML Text

You can also POST HTML content using text/html, which can be useful for wiki-style pages or HTML editors that save full documents.

async function sendHTML() {
    const htmlData = `<!DOCTYPE html>
<html>
<head><title>Example</title></head>
<body><h1>Hello World!</h1></body>
</html>`;
    const response = await fetch('/api/html/', {
        method: 'POST',
        headers: {
            'Content-Type': 'text/html',
            'X-CSRFToken': getCSRFToken()
        },
        body: htmlData
    });
    const result = await response.json();
    console.log(result);
}

The Django view would accept the data like this (add your own validation):

from django.http import JsonResponse
from django.views.decorators.http import require_http_methods


@require_http_methods(["POST"])
def handle_html(request):
    """Handle text/html requests"""
    html_content = request.body.decode("utf-8")
    return JsonResponse(
        {
            "status": "success",
            "received": html_content,
            "length": len(html_content),
            "content_type": request.content_type,
        }
    )

XML Data

Older or legacy integrations (especially SOAP-based ones) still rely on application/xml.

Here's a JavaScript example:

async function sendXML() {
    const xmlData = `<?xml version="1.0" encoding="UTF-8"?>
<user>
<name>John Doe</name>
<email>john@example.com</email>
<age>30</age>
</user>`;

    const response = await fetch('/api/xml/', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/xml',
            'X-CSRFToken': getCSRFToken()
        },
        body: xmlData
    });
    const result = await response.json();
    console.log(result);
}

And the Django view can parse the XML data into a dictionary like this:

import xml.etree.ElementTree as ET
from django.http import JsonResponse
from django.views.decorators.http import require_http_methods


@require_http_methods(["POST"])
def handle_xml(request):
    """Handle application/xml requests"""
    try:
        xml_content = request.body.decode("utf-8")
        root = ET.fromstring(xml_content)

        data = {
            child.tag: child.text 
            for child in root
        }

        return JsonResponse(
            {
                "status": "success",
                "root_tag": root.tag,
                "data": data,
                "content_type": request.content_type,
            }
        )
    except ET.ParseError:
        return JsonResponse({"error": "Invalid XML"}, status=400)

SVG Image

SVG graphics can be sent as image/svg+xml, since they are XML-based.

async function sendSVG() {
    const svgData = `<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
<circle cx="50" cy="50" r="40" stroke="black" stroke-width="3" fill="red" />
</svg>`;
    const response = await fetch('/api/svg/', {
        method: 'POST',
        headers: {
            'Content-Type': 'image/svg+xml',
            'X-CSRFToken': getCSRFToken()
        },
        body: svgData
    });
    const result = await response.json();
    console.log(result);
}

The Django view (add your own validation):

from django.http import JsonResponse
from django.views.decorators.http import require_http_methods


@require_http_methods(["POST"])
def handle_svg(request):
    """Handle image/svg+xml requests"""
    svg_content = request.body.decode("utf-8")
    return JsonResponse(
        {
            "status": "success",
            "received": svg_content,
            "length": len(svg_content),
            "content_type": request.content_type,
        }
    )

Binary Data

For raw binary streams – images, audio, video, PDF, or any unknown byte sequence – the fallback is application/octet-stream.

Here is a JavaScript example of how to post it:

async function sendBinary() {
    const binaryData = new Uint8Array([72, 101, 108, 108, 111]);
    const response = await fetch('/api/binary/', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/octet-stream',
            'X-CSRFToken': getCSRFToken()
        },
        body: binaryData
    });
    const result = await response.json();
    console.log(result);
}

The Django view would be the most straightforward, because request.body is already coming as bytestring:

from django.http import JsonResponse
from django.views.decorators.http import require_http_methods


@require_http_methods(["POST"])
def handle_binary(request):
    """Handle application/octet-stream requests (raw binary data)"""
    binary_data = request.body
    return JsonResponse(
        {
            "status": "success",
            "size": len(binary_data),
            "content_type": request.content_type,
            "first_bytes": list(binary_data[:10]),
        }
    )

Protocol Buffers

Protocol Buffers use application/x-protobuf, and compared to JSON they’re usually around 50% smaller and faster to parse. I won't cover the code in this article, but do your research if you need speed.

Code to Play Around with

The rough distribution of content-type usage in real-world APIs is this:

JSON: ~85–90%
Multipart: ~10–15%
Everything else: <5%

If you want to experiment with all the content types, and see the code in context, here's a repo as a great playground:
https://github.com/archatas/django-post-content-types

Moving a Domain to Another Registrar

Aidas Bendoraitis — Fri, 17 Oct 2025 21:52:41 +0000

The Situation

The domain for my first SaaS project 1st-things-1st.com was registered with GoDaddy. Even though the whole project was already running under my company’s name, I never really bothered to move the domain to my company’s account at Namecheap.

Last week I noticed that the domain was about to expire, and I thought, alright, time to finally do it.

I had never transferred a domain before, so I wasn’t sure how it would go or whether I could pull it off without any downtime. Here’s how it went.

The Story

Namecheap has this feature called “Transfer to Us.” You just follow a few simple steps: request a transfer for your domain, enter a one-time Auth code (also called as EPP - Extensible Provisioning Protocol - code) from another registrar to confirm you’re the owner, and pay for another year.

At GoDaddy’s side, there was a whole confirmation process to make sure I really wanted to transfer the domain and understood it couldn’t be undone. Once that was done, I got the code I needed for Namecheap.

Then came the waiting part. It took almost a week to get the confirmation that the transfer was successful, which was expected according to their help docs. As soon as I got the notification, I jumped into my Namecheap settings to check if everything looked right.

Unfortunately, the domain records weren’t migrated automatically. Only the ownership was transferred. The nameserver settings in Namecheap were still pointing to GoDaddy’s servers.

And since GoDaddy no longer listed the domain or its DNS records, I had to recover those values myself.

I needed to extract the following records for each subdomain:

A – IPv4 Address
CNAME – Canonical Name
MX – Mail Exchange
TXT – Text

I did it from the command line like this:

$ dig 1st-things-1st.com ANY > 1st-things-1st.txt
$ dig www.1st-things-1st.com ANY >> 1st-things-1st.txt
$ dig my.1st-things-1st.com ANY >> 1st-things-1st.txt
$ dig our.1st-things-1st.com ANY >> 1st-things-1st.txt
$ dig apps.1st-things-1st.com ANY >> 1st-things-1st.txt
$ dig analytics.1st-things-1st.com ANY >> 1st-things-1st.txt

Alternatively, you can look up WHOIS information on sites like who.is.

Once I had all the records, I switched to Namecheap’s nameservers (Namecheap BasicDNS) and added everything manually.

The website was down for about 30 to 60 minutes, depending on where in the world the visitor was. Some downtime was unavoidable, but overall, the transfer went through successfully.

The Learnings

The whole thing could have been smoother if I had known what to expect. Here’s how I’d do it next time:

Save all domain records to a local file before starting.
Get the Auth/EPP code from the old registrar.
Request the transfer at the new registrar.
Wait for the transfer to complete.
Pick the best time for downtime and let users know in advance.
Switch to the new nameservers and add all records manually.

Per-Object Permissions for Elasticsearch Lists in Django Websites

Aidas Bendoraitis — Sat, 27 Sep 2025 15:15:42 +0000

The Challenge

Elasticsearch improves the performance of filterable and searchable list views, reducing load times from several seconds to about half a second. It stores list view details from various relations denormalized in a JSON-like structure.

In the Django-based system I’ve been working on, we use django-guardian to set per-object permissions for users or roles managing various items. This means you not only need to check whether a user has general permission to view, change, or delete a type of object, but also whether they have permission to access specific objects.

A major challenge arises when using Elasticsearch for authorized views based on user permissions – how can we check permissions without slowing down the listing too much?

Things We Considered

Here are a few options I compared:

Check all object UUIDs the user can access via django-guardian, then pass those UUIDs to the Elasticsearch search query. This might work with fewer than 100 items, but it doesn’t scale.
Filter the Elasticsearch list first, and then check each item’s UUID against user permissions. With thousands of search results, permission checks become too slow. If I check permissions only for the first page, pagination data becomes inaccurate.
Create a user-permission Elasticsearch index with all item UUIDs accessible to the user, and filter the list by looking up those UUIDs. This makes updating the index tricky, especially for admins and superusers.
For each item, store the list of user IDs and group IDs that can view it, then check the current user against those IDs in the list view. This is the approach I chose, since typically only a handful of users and groups need access to any given item.

Below is the code snippet that implements the last approach.

Our Chosen Approach

We use django-elasticsearch-dsl for indexing Django models in Elasticsearch. The Elasticsearch index document for an item with user IDs and group IDs can look like this:

# items/documents.py
from django.conf import settings
from django_elasticsearch_dsl.registries import registry
from django_elasticsearch_dsl import Document, fields
from guardian.shortcuts import get_users_with_perms, get_groups_with_perms

from .models import Item


@registry.register_document
class ItemDocument(Document):
    users_can_view = fields.KeywordField(multi=True)
    users_can_change = fields.KeywordField(multi=True)
    users_can_delete = fields.KeywordField(multi=True)
    groups_can_view = fields.KeywordField(multi=True)
    groups_can_change = fields.KeywordField(multi=True)
    groups_can_delete = fields.KeywordField(multi=True)

    class Index:
        name = "items"
        settings = {
            "number_of_shards": 1,
            "number_of_replicas": 0,
        }

    class Django:
        model = Item

        fields = [
            "uuid",
            "title",
            "intro",
            "created_at",
            "updated_at",
        ]

        queryset_pagination = 5000

    def prepare(self, instance):
        data = super().prepare(instance)

        data["users_can_view"] = []
        data["users_can_change"] = []
        data["users_can_delete"] = []
        for user, permissions in get_users_with_perms(
            item,
            attach_perms=True,
            with_superusers=True,
            with_group_users=False,
            only_with_perms_in=["view_item", "change_item", "delete_item"],
        ).items():
            if "view_item" in permissions:
                data["users_can_view"].append(user.pk)
            if "change_item" in permissions:
                data["users_can_change"].append(user.pk)
            if "delete_item" in permissions:
                data["users_can_delete"].append(user.pk)

        data["groups_can_view"] = []
        data["groups_can_change"] = []
        data["groups_can_delete"] = []
        for group, permissions in get_groups_with_perms(
            item, attach_perms=True
        ).items():
            for perm in permissions:
                if perm == "view_item":
                    data["groups_can_view"].append(group.pk)
                elif perm == "change_item":
                    data["groups_can_change"].append(group.pk)
                elif perm == "delete_item":
                    data["groups_can_delete"].append(group.pk)

        return data

Next, we need a utility class for paginating Elasticsearch indexes in a way that’s compatible with Django’s default queryset pagination:

# items/utils.py

class ElasticsearchPage:
    """
    Django Paginator-compatible interface for Elasticsearch search results.
    """

    def __init__(self, results, total_count, page_number, items_per_page):
        self.object_list = results
        self.total_count = total_count
        self.number = page_number
        self.paginator = type(
            "Paginator",
            (),
            {
                "count": total_count,
                "num_pages": (total_count + items_per_page - 1) // items_per_page,
                "per_page": items_per_page,
            },
        )()

    def has_previous(self):
        return self.number > 1

    def has_next(self):
        return self.number < self.paginator.num_pages

    def has_other_pages(self):
        return self.paginator.num_pages > 1

    def previous_page_number(self):
        return self.number - 1 if self.has_previous() else None

    def next_page_number(self):
        return self.number + 1 if self.has_next() else None

Finally, the list view checks user IDs and group IDs in the index against the current user’s ID and group memberships:

# items/views.py
from .utils import ElasticsearchPage
from .documents import ItemDocument

@login_required
def item_list(request):
    user_group_pks = list(request.user.groups.values_list("pk", flat=True))

    search_obj = ItemDocument.search()

    perm_filter = Q(
        "bool",
        should=[
            Q("term", users_can_view=request.user.pk),
            Q("terms", groups_can_view=user_group_pks),
        ],
        minimum_should_match=1,
    )

    search_obj = search_obj.query("bool", must=[perm_filter])

    # more search and filtering go here...

    items_per_page = int(request.GET.get("items_per_page", 24))
    page_number = int(request.GET.get("page", 1))
    offset = (page_number - 1) * items_per_page

    total_count = search_obj.count()

    search_obj = search_obj[offset : offset + items_per_page]
    search_results = search_obj.execute()

    page = ElasticsearchPage(
        results=search_results,
        total_count=total_count,
        page_number=page_number,
        items_per_page=items_per_page,
    )
    context = {
        "page": page,
        "items_per_page": items_per_page,
    }
    return render(request, "items/item_list.html", context)

At this point, it’s important to update the index not only when item details change, but also when permissions change.

This can be done by calling the following in the relevant views or form save methods:

from django_elasticsearch_dsl.registries import registry

registry.update(item)

Final Thoughts

Using django-guardian to pre-process or post-process Elasticsearch-filtered lists is inefficient. Instead, permissions should exist directly in the Elasticsearch index. Storing user IDs and group IDs in the items themselves is more practical. Just make sure Elasticsearch is properly secured with SSL/TLS and authentication (username and password) to protect the data from tampering.

User Timezones in Django

Aidas Bendoraitis — Mon, 28 Jul 2025 14:14:42 +0000

When you create a local website, the local time usually matches your country’s timezone, and all visitors see times in that timezone. That’s not a big issue if your country has only one timezone and your audience is local.

But when building a social platform like pybazaar.com, users are international and need to see times in their timezones. In this article, I’ll show you how to handle that in Django.

Time Zone Database

Since version 4.0, Django has used the zoneinfo library for managing timezones, and it used pytz up to version 3.2. Both rely on the IANA Time Zone Database (tzdata). IANA is the same organization that manages the DNS root zone, IP addresses, and other global internet resources.

Install tzdata in your virtual environment as usual:

(venv)$ pip install --upgrade tzdata

Timezone Changes

Timezone information changes several times a year due to:

Daylight Saving Time (DST) adjustments
Political and border changes
Shifts in standard time offset

Daylight Saving Time (DST) was first introduced in 1914 in Canada and later standardized in the U.S. in 1966. When dealing with historic dates before 1966—or future dates with uncertain timezone rules—precise time calculations can be unreliable.

# Before U.S. DST standardization:
old_date = datetime(1960, 6, 15, 12, 0)  

# DST rules may change in the future:
future_date = datetime(2030, 6, 15, 12, 0)

Some timezone changes are driven by politics:

Country splits or mergers — new countries may adopt different timezones.
Regional preferences — states or provinces may change timezone alignment.
Symbolic actions — e.g., North Korea introduced "Pyongyang Time" in 2015 by shifting 30 minutes back to symbolically break from Japan’s colonial legacy.

And countries sometimes adjust their UTC offsets:

Russia — changed its timezone policy multiple times
Venezuela — changed from UTC-4 to UTC-4:30 in 2007, then back in 2016
Samoa — jumped from UTC-11 to UTC+13 in 2011, skipping Dec 30 entirely

Best Practices for Django

Use named timezones, not fixed UTC offsets.
Update tzdata monthly or quarterly.
Test with historic and future dates.
Handle conversion errors gracefully, falling back to UTC.
Store all times in UTC internally.
Convert to user’s timezone only in the UI.
Include tzdata updates in deployment (Docker, Ansible, etc.).

Timezone Management for a Social Platform

For platforms with global users:

Store all datetimes in UTC.
Store each user's preferred timezone.
Convert times on input/output according to the user’s timezone.

1. Enable Timezone Support in Django Settings

Set the default timezone to UTC:

# settings.py
USE_TZ = True
TIME_ZONE = "UTC"  # Store everything in UTC

2. Add a `timezone` Field to the Custom `User` Model

Use a function for dynamic timezone choices, so you don’t need new migrations when the list changes.

def get_timezone_choices():
    import zoneinfo
    return [(tz, tz) for tz in sorted(zoneinfo.available_timezones())]

class User(AbstractUser):
    # ...
    timezone = models.CharField(
        _("Timezone"), max_length=50, choices=get_timezone_choices, default="UTC"
    )

3. Detect Timezone on the Frontend

Add hidden fields in your Login and Signup forms to capture the user’s timezone from their browser:

document.addEventListener('DOMContentLoaded', function () {
    const userTimezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
    const timezoneInput = document.getElementById('id_timezone');
    if (timezoneInput) {
        timezoneInput.value = userTimezone;
    }
});

You can also let users change their timezone manually in account settings.

4. Use a Custom DateTime Field in Forms

This field will convert datetimes between UTC and the user’s local timezone:

import datetime
from zoneinfo import ZoneInfo
from django import forms
from django.utils import timezone
from django.utils.dateparse import parse_datetime

class TimezoneAwareDateTimeField(forms.DateTimeField):
    widget = forms.DateTimeInput(attrs={"type": "datetime-local"})

    def __init__(self, user_timezone=None, *args, **kwargs):
        self.user_timezone = user_timezone
        super().__init__(*args, **kwargs)

    def prepare_value(self, value):
        if value and self.user_timezone:
            try:
                user_tz = ZoneInfo(self.user_timezone)
                if timezone.is_aware(value):
                    value = value.astimezone(user_tz)
            except Exception:
                pass
        return value

    def to_python(self, value):
        if value in self.empty_values:
            return None
        if isinstance(value, datetime.datetime):
            result = value
        elif isinstance(value, datetime.date):
            result = datetime.datetime(value.year, value.month, value.day)
        else:
            try:
                result = parse_datetime(value.strip())
            except ValueError:
                raise forms.ValidationError(
                    self.error_messages["invalid"], code="invalid"
                )
        if not result:
            result = super(forms.DateTimeField).to_python(value)
        if result and self.user_timezone:
            try:
                user_tz = ZoneInfo(self.user_timezone)
                if timezone.is_naive(result):
                    result = result.replace(tzinfo=user_tz)
                result = result.astimezone(ZoneInfo("UTC"))
            except Exception:
                pass
        return result

The type="datetime-local" widget uses the browser’s native date/time picker.

Use the custom field like this:

from django import forms
from django.utils.translation import gettext_lazy as _
from myproject.apps.core.form_fields import TimezoneAwareDateTimeField
from .models import Post

class PostForm(forms.ModelForm):
    class Meta:
        model = Post
        fields = ["title", "content", "published_from"]

    def __init__(self, request, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.request = request
        self.fields["published_from"] = TimezoneAwareDateTimeField(
            label=_("Published from"),
            help_text=_("Enter date and time in your local timezone."),
            required=False,
            user_timezone=self.request.user.timezone,
        )

5. Output Dates and Times in User's Timezone

{% load tz %}
{% with user_timezone=request.user.timezone|default:"UTC" %}
    {{ post.published_from|timezone:user_timezone|date:"j M, Y H:i" }}
{% endwith %}

Other Options

You can also detect the visitor’s timezone in JavaScript and send it via Ajax to be saved in the Django session. Then you can use it even for anonymous users.

Final Words

Timezones aren’t so scary if you follow Django’s best practices:

Store all times in UTC.
Update tzdata regularly.
Use the user's timezone only at input/output stages.
Detect the user’s timezone via JavaScript—no need to ask them manually.

This keeps your website accurate, user-friendly, and ready for global audiences.

Cover photo by Andrey Grushnikov

DEV Community: Aidas Bendoraitis

Setting Up DNS for SaaS Emails

Consider using separate subdomains for different types of email

MX records for receiving emails

SMTP setup for outgoing emails

SPF records for outgoing emails: Which senders are allowed?

DKIM records for outgoing emails: Is the sender valid?

DMARC records for outgoing emails: What to do with unauthorized senders?

Brevo setup as an exception

BIMI records for the outgoing emails: What brand logo will be shown?

Final words

When Python is Too Slow

How do the bindings work

An experiment with benchmarks

What is there to know about Rust

The package structure

Rust in Django

Final words

Understanding Memory Usage in Django Webserver Workers

Startup time vs. request execution

Little demo of shared memory between requests

How RAM is managed

1. Compilation/setup state is persistent

2. Execution state lives per-request

Common bugs to avoid

1. Mutable module-level state

2. Storing per-request data on a shared instance

3. Class-level cache shared across instances

Mental model

Conclusion

Browser Push Notifications for a Django Website

How it works

Prerequisites

Step 1. The Feedback App

Step 2. VAPID keys

Step 3. Django settings

Step 4. The Notifications App

Step 5. Subscribe / unsubscribe views

Step 6. Wire URLs into myproject/urls.py

Step 7. Service worker JavaScript

Step 8. Admin subscription JavaScript

Step 9. Context processor

Step 10. Inject globals via admin/base_site.html

Step 11. Huey task

Step 12. Content Security Policy

User experience

Privacy and security

OS permissions

Marketing perspective

Final words

Improving First Byte and Contentful Paint on a Django Website

HttpResponse vs. StreamingHttpResponse in Action

Generic HTML Streaming View

Use Case with the Strategic Prioritizer "1st things 1st"

The Optimization Results

Final Words

Wagtail Routable Pages and Layout Configuration

1. Project Setup

2. File Structure

3. Models

myproject/apps/articles/models.py

4. StreamField Blocks

myproject/apps/articles/blocks.py

5. Templates

articles/article_list.html

articles/article_detail.html

articles/blocks/cover_image_block.html

articles/blocks/description_block.html

articles/blocks/related_articles_block.html

6. Django Admin Registration

articles/admin.py

7. Migrations and Initial Data

8. Wagtail Admin Setup

Final words

How to Show a Waitlist Until Your Wagtail Site Is Ready

The Concept

1. Generate and store two secrets

2. Create the access-control decorator

3. Create the passphrase form

4. Build the cookie toggle view

`HttpResponse` vs. `StreamingHttpResponse` in Action

`myproject/apps/articles/models.py`

`myproject/apps/articles/blocks.py`

`articles/article_list.html`

`articles/article_detail.html`

`articles/blocks/cover_image_block.html`

`articles/blocks/description_block.html`

`articles/blocks/related_articles_block.html`

`articles/admin.py`

2. Add a `timezone` Field to the Custom `User` Model