Installation

Pre-requisites

Note

In a server, you'll need TLS certificates in either Caddy or Nginx (reverse proxies), add proper DNS records on your domain registrar, adjust the backup policy (e.g. with a remote/ off-site server holding snapshots), probably provision a mail server, etcetera.

The following instructions are only meant to give you a glimpse into the ease of running our Web Application, ignoring many system administration details. We highly recommend you get in contact to your IT department for a persistent installation, specially if this is your first time deploying a dynamic web application. Nonetheless, the steps to get it up and running would be the following, with these software requirements.

Software requirements

Our main deployment strategy is using Docker with docker-compose-plugin (v2), and docker-buildx-plugin.

• on Linux, install 'Docker Desktop', and 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 these commands under Git Bash, or WSL.

Note

Other containerization stacks should work fine too (i.e. rootless containers). If you prefer not to use Docker; or any other containerization, 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. Also, check the corresponding Wiki Post-Install sub-page: Loading Initial Data.

Important

To ease common Development-n-Operations tasks, routines are encapsulated as rules in a Makefile at the repo root. Run make help to see some of the available behaviors. Check the Wiki Post-Install sub-page: DevOps for further details.

Finally, review misc/parkour.env settings and edit its contents accordingly. This file is re-read on each deployment via docker-compose. Check our Wiki's Post-Install sub-page: Backups sooner rather than later ;)

---

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.

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 anything else... for example python manage.py shell_plus --ipython is a handy command for any developer or contributor. If you're looking forward to being one, please check our Wiki's sub-page CONTRIBUTING.