python-discord/site: the Django application behind pythondiscord.com

A site codebase, not a library you can depend on

The repository description is precise: pythondiscord.com, a Django and Bulma web application. The readme says this is all of the code that is responsible for maintaining our website and all of its subdomains.

So the scope is the community site itself, its subdomains, and whatever the project uses to track metrics across them. It is not a packaged Django application that you install into your own project, and the manifest makes that explicit with package = false under the tool.uv section, meaning uv treats it as a project rather than a library to build and publish.

The stack is current Django. The dependency list pins django 5.1.15, djangorestframework 3.16.0, django-filter 25.1, django-environ 0.12.0 and django-prometheus 2.4.1, alongside django-distill 3.2.7 and django-simple-bulma 2.6.0 for the front end. Markdown handling comes from markdown 3.8.2 with pymdown-extensions, and the database driver is psycopg with the binary extra at 3.2.9.

The Python version is pinned exactly, requires-python is ==3.13.*, and the Ruff configuration targets py313. Everything is pinned to an exact version rather than a range, and the uv lock file is committed, which is a deliberate reproducibility choice for a deployment that has to keep working.

The licence is MIT, and the repository is not archived with the last push on 2026-10-12. There are no GitHub releases, which is what you would expect for a private deployment repository.

The dependency list tells you what the site actually does

Reading the pinned dependencies is the fastest way to understand the shape of the application, because each one points at a feature.

django-restframework is there, so there is an API surface, and the Compose file confirms it by giving the web service three network aliases, api.web, admin.web and staff.web, which is how a single container serves three hostnames with different behaviour.

django-prometheus gives metrics, and the Dockerfile contains a specific accommodation for it. Before running collectstatic, the build sets BUILDING_DOCKER to anything but undefined, with the comment explaining that this prevents settings.py from inserting django_prometheus into the list of installed apps, and that this prevents django_prometheus from attempting to connect to the database when the collectstatic task runs. That is the kind of detail you only find in a deployment repository, and it tells you the metrics library reaches for the database at import time.

django-environ is how configuration arrives, so there is no checked-in local settings file with secrets in it, and the Compose file confirms the pattern with DATABASE_URL, METRICITY_DB_URL, SECRET_KEY, STATIC_ROOT and DEBUG given as environment variables.

whitenoise 6.9.0 serves static files, waitress 3.0.2 is the WSGI server, and sentry-sdk 2.33.0 is the error reporting client. httpx 0.28.1 is the HTTP client, pyjwt with the crypto extra handles tokens, and python-frontmatter with markdown and pymdown-extensions is how the content pages, which live in a content app and are written in Markdown, are rendered.

That is a complete picture of a community site: a content system backed by Markdown, a REST API, metrics, error tracking, and a static file pipeline.

Bringing it up locally with Docker Compose

The Compose file is described as a setup file that can be used to quickly set up a development server with code auto-reloading and automatic execution of migrations, and it is explicit that it is not intended to be used for production, because the migrate and server script applies migrations and uses the Django development server, which is unsuitable for production.

There are two services. The database is postgres:15-alpine, published on port 7777 to 5432, with POSTGRES_DB, POSTGRES_PASSWORD and POSTGRES_USER all set to pysite, a healthcheck of pg_isready with the pysite user on a two second interval, and a volume mounting ./postgres/init.sql into the container's initdb directory.

The web service is built from the repository's own Dockerfile and runs python manage.py run, and it depends on the postgres service with the condition service_healthy, which is how the migration step at start-up waits for a database that is actually accepting connections rather than one that is merely started.

The environment block is where you can see the two-database design:

    environment:
      DATABASE_URL: postgres://pysite:pysite@postgres:5432/pysite
      METRICITY_DB_URL: postgres://pysite:pysite@postgres:5432/metricity
      SECRET_KEY: suitable-for-development-only
      STATIC_ROOT: /var/www/static
      DEBUG: 1

DATABASE_URL and METRICITY_DB_URL point at the same server but different databases, pysite and metricity, which is the metricity project holding the traffic and page view data that the site displays. The source is mounted read only at /app, and a named volume holds the static files at /var/www/static.

For a contributor, that is a one command setup with a working database, and the cost is that the SECRET_KEY is literally the string suitable-for-development-only, which is exactly the kind of value that must never reach a deployment.

The Dockerfile, and the static build path

The Dockerfile is a two stage build with a few decisions that reveal how the site is deployed.

The base is python:3.13-slim by way of an ARG, and the comment at the top asks that when the Python version is updated there, the contributor guide is updated too, with the path to it given.

