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), and docker-buildx-plugin.

• 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 here.

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. Run this command: make. Then, you may access the application at: http://localhost:9980/ (not 127.0.0.1!). You should see the application asking for user credentials.
4. Create a 'super' administrative user: docker compose exec parkour2-django python manage.py createsuperuser.

Use the Site Administration to remove these users afterward, and 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.

Finally, review misc/parkour.env settings and edit its contents accordingly. This file is re-read on each deployment via docker-compose.

---

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 following step, all the static files (js, css, etc.) were copied over to the corresponding container to fully serve the application through hypertext protocol. Finally, the fixtures files (json) were loaded, including the two default users.

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)