djangoproject.com source code

To run locally, you can either:

• Install and run from a virtual environment
• Run with docker compose (see below)

Install and run locally from a virtual environment

1. Create a Python 3.12 virtualenv and activate it

2. Install dependencies:

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

   Alternatively, use the make task:

   make install
   

3. Make a directory to store the project's data (MEDIA_ROOT, DOC_BUILDS_ROOT, etc.). We'll use ~/.djangoproject for example purposes. Create a sub-directory named conf inside that directory:

   mkdir -p ~/.djangoproject/conf
   

   Create a secrets.json file in the conf directory, containing something like:

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

4. Add export DJANGOPROJECT_DATA_DIR=~/.djangoproject (without the backticks) to your ~/.bashrc (or ~/.zshrc if you're using zsh, ~/.bash_profile if you're on macOS and using bash) file and then run source ~/.bashrc (or source ~/.zshrc, or source ~/.bash_profile) to load the changes.

5. Create databases:

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

6. Setting up database access

   If you are using the default postgres configuration, chances are you will have to give a password for the newly created users to be able to use them for Django:

   psql
   ALTER USER djangoproject WITH PASSWORD 'secret';
   ALTER USER "code.djangoproject" WITH PASSWORD 'secret';
   \d
   

   (Use the same passwords as the ones you've used in your secrets.json file)

7. Create tables:

   psql -d code.djangoproject < tracdb/trac.sql
   
   python -m manage migrate
   

8. Create a superuser:

   python -m manage createsuperuser
   

9. Populate the www and docs hostnames in the django.contrib.sites app:

   python -m manage loaddata dev_sites
   

10. Compile .po files to .mo files for translations:

    make compilemessages
    
    This only needs to happen once to support running the locale tests
    locally.
    

11. For docs (next step requires gettext):

    python -m manage loaddata doc_releases
    python -m manage update_docs
    

12. For dashboard:

    To load the latest dashboard categories and metrics:

    python -m manage loaddata dashboard_production_metrics
    

    Alternatively, to load a full set of sample data (takes a few minutes):

    python -m manage loaddata dashboard_example_data
    

    Finally, make sure the loaded metrics have at least one data point (this makes API calls to the URLs from the metrics objects loaded above and may take some time depending on the metrics chosen):

    python -m manage update_metrics
    

13. Compile the CSS (only the source SCSS files are stored in the repository):

    make compile-scss
    

14. Finally, run the server:

    make run
    

    This runs both the main site ("www") as well as the docs and dashboard site in the same process. Open http://www.djangoproject.localhost:8000/, http://docs.djangoproject.localhost:8000/, or http://dashboard.djangoproject.localhost:8000/.

Running the tests

We use GitHub actions for continuous testing and GitHub pull request integration. If you're familiar with those systems you should not have any problems writing tests.

Our test results can be found here:

• https://github.com/django/djangoproject.com/actions

Then in the root directory (next to the manage.py file) run:

make test

Behind the scenes, this will run the usual python -m manage test management command with a preset list of apps that we want to test. We collect test coverage data as part of that test run, to show the result simply run:

python -m coverage report

or for a HTML-based report:

python -m coverage html

(Optional) In case you're using an own virtualenv you can also run the tests manually using the test task of the Makefile. Don't forget to install the test requirements with the following command first though:

python -m pip install -r requirements/tests.txt

Then run:

make test

or simply the usual test management command:

python -m manage test [list of app labels]

Supported browsers

The goal of the site is to target various levels of browsers, depending on their ability to use the technologies in use on the site, such as HTML5, CSS3, SVG, webfonts.

We're following Mozilla's example when it comes to categorizing browser support.

• Desktop browsers, except as noted below, are A grade, meaning that everything needs to work.
• IE < 11 is not supported (based on Microsoft's support).
• Mobile browsers should be considered B grade as well. Mobile Safari, Firefox on Android and the Android Browser should support the responsive styles as much as possible but some degradation can't be prevented due to the limited screen size and other platform restrictions.

File locations

Static files such as CSS, JavaScript or image files can be found in the djangoproject/static subdirectory.

Templates can be found in the djangoproject/templates subdirectory.

Styles

CSS is written in Scss and compiled via Libsass.

Run the following to compile the Scss files to CSS:

make compile-scss-debug

Alternatively, you can also run the following command in a separate shell to continuously watch for changes to the Scss files and automatically compile to CSS:

make watch-scss

Running all at once

Optionally you can use a tool like Foreman to run all process at once:

• the site (similar to www.djangoproject.com) on http://0.0.0.0:8000/ to be used with the modified /etc/hosts file (see above)
• the make task to automatically compile the SCSS files to CSS files

This is great during development. Assuming you're using Foreman simply run:

foreman start

If you just want to run one of the processes defined above use the run subcommand like so:

foreman run web

That'll just run the www server.

Check out the Procfile file for all the process names.

JavaScript libraries

This project's JavaScript libraries can be found in djangoproject/static/js/lib/. If you need to add a library, commit the minified version of it to this directory.

Documentation search

When running python -m manage update_docs to build all documents it will also automatically index every document it builds in the search engine as well.

Updating metrics from production

The business logic for dashboard metrics is edited via the admin interface and contained in the models in the dashboard app (other than Dataum, which contains the data itself). From time to time, those metrics should be extracted from a copy of the production database and saved to the dashboard/fixtures/dashboard_production_metrics.json file.

To update this file, run:

python -m manage dumpdata dashboard --exclude dashboard.Datum --indent=4 > dashboard_production_metrics.json

Release Checklists

The checklists app provides assistance for issuing Django releases (feature releases, pre-releases (alpha/beta/RC), bugfix releases, and security releases).

For detailed documentation see checklists/README.md.

Translation

We're using Transifex to help manage the translation process. The Transifex client app is required. To install it, run:

curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash

Before using the command-line Transifex client, create ~/.transifexrc according to the instructions at https://docs.transifex.com/client/client-configuration. You'll need to be a member of the Django team in the Django organization at Transifex. For information on how to join, please see the Translations section of the documentation on contributing to and localizing Django.

Since this repo hosts three separate sites, our .po files are organized by website domain. At the moment, we have:

• dashboard/locale/ contains the translation files for https://dashboard.djangoproject.com
• docs/locale/ contains the translation files for https://docs.djangoproject.com (only for the strings in this repository; translation of the documentation itself is handled elsewhere)
• locale/ contains the translation files for https://www.djangoproject.com (including strings from all apps other than dashboard and docs)

Important: To keep this working properly, note that any templates for the dashboard and docs apps must be placed in the <app name>/templates/<app name>/ directory of the respective app, not in the djangoproject/templates/ directory.

Updating messages on Transifex

When there are changes to the messages in the code or templates, a member of the translations team will need to update Transifex as follows:

1. Regenerate the English (only) .po file:

   python -m manage makemessages -l en
   

   (Never update alternate language .po files using makemessages. We'll update the English file, upload it to Transifex, then later pull the .po files with translations down from Transifex.)

2. Push the updated source file to Transifex:

   tx push -s
   

3. Commit and push the changes to GitHub:

   git commit -m "Updated messages" locale/en/LC_MESSAGES/*
   git push
   

Updating translations from Transifex

Anytime translations on Transifex have been updated, someone should update our translation files as follows:

1. Pull the updated translation files:

   ./update-translations.sh
   

2. Use git diff to see if any translations have actually changed. If not, you can just revert the .po file changes and stop here.

3. Compile the messages:

   python -m manage compilemessages
   

4. Run the test suite one more time:

   python -m manage test
   

5. Commit and push the changes to GitHub:

   git add dashboard/locale/ docs/locale/ locale/
   git commit -m "Updated translations"
   git push
   

Testing the fundraising page (Stripe)

The site talks to Stripe in test mode. Out of the box the app falls back to shared sandbox keys committed in djangoproject/settings/common.py, so you can test donations without any extra configuration. To use your own (or the sandbox team's) keys instead, add stripe_secret_key, stripe_publishable_key, stripe_endpoint_secret and, if needed, the stripe_product_id_* values to your secrets.json.

Without a webhook endpoint registered for the account, the site can't receive Stripe's notifications and test donations will complete at the Stripe step but will not be recorded in the database. To test the full flow, relay test-mode webhooks to the local development server with the Stripe CLI (below).

Testing Stripe webhooks

Mergers have access to the "djangoproject.com Public Sandbox" Stripe account that the committed development keys belong to, so they can test the webhook out of the box. Non-mergers can test the same flow by using their own Stripe account's test mode and pointing the app at it: create a restricted test-mode API key in your Stripe dashboard, add the corresponding stripe_secret_key (plus stripe_publishable_key and, if your account has fewer than four active products, stripe_product_id_* values) to your secrets.json, then restart the dev server with the new keys.

Install the Stripe CLI, then point it at the account whose keys the site is using:

stripe login --interactive

(Enter the test-mode secret key the site uses — for the shared sandbox, that's the committed fallback key in djangoproject/settings/common.py.)

Check which authorized contexts the CLI has, and switch to the test-mode context that matches the active keys if you have more than one:

stripe login list
stripe switch context

Next, run a webhooks forwarder that relays Stripe's test-mode events to your local development server. Keep it running for as long as you want to test donations:

stripe listen --forward-to www.djangoproject.localhost:8000/fundraising/receive-webhook/

Note: on some machines www.djangoproject.localhost doesn't resolve automatically, in which case stripe listen fails with:

[ERROR] Failed to POST: Post "http://www.djangoproject.localhost:8000/fundraising/receive-webhook/": dial tcp: lookup www.djangoproject.localhost: no such host

Add an entry like 127.0.0.1 www.djangoproject.localhost to /etc/hosts and try again (the same entry also makes the site itself reachable in a browser on those machines).

stripe listen prints a webhook signing secret (stripe_endpoint_secret: whsec_...). Export the webhook secret before starting the server (or add it to secrets.json), otherwise webhook signature verification fails and no donations are saved:

export STRIPE_ENDPOINT_SECRET=whsec_...
make run

Now, with the dev server and stripe listen both running:

1. Open http://www.djangoproject.localhost:8000/fundraising/ in your browser.
2. Fill out the donation form and pay with the test card 4242 4242 4242 4242 (future expiry, any CVC, any details).
3. You'll redirect to the thank-you page, the thank-you email is printed to the dev server console, and the stripe listen output shows the forwarded webhook events (a handful of events are ignored with HTTP 422 — only checkout.session.completed and invoice.* events create records).
4. The donation appears in the database and in the Django admin (Django heroes, Donations, Payments).
5. Reload the fundraising page: the heart's total updates to include your donation (e.g. "$50 donated of a $500,000 USD goal for ...").
6. To see subscription renewals, cancel, or failed payments, use the "Manage" links in the thank-you email (printed to the console) and the https://dashboard.stripe.com/test overview.

Note: the thank-you email is sent as plain text, so the dev server console shows it quoted-printable encoded: long lines are wrapped with a trailing = and lines beginning with spaces get a leading =. The manage-donations URL can get split across two lines (the trailing = marks the wrap), so when copying it, remove any embedded = before pasting it into your browser. E.g. in the console you'll see:

http://www.djangoproject.localhost:8000/fundraising/manage-donations/CKhd=
YAjdD39Y/

which is really:

http://www.djangoproject.localhost:8000/fundraising/manage-donations/CKhdYAjdD39Y/

(A real mail client decodes this automatically, which is why the link appears broken in the console output but may work fine from the email app.)

Running Locally with Docker

1. Build the images:

   docker compose build
   

2. Spin up the containers:

   docker compose up
   

3. Run the tests:

   docker compose run --rm web python -m manage test
   

4. Load the sample / local dev data:

   docker compose run --rm web make reset-local-db
   

   If preferred, refer to the "Install and run locally from a virtual environment" for more granular management commands to load specific data sets.

5. View the site at http://www.djangoproject.localhost:8000/ or http://dashboard.djangoproject.localhost:8000/.

6. For docs, download the documentation (takes awhile):

   docker compose exec -it web python -m manage update_docs
   

7. View the docs at http://docs.djangoproject.localhost:8000/.

git hooks

pre-commit is a framework to run hooks written in many languages, and it manages the language toolchain and dependencies for running the hooks.

prek is a reimagined version of pre-commit, built in Rust. It is designed to be a faster, dependency-free and drop-in alternative for it, while also providing some additional long-requested features.

- quoted from prek's README.md

To use git hooks locally, first install prek and then the git hooks:

• Depending on your choice of platform and tooling, you can use the related installation instructions from https://prek.j178.dev/installation/
• Install git hooks using prek install command: https://prek.j178.dev/cli/#prek-install

The installed hooks will be triggered during each commit, or can be manually triggered via prek run command: https://prek.j178.dev/cli/#prek-run If an error is found, the tool will go ahead and try to fix them for you. Review the changes and re-stage for commit when you are happy with them.