django-countdown

Display a maintenance countdown banner across a Django site, then block public access (returning HTTP 503) when the countdown expires. Superusers retain access during maintenance so they can finish the work and clear the countdown.

📖 Full documentation: https://iplweb.github.io/django-countdown/

Why?

Planned downtime is the worst kind of downtime to communicate badly. Users land on a half-broken page mid-deploy, hit error logs, file support tickets, and trust erodes. django-countdown lets you announce a maintenance window before it starts (a countdown banner with a real timer), then during the window swap public traffic for an explicit "we're in maintenance" page — while leaving operators unblocked so they can actually finish the work.

Features

• Pre-maintenance banner — an ultra-visible countdown banner inserted into templates via context processor, with a JS timer that ticks live.
• Hard cutoff at expiry — middleware returns HTTP 503 and renders a branded blocked page once the countdown lapses.
• Superuser bypass — admins keep working through the cutoff so they can fix the underlying issue and clear the countdown.
• Maintenance window — optional maintenance_until lets you set a target end-time; a second banner appears for superusers and the blocked page shows a live countdown to recovery.
• Self-healing wait — the blocked page polls a status endpoint in the background and sends visitors back to the page they wanted the moment the site returns. It tells "still down for maintenance" apart from "nothing is answering while the container restarts", so a timer that runs out mid-deploy no longer strands anyone on the proxy's error page.
• Per-Site configuration — uses Django's sites framework, so each domain in a multi-tenant setup has its own independent countdown.
• A command per verb — start_countdown schedules a window, show_countdown reports where it stands (with --json for monitoring), extend_countdown and shorten_countdown move its boundaries when the plan slips, and stop_countdown reopens the site.
• Dead man's switch — extend_countdown --at-least 5m raises a floor rather than adding time, so a deploy loop can hold the site closed while it works and let it reopen by itself if the deploy dies.
• Admin integration — full Django admin support alongside the commands.

Supported versions

All 11 cells are exercised by the CI matrix on every push. Django is the only runtime dependency.

Installation

uv add django-countdown      # or: pip install django-countdown

Add the app, the middleware and the context processor to your settings:

INSTALLED_APPS = [
    # ...
    "django.contrib.sites",
    "django_countdown",
]
SITE_ID = 1

MIDDLEWARE = [
    # ...
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django_countdown.middleware.CountdownBlockingMiddleware",
]

TEMPLATES = [{
    # ...
    "OPTIONS": {"context_processors": [
        # ...
        "django_countdown.context_processors.countdown_context",
    ]},
}]

Then ./manage.py migrate, and include the banner in your base template:

{% include "django_countdown/countdown_banner.html" %}

Full walkthrough: Installation.

Quick start

./manage.py start_countdown --banner +15m --service +30m \
    --message "Database upgrade" --noinput

Banner shows for 15 minutes, then the site returns 503 for 30 minutes, then reopens by itself. Check on it with ./manage.py show_countdown, and reopen early with ./manage.py stop_countdown. Use --service indefinite to stay closed until you do. See Quickstart.

A working end-to-end example lives under example/.

Documentation

Development

git clone https://github.com/iplweb/django-countdown.git
cd django-countdown
uv sync --all-extras
uv run pytest

See Contributing.

License

MIT — see LICENSE for details.