Installation without docker

First, reconsider if your concerns wouldn't be addressed by switching settings (e.g. rootless) or containerization daemons (e.g. nerdctl, podman, lilipod, etc.)

Pre-requisites

Note

In a server, you'll need to set passwords safely, configure the reverse proxy, configure TLS certificates in either Caddy or Nginx, add proper DNS records on your domain registrar, preserve data between docker runs, adjust the backup policy (e.g. with a remote/ off-site server), 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 all the system administration details. We highly recommend you get in contact to your IT department for a persistent installation. Nonetheless, the steps to get it up and running would be...

• Python (any version matching the ones specified here grep python-version .github/workflows/django.yml).
• Virtualenv (e.g. python3-venv package from your distro's repositories).
• PostgreSQL database (Django framework will administer tables inside it).
• E-mail server, Open port, TLS certificates, DNS routing, Reverse Proxy, Backup strategy, etc.

Steps

Warning

Execute these commands as the user that will be running/ exposing the application.

First

git clone --depth=1 [email protected]:maxplanck-ie/parkour2.git
git checkout \
  $(git describe --abbrev=0 --tags --match "[0-9]*" $(git rev-list --tags --max-count=1))  # switch to latest release ;)
python3 -m venv env_app
source ./env_app/bin/activate
pip install -r parkour_app/requirements/prod.txt

Now the core installation is done, you may move forward.

Second

We assume some environmental variables are set (e.g. LANG, LC_TIME, TZ, etc.) ... Next, you'll need to set further environmental variables (use export so that these are inherited by downstream processes). Take a look at misc/parkour.env to get an idea of what you'll need (e.g. DATABASE_URL is read by Django to authenticate with your PostgreSQL instance). Most of these variables may be skipped, we have added some sane defaults into the loading instructions at parkour_app/settings/wui/base.py (e.g. using SQLite if DATABASE_URL is unset).

A very important variable is DJANGO_SETTINGS_MODULE. You should also set this, e.g. to wui.settings.prod, so that the application will be using wui/settings/prod.py as settings module with the configuration of everything around the core (e.g. static files URL).

Third

Next, change directory into the parkour_app/ subfolder. From now on, all commands will assume this positioning.

Fourth

At last, run the application (in this example, using 4 workers and binding it to port 8000 of all available IP addresses, to be taken care afterward by a web server running as a reverse proxy). See Green Unicorn's Official Documentation for further details.

gunicorn wui.wsgi:application -t 600 -w 4 -b :8000

Fifth

At this point, the database is empty. Before populating it, we'd need to define the schema (e.g. creating empty tables, defining relation between columns/ foreign keys, etc.) For this, run python manage.py migrate --traceback. The command will run all the django-generated code matching the Model definitions of our application (e.g. files matching parkour_app/**/migrations/*.py)

Sixth

Optinally, pre-load some data: python manage.py load_initial_data. You may edit fixtures manually (e.g. files matching parkour_app/**/fixtures/*.json). For further details, check Loading Initial Data. Please note that since the primary keys (pk) are defined in such files; every time you re-load these JSON Fixtures, the database is gracefully overwritten on these items. You might prefer saving customizations with pg_dump.

Seventh

Optionally, create an admin account with the following command: python manage.py createsuperuser. You'll be asked for an email account, and a password (twice). Login, remove some of the default users that were pre-loaded and create new normal and staff users as you see fit... These default credentials may come in handy,

• [email protected] with password parkour-staff.
• [email protected] with password parkour-admin.

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

Ninth

Add any required cronjobs for a proper backup strategy. In there, you should also add: python manage.py clearsessions (mind the paths to proper python interpreter/ venv, and your application's manage.py location).

Last (but not least)

Take a look at other administrative commands, like django-admin dumpdata and/ or the database pg_dump & pg_restore. Even if you're not using docker, running make help for checking the essentials is highly recommended. And, upon the rules listed there, you may always execute in dry-run mode (e.g. make -n save-postgres) to see the sequence of instructions.

Of course, make shall be run from the repository root, one level up from your current work directory, parkour_app.