djangoproject.com source code: two databases and a Trac schema before a single page loads

The official Django site as a local development environment

The django/djangoproject.com repository holds the source code for https://www.djangoproject.com/, the official home of the Django framework. Running it locally produces a working copy of the live site, including the main page, the documentation interface, the developer dashboard, the fundraising pages and the blog.

The architecture is standard Django. A top-level djangoproject/ directory holds the project-wide settings, URL configuration and static file locations. Features are organised into individual Django apps: accounts, aggregator, blog, checklists, contact, dashboard, docs, foundation, fundraising, legacy, members, releases, svntogit and tracdb, along with the main djangoproject app itself. All fifteen of those app labels appear explicitly in the Makefile's APP_LIST variable, which controls which directories the test runner covers.

The project is published under the BSD-3-Clause licence. The last push to the main branch was on 2026-10-06. No GitHub releases exist: there is no tag to pin and no changelog file outside the commit history itself, so anyone who wants to reference a fixed state must do so by commit hash.

Two PostgreSQL databases: djangoproject and code.djangoproject

Most Django projects need one database. This project needs two. The first, named djangoproject, holds the main site data. The second, named code.djangoproject, holds the schema for Trac, the bug tracker Django used before moving to GitHub. That Trac integration is still part of the codebase through the tracdb app, and leaving out its database causes errors before a single page can render.

Both databases need their own PostgreSQL users before Django can connect. The README gives these commands:

createuser -d djangoproject --superuser
createdb -O djangoproject djangoproject
createuser -d code.djangoproject --superuser
createdb -O code.djangoproject code.djangoproject

If PostgreSQL's default configuration requires passwords for local connections, both users need them set explicitly:

ALTER USER djangoproject WITH PASSWORD 'secret';
ALTER USER "code.djangoproject" WITH PASSWORD 'secret';

The Trac database requires a schema loaded from a file in the repository, separate from Django's migration system:

psql -d code.djangoproject < tracdb/trac.sql

Django's python -m manage migrate handles the main database tables but does not touch the Trac schema. Running migrate without first loading tracdb/trac.sql leaves the Trac-related parts without their tables, and the application will fail when it tries to query them.

secrets.json holds eight required keys and DJANGOPROJECT_DATA_DIR must be set

Before any management command runs, the process needs a secrets.json file and an environment variable pointing to a data directory. The data directory does not exist on a fresh machine, so the README's first manual step is:

mkdir -p ~/.djangoproject/conf

A development secrets.json needs all eight keys shown in the README:

{
  "secret_key": "xyz",
  "superfeedr_creds": ["[email protected]", "some_string"],
  "db_host": "localhost",
  "db_password": "secret",
  "db_user": "djangoproject",
  "trac_db_host": "localhost",
  "trac_db_password": "secret",
  "trac_db_user": "code.djangoproject"
}

The superfeedr_creds entry takes a list with exactly two values, not a plain string, and a plain string here causes an error that takes time to trace. All eight keys must be present: removing any one of them causes a startup failure rather than a degraded run.

The DJANGOPROJECT_DATA_DIR environment variable must be set and sourced before running any command. The README says to add export DJANGOPROJECT_DATA_DIR=~/.djangoproject to the shell profile (bashrc, zshrc or bash_profile depending on the platform) and then run source on that file to load the change into the current shell session. Without the variable, every management command fails immediately while looking for the configuration directory.

Installing dependencies and compiling SCSS before the server starts

Dependencies install from the dev requirements file:

python3 -m pip install -r requirements/dev.txt

Alternatively, the Makefile shortcut does the same thing:

make install

The pyproject.toml sets requires-python to ==3.12.*, which pins the project to the Python 3.12 series. Attempting to use a different major or minor version will fail at install time because the version constraint is exact rather than a lower bound.

Before running the server, the SCSS source files in djangoproject/scss/ must be compiled to CSS in djangoproject/static/css/. The repository stores only the SCSS sources, and no compiled CSS is committed:

make compile-scss

For development with a source map included:

make compile-scss-debug

Skipping this step starts the server but every page loads without any styles applied. A separate watcher command keeps the compiled output current during development, recompiling automatically whenever a source file changes:

make watch-scss

After all the setup steps, including database creation, schema loads, site data fixtures and SCSS compilation, the final command starts the www, docs and dashboard subdomains in a single process:

make run

