Installation

Pre-requisites

To carry out the deployment (ideally, on a server) of this Django application, we're using Docker with docker-compose-plugin (v2). If you're using 'Docker Desktop' on Linux, we are all set.

On MacOS, you should also install "GNU sed" and make it available as sed instead of gsed (detailed instructions, here).

On Windows, you should run this under Git Bash, or WSL.

Note: If you prefer not to use Docker, then you may run this application with a Python virtual environment. Such instructions are provided at the bottom of our Contributing guidelines (Under the 'Without docker' section), this is meant to clarify some details for Python developers.

Steps

1. Install the system requirements 🐳, then download the latest Parkour2 release.
2. Decompress this anywhere, and rename the folder with all the files to 'parkour2' instead of 'parkour2-x.y.z' (where x.y.z is the version number). Else, all the containers names and volumes would change, and the Makefile would be 'broken'.
3. Copy misc/parkour.env.sample file to misc/parkour.env and edit its contents accordingly. For the time being, and demo purposes, you can leave this as it is.
4. Optionally, add your email and password in the aforementioned file using the variables SETUP_ADMIN_EMAIL and SETUP_ADMIN_PASSWORD.
5. Run this command: make. Then, you may access the application at: http://127.0.0.1:9980/ (not localhost!). You should see the application asking for user credentials. To log in, use the admin account from parkour.env (previous step) or create a super-user (next step)...
6. Optionally, create any extra admin user(s) with the following command: docker compose run parkour2-django python manage.py createsuperuser.

Finally, you may want to edit the JSON data to be loaded through the use of fixtures (Pro tip: there's a load-fixtures GNU Make rule), or just use the Site Administration to populate your database according to your needs (see the user manual for details).

To ease further DevOps tasks, common routines are bundled as rules at a Makefile, run make help to see the most common. For example, to stop the containers, use make down.

---

Note

When you ran make, the default rule, deploy was triggered. This one, adjusted settings in webserver, and dockerfile, created a network namespace for the containers, installed django among other dependencies inside a python container, built another container with latest postgresql for the database, and last a container with the webserver (caddy). As a final step, all the static files (js, css, etc.) were copied over to the corresponding container to fully serve the application through hypertext protocol.

In a real scenario, you'll need to preserve data between docker runs, configure TLS certificates in the web server, add DNS records, adjust the backup policy (e.g. adding remote/ off-site), probably provision a mail server, etcetera.

Furthermore, it's up to the System Administrator to decide if a simple SQLite database is enough. Yet, this kind of deployment wasn't tested in production, and we advise all contributors to stay away from changing the database provider.

Of course, the application could be run locally without any containerization, this is supported but will require some adjustments (e.g. loading parkour.env global vars for the settings)