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. Other containerization stacks should work fine too (i.e. rootless containers via podman, apptainer, charliecloud, etc.)

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

Finally, further customize your database according to your needs. Use the cog icon in the top-right corner to access the 'Site Admin' panel.

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. Make a back-up!

---

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.

Remember, most make commands prepend docker exec [-it] <container-name> <command>. You'll need to use this to run commands inside the container. For example, starting an interactive root bash shell: docker exec -it parkour2-django bash, and then you may run python manage.py <command>.