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.
• 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 8 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.