Contributing to Site

Requirements

Using Docker (recommended):

Without Docker:

  • PostgreSQL
    • Note that if you wish, the webserver can run on the host and still use Docker for PostgreSQL.

Fork the project

You will need access to a copy of the git repository of your own that will allow you to edit the code and push your commits to. Creating a copy of a repository under your own account is called a fork.

This is where all your changes and commits will be pushed to, and from where your PRs will originate from.

For any Core Developers, since you have write permissions already to the original repository, you can just create a feature branch to push your commits to instead.

Development environment

  1. Clone your fork to a local project directory
  2. Install the project's dependencies

Without Docker

Some additional steps are needed when not using Docker. Docker abstracts away these steps which is why using it is generally recommended.

1. PostgreSQL setup

Enter psql, a terminal-based front-end to PostgreSQL:

psql -qd postgres

Run the following queries to create the user and database:

CREATE USER pysite WITH SUPERUSER PASSWORD 'pysite';
CREATE DATABASE pysite WITH OWNER pysite;
CREATE DATABASE metricity WITH OWNER pysite;

Finally, enter /q to exit psql.

2. Environment variables

These contain various settings used by the website. To learn how to set environment variables, read this page first.

DATABASE_URL=postgres://pysite:pysite@localhost:7777/pysite
METRICITY_DB_URL=postgres://pysite:pysite@localhost:7777/metricity
DEBUG=1
SECRET_KEY=suitable-for-development-only
STATIC_ROOT=staticfiles

The Configuration in Detail section contains detailed information about these settings.

Notes regarding DATABASE_URL

  • If the database is hosted locally i.e. on the same machine as the webserver, then use localhost for the host. Windows and macOS users may need to use the Docker host IP instead.
  • If the database is running in Docker, use port 7777. Otherwise, use 5432 as that is the default port used by PostegreSQL.
  • If you configured PostgreSQL in a different manner or you are not hosting it locally, then you will need to determine the correct host and port yourself. The user, password, and database name should all still be pysite unless you deviated from the setup instructions in the previous section.

Run the project

The project can be started with Docker or by running it directly on your system.

Run with Docker

Start the containers using Docker Compose:

docker-compose up

The -d option can be appended to the command to run in detached mode. This runs the containers in the background so the current terminal session is available for use with other things.

If you get any Docker related errors, reference the Possible Issues section of the Docker page.

Run on the host

Running on the host is particularly useful if you wish to debug the site. The environment variables shown in a previous section need to have been configured.

Database

First, start the PostgreSQL database. Note that this can still be done with Docker even if the webserver will be running on the host - simply adjust the DATABASE_URL environment variable accordingly.

If you chose to use Docker for just the database, use Docker Compose to start the container:

docker-compose up postgres

If you're not using Docker, then use pg_ctl or your system's service manager if PostgreSQL isn't already running.

Webserver

Starting the webserver is done simply through poetry:

poetry run task start

Working on the project

The development environment will watch for code changes in your project directory and will restart the server when a module has been edited automatically. Unless you are editing the Dockerfile or docker-compose.yml, you shouldn't need to manually restart the container during a developing session.

Click here to see the basic Git workflow when contributing to one of our projects.

Django admin site

Django provides an interface for administration with which you can view and edit the models among other things.

It can be found at http://127.0.0.1:8000/admin/. The default credentials are admin for the username and admin for the password.

Configuration in detail

The website is configured through the following environment variables:

Essential

  • DATABASE_URL: A string specifying the PostgreSQL database to connect to, in the form postgresql://user:password@host/database, such as postgresql://joethedestroyer:ihavemnesia33@localhost/pysite_dev

  • METRICITY_DB_URL: A string specifying the PostgreSQL metric database to connect to, in the same form as $DATABASE_URL.

  • DEBUG: Controls Django's internal debugging setup. Enable this when you're developing locally. Optional, defaults to False.

  • LOG_LEVEL: Any valid Python logging module log level - one of DEBUG, INFO, WARN, ERROR or CRITICAL. When using debug mode, this defaults to INFO. When testing, defaults to ERROR. Otherwise, defaults to WARN.

Deployment

  • ALLOWED_HOSTS: A comma-separated lists of alternative hosts to allow to host the website on, when DEBUG is not set. Optional, defaults to the pythondiscord.com family of domains.

  • SECRET_KEY: The secret key used in various parts of Django. Keep this secret as the name suggests! This is managed for you in debug setups.

  • STATIC_ROOT: The root in which python manage.py collectstatic collects static files. Optional, defaults to /app/staticfiles for the standard Docker deployment.

Table of Contents