diff --git a/README.md b/README.md new file mode 100644 index 0000000000000000000000000000000000000000..41c7a3d912180b5f3b158618991e395c1aba060f --- /dev/null +++ b/README.md @@ -0,0 +1,58 @@ +# Lehrpreis Nominierungs-Website + +Or: Some software that lets you collect nominations for instances of awarding +occasions. Primarily suited for teaching awards, but should be easy to adapt to +any type of award. + +## Basic Installation Guide + +This software is implemented in Python. It is recommended to use a virtual +environment via `python3 -m venv venv`. Then install all requirements per +`./venv/bin/pip -r requirements.txt`. This includes psycopg2-binary for a +postgres database. For the database you may use anything supported by +SQLAlchemy. The database schema can be created via `createdb.py`. + +Copy `config.example.py` to `config.py`. Important options are the following: + +- `SECRET_KEY`: Insert some random bytes here. +- `SQLALCHEMY_DATABASE_URI`: In case of problems, refer to the SQLAlchemy docs. +- `DEBUG`: For a production deployment, set to `False`. +- `BABEL_DEFAULT_LOCALE`: Currently `'en'` and `'de'` are supported. +- `BABEL_DEFAULT_TIMEZONE`: Set a tzdata compatible timezone here. +- `USER_GROUP`: Set to a group that is allowed to login. +- `AD_HOST`, `AD_DOMAIN`, `AD_USER_DN`, `AD_GROUP_DN`, `AD_CA_CERT` are derived + from your active directory setup. +- `BRANDING_APP_NAME`: Set the website name in de/en locales. +- `BRANDING_APP_URL`: URL used when printing an external link to the website. +- `BRANDING_ORG_NAME`: The awarding organizations name. +- `BRANDING_LOGO`: Your logo to be displayed in the upper left. +- `BRANDING_CONTACT`: The organizations contact address. Should be you(, too). +- `BRANDING_INFORMATION`: Analog to `APP_NAME`. Printed above the nomination + form. +- `MAIL_ENABLED`: Set to `False` if you do not want mail notifications about + new nominations. +- `MAIL_ADDRESS`: Notification recipient. +- `MAIL_HOST`: SMTP host sending the notification. +- `MAIL_LOCALE`: Analog to `DEFAULT_LOCALE`. + +Compile the translations via `./venv/bin/pybabel compile -d translations`, else +only the english language will work. For running `lehrpreis.py` you should use +some WSGI middleware, e.g. uwsgi. + +There is an Ansible role for all this. + +## Usage Guide (German) + +- Jeder kann auf der Startseite neue Vorschläge eintippen. +- Login ist oben rechts im Menü verlinkt. Per AD-Account. +- Danach taucht ein Menüpunkt "Manage" auf. +- Dort lassen sich Instanzen (aka Semester) verwalten. +- Pro Instanz lassen sich Nominierungen einsehen (grüner Button). +- Nominierungen werden immer für die datumsweise näxte, aktivierte + Instanz angenommen. Wenn es keine solche aktivierte gibt, wird + lediglich auf das Verleihungsdatum der näxten hingewiesen. Sonst wird + darauf hingewiesen, dass es nichts zu nominieren gibt. +- Pro Nominierung werden Name, Modul, Grund und Kategorie gesammelt. +- Pro Instanz werden Name, Datum, Aktiviertheit und Kategorien gespeichert. + (Und auch die Nominierungen...) +