Contributing to Site
Using Docker (recommended):
- 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.
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;
/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 METRICITY_DB_URL=postgres://pysite:[email protected]:7777/metricity DEBUG=1 SECRET_KEY=suitable-for-development-only STATIC_ROOT=staticfiles
The Configuration in Detail section contains detailed information about these settings.
- If the database is hosted locally i.e. on the same machine as the webserver, then use
localhostfor 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
5432as 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
pysiteunless 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:
-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.
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.
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.
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:
METRICITY_DB_URL: A string specifying the PostgreSQL metric database to connect to, in the same form as
DEBUG: Controls Django's internal debugging setup. Enable this when you're developing locally. Optional, defaults to
LOG_LEVEL: Any valid Python
loggingmodule log level - one of
CRITICAL. When using debug mode, this defaults to
INFO. When testing, defaults to
ERROR. Otherwise, defaults to
ALLOWED_HOSTS: A comma-separated lists of alternative hosts to allow to host the website on, when
DEBUGis not set. Optional, defaults to the
pythondiscord.comfamily 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 collectstaticcollects static files. Optional, defaults to
/app/staticfilesfor the standard Docker deployment.