The site becomes available at http://www.djangoproject.localhost:8000/, http://docs.djangoproject.localhost:8000/ and http://dashboard.djangoproject.localhost:8000/. The README does not explain how to make those subdomain hostnames resolve on systems that do not support wildcard .localhost resolution by default.

Docker Compose skips secrets.json but not the Trac schema load

The Docker Compose path removes several of the manual steps. The docker-compose.yml file defines two services: web and db. The db service uses postgres:17-trixie and creates the djangoproject database automatically via environment variables. The web service builds from the Dockerfile, which starts from python:3.12-slim-trixie and installs gettext, git, rsync and PostgreSQL client tools before adding the Python dependencies.

Environment variables in docker-compose.yml set DJANGOPROJECT_DATA_DIR=./data and DJANGO_SETTINGS_MODULE=djangoproject.settings.docker, which removes the need to write a secrets.json manually. Database credentials are provided inline: SQL_PASSWORD=secret, SQL_USER=djangoproject, TRAC_USER=code.djangoproject and TRAC_PASSWORD=secret, covering both the main site database and the Trac database.

What Docker does not create automatically is the Trac database itself. A comment in docker-compose.yml notes that the Trac schema needs to be loaded manually via a separate initialization script (02_trac_schema.sh), because it applies to the Trac database rather than the main Django database that the container creates on startup. That step remains a manual operation regardless of whether you use the virtualenv path or the Docker path.

External service credentials are also absent from docker-compose.yml. Superfeedr, Stripe and Kismet are not configured, so any app functionality that calls those services requires additional setup before it works.

Running tests, collecting coverage and adding Playwright for end-to-end checks

From the repository root, one command runs the full test suite with coverage collection enabled:

make test

Behind the scenes, the Makefile runs python -m coverage run --source=. --module manage test over all fifteen app labels and any additional TEST_ARGS passed in. After the run finishes, the coverage summary prints with:

python -m coverage report

An HTML report that shows per-file and per-line detail generates with:

python -m coverage html

End-to-end tests use Playwright and require browsers installed separately before the first run:

python -m playwright install --with-deps chromium firefox

With the browsers available, end-to-end tests run as part of the standard test target by passing browser flags:

make test TEST_ARGS="--browser chromium --browser firefox"

Playwright is pinned at version 1.62.0 in the test dependencies. GitHub Actions handles continuous integration for the project, and the results are public at https://github.com/django/djangoproject.com/actions. Test requirements live in requirements/tests.txt, which is already included via requirements/dev.txt, so a standard virtualenv install has everything without a separate step.

Exact version pins, one git-sourced dependency and a mobile browser grade

The pyproject.toml pins each production dependency to an exact version: Django at 6.1, Stripe at 13.2.0, Pillow at 12.3.0, Sphinx at 8.1.3 and gunicorn at 26.0.0, among others. That level of pinning makes a known-good state easy to reproduce from a clean environment, but it also means that any security update in a dependency requires a deliberate edit to pyproject.toml rather than a routine upgrade.

One package does not come from PyPI: django-push installs from a specific GitHub commit hash. The entry reads django-push @ git+https://github.com/brutasse/django-push.git@22fda99641cfbd2f3075a723d92652a8e38220a5. That commit pin is stable but it bypasses PyPI release metadata and any security advisories tied to a version number, so a project that audits its dependency graph will not find django-push in the standard vulnerability databases.

Browser support follows a grade system the README attributes to Mozilla's example. Desktop browsers except those below IE 11 are A grade, meaning everything must work. Mobile browsers including Mobile Safari, Firefox on Android and the Android Browser are B grade, where some degradation is expected due to screen size and platform restrictions. IE below 11 is not supported, based on Microsoft's support policy at the time the README was written.

With no GitHub releases, there is no tag on the main branch and no CHANGELOG file at the repository root. Any deployment or dependency on a known state requires tracking commits directly.

Editorial conclusion

Run this repository if you are contributing to djangoproject.com directly or studying how the Django team structures a multi-app project with two PostgreSQL databases and a Trac integration. The setup requires Python 3.12 exactly, two PostgreSQL databases, a secrets.json with all eight keys, and SCSS compiled before the first request. Skip it as a template for a new project: the Trac integration, two-database layout and partially unconfigured external services (Stripe, Superfeedr, Kismet) make it a poor starting point. Before running, verify that your PostgreSQL installation accepts password authentication and that your system resolves .localhost subdomains, which the README does not address.

Frequently asked questions

Official sources

1. django/djangoproject.com on GitHub
2. Issues
3. License: BSD-3-Clause
4. Project website
5. README