The builder stage copies the uv binary out of the ghcr.io/astral-shuv image, sets UV_COMPILE_BYTECODE and UV_LINK_MODE, and runs uv sync --frozen --no-dev with cache mounts for the uv cache and bind mounts for uv.lock and pyproject.toml. The frozen flag is what makes the lock file authoritative, so the image contains exactly the pinned versions.

The runtime stage is the same python image, with STOPSIGNAL SIGQUIT and a comment explaining that it allows the service to handle stops gracefully. It copies the built virtualenv from the builder and puts /build/.venv/bin on the PATH, then copies the source code in last, with a comment saying that is done to optimise rebuilding the image.

Then the collectstatic step, which is the part worth reading:

RUN \
    BUILDING_DOCKER=yes \
    SECRET_KEY=dummy_value \
    DATABASE_URL=postgres://localhost \
    METRICITY_DB_URL=postgres://localhost \
    uv run python manage.py collectstatic --noinput --clear

Django refuses to run collectstatic without a secret key and a configured database, so the build supplies dummy values, and the note explains that the dummies exist so settings.py can load. The BUILDING_DOCKER flag is the piece that makes the metrics app stay out of the installed apps list during the build.

There is also a static build mode, a STATIC_BUILD argument set to false by default, and a separate static-builds directory in the repository, so the site can also be produced as static output.

Where this repository is the wrong tool

There are clear cases where copying this repository is a mistake, and they are about what kind of artefact it is.

The first is if you want a Django starter. There are many, and this is not one. The project is the code for pythondiscord.com, with its content models, its pages, its site navigation and its API, all of which are specific to a community site. Starting a new site from it means deleting most of it.

The second is the exact version pinning. requires-python is ==3.13.* and every dependency is pinned to an exact version, which is right for a deployment you have to keep running and is a constraint if you want to run it alongside other software, or on a distribution that does not ship Python 3.13 yet. There is no supported version range to negotiate with.

The third is that the configuration is environment driven with no local settings file, so the code assumes twelve-factor style configuration. That is the right model for a container deployment and it means a developer needs the environment set up before anything imports settings, which is why the Compose file exists and why the Dockerfile passes dummies.

The fourth is the Compose file being development only. It runs the Django development server, and the file says so twice. Using it in production would give you a development server, a secret key that says not to use it, and DEBUG on.

And the fifth is the dependency on two databases. A single application with a content database and a separate metrics database is a reasonable design for a site that tracks traffic across subdomains, and it is more moving parts than a small site needs.

Against a fresh Django project, and against a static site generator

Two comparisons make the choice clear.

The first is against starting from a fresh Django project with django-admin startproject. The difference in approach is that a fresh project gives you a clean, minimal application with nothing in it, and the dependency set you choose yourself. This repository gives you a working deployment: a two stage Dockerfile, a Compose file with a database and a health check, a metrics library, an error reporting client, a static file pipeline that runs at build time, a lint configuration, a pre-commit setup and a coverage report wired into continuous integration.

For a community site with volunteers contributing, that packaging is the value. The person picking up an issue does not have to work out how to containerise a Django app, how to get PostgreSQL running, how to wire Prometheus without it trying to reach the database during the build, or how to make the static files available. It is all solved and the solutions are visible in the repository. The cost is that the reference is a specific site, so you inherit decisions you may not have made, and the exact version pins that go with them.

The second is against a static site generator. A site whose content is Markdown files, as this one partly is, could be built with a generator and served as static files, which removes the application server, the database and the runtime entirely. The static-builds directory suggests that path is partly available here.

The reason a Django site with a database is the right shape for a community site is that a community site is not only a blog. It has accounts, a session, a permission model for staff and administrators, forms that write to the database, and dynamic pages that reflect what happened in the community. Once you need that, a static generator stops being sufficient and you are back to a web framework. The question is which framework, and here the answer is Django with a well-documented deployment around it.

Editorial conclusion

Adopt this repository as a reference if you want to see a Django site with REST API, Prometheus metrics, a Bulma theme, PostgreSQL and a Docker Compose development environment wired together in a way you can read end to end. Skip it if you need a reusable application, because it is the code for one specific community site rather than a distributable package, and the pyproject declares package = false. Verify first that the pinned Python 3.13 and Django 5.1.15 versions fit your environment, that the settings expect environment variables rather than a local settings file, and that the static build path in the Dockerfile produces something your deployment can serve.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. python-discord/site on GitHub
5. README