Contributing to Site

This project is responsible for maintaining the website, all of its subdomains, and the backend API that our Python Discord Bot relies on to function.

The website is built on the Django web framework, uses django-wiki for resource pages and utilises Bulma for CSS.

This guide is new and is the process of testing and refinement. If you have any troubles following it, let staff know!

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
  3. Prepare your hosts file

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;

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:[email protected]:7777/pysite
DEBUG=1
SECRET_KEY=suitable-for-development-only
STATIC_ROOT=staticfiles
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 particularily 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 pipenv:

pipenv run 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://admin.pythondiscord.local:8000. The default credentials are admin for the username and admin for the password.