Contributing to Site
Using Docker (recommended):
- Note that if you wish, the webserver can run on the host and still use Docker for PostgreSQL.
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 particularly 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.
Now that you have everything setup, it is finally time to make changes to the site! If you have not yet read the contributing guidelines, now is a good time. Contributions that do not adhere to the guidelines may be rejected.
If you're not sure where to go from here, our detailed walkthrough is for you.