FSTUM / settool-v2

Management-Engine of the Study Introductory Days (SET).

SET-Tool-v2

UI-Samples:

Base-page for logged-in users

Dashboards

Management views

Sign up

Scope:

• manage SET-Fahrt
• manage SET-Bags
• manage SET-Guidedtours
• manage SET-Tutors/Collaborators
• manage tasks and dates
• IO
  • manage and send tremplated Mails
  • send reminders
  • generate (pretty) PDF-Documents
  • export to CSV

Installation

1. Install system dependencies

sudo apt-get update
sudo apt-get install -y python3-pip python3-venv texlive-base texlive-lang-german texlive-fonts-recommended texlive-latex-extra latexmk

2. Install python-dependencies in an virtual environment

python3 -m venv venv
source venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -r requirements.txt

Development

1. Install additional dependencies after you installed the dependencies listed in Installation

sudo apt-get install -y gettext npm
python3 -m pip install -r requirements_dev.txt

2. Set the DJANGO_SETTINGS_MODULE environment option:

This Step is needed, because we have to have multiple settings files. The klopapier.settings.keycloak_settings-file uses keycloak, but because we DONT want to commit the secrets to git, this config is not useful for development (except if you want to test if keycloak works).
The klopapier.settings.dev_settings-file uses django's default modelbackend for authorisation. This backend can be populated with a user using the fixture, or the createsuperuser command mentioned below. The klopapier.settings.staging_settings-file is only used in the staging environment.

export DJANGO_SETTINGS_MODULE=klopapier.settings.dev_settings

3. Create the database with inital data by running the following command inside the project directory:

Postgres is necessary, since there are some differences between SQLite and Postgres, which have in the past caused substantial downtime.

docker run -p 5432:5432 -e POSTGRES_PASSWORD=password postgres
python3 manage.py migrate

4. (Optional step, a user can be created using the fixture below) Create an admin-account by running the following command inside the project directory:

python3 manage.py createsuperuser

Note that this doesn't set the fist_name, thus the username is shown on the website. If you want your fist_name to be shown instead, you have to add your fist name in the admin interface.

4. Start the local webserver

python3 manage.py runserver

You can now visist http://localhost:8000/ in your browser

pre-commit

Code quality is ensured via various tools bundled in pre-commit.

You can install pre-commit, so it will automatically run on every commit:

pre-commit install

This will check all files modified by your commit and will prevent the commit if a hook fails. To check all files, you can run

pre-commit run --all-files

This will also be run by CI if you push to the repository.

Sample-Data/ "Fixtures"

you can generate example-data (overrides every model with data that looks partially plausible, but is clearly not production-data) by opening the django shell using:

python3 manage.py shell

In the shell type

import settool_common.fixtures.showroom_fixture

settool_common.fixtures.showroom_fixture.showroom_fixture_state()

This operation might take a few seconds. Don't worry.

Adding Depenencies

If you want to add a dependency that is in pip add it to the appropriate requirements-file.
If you want to add a dependency that is in npm run npm i DEPENDENCY. Make shure that you do only commit the nessesary files to git.

Translation

1. Update the .po-files with

python manage.py makemessages --all

2. Edit the .po-file. Poedit is an excellent GUI for this!

   In the Settings please change:

   Setting	to value
   name	$NAME
   email	$EMAIL
   Line endings	Unix
   Wrap at	120
   check-spelling	True

3. Edit the .po-files, e.g. guidedtours/locale/de/LC_MESSAGES/django.po.

Note that pre-commit will automatically compile the translations for you.

Adding Dependencies

If you want to add a dependency that is in pip add it to the appropriate requirements-file.
If you want to add a dependency that is in npm run npm i DEPENDENCY. Make sure that you do only commit the necessary npm-files to git.

Staging

A staging environment is offered at set.frank.elsinga.de
The username is password
The password is username

Building and running the dockerfile for local development

1. you need to save your environment variables in an .env-file. The further guide assumes content similar to the following in staging/.env.

DJANGO_DEBUG="True"
DJANGO_SECRET_KEY="CHOOSE_A_SAVE_PASSWORD"
DJANGO_ALLOWED_HOSTS="0.0.0.0,localhost,127.0.0.1"

2. Build the dockerfile

docker build -t settool-staging:v1 .

3. Run the Dockerfile

docker run --env-file staging/.env -p 8080:8000 settool-staging:v1

The Staging instance is now availibe at 127.0.0.1:8080 and is pushed to the Github Container Registry for convinience.