ki-backend/README.md

<!--
SPDX-FileCopyrightText: WTF Kooperative eG <https://wtf-eg.de/>

SPDX-License-Identifier: AGPL-3.0-or-later
-->

# Kompetenzinventar Backend

[![Build Status](https://drone.wtf-eg.de/api/badges/kompetenzinventar/ki-backend/status.svg?ref=refs/heads/main)](https://drone.wtf-eg.de/kompetenzinventar/ki-backend)
[![REUSE status](https://api.reuse.software/badge/git.wtf-eg.de/kompetenzinventar/ki-backend)](https://api.reuse.software/info/git.wtf-eg.de/kompetenzinventar/ki-backend)

## Über

Dieses Repo enthält das Backend des Projekts Kompentenzinventar - einer Webapplikation zur Erfassung von Userprofilen für die WTF eG.

Implementiert ist das Backend mit Flask.

### Mitmachen

Du kannst gerne bei der Entwicklung des Kompetenzinventars mitmachen.

- Fehler oder fehlende Funktionen erfassen. Bitte direkt über die [Issues](https://git.wtf-eg.de/kompetenzinventar/ki-backend/issues) in Gitea.
- Dokumentation oder Implementierung verbessern. Bitte forke hierzu das Projekt, branche von `main` ab und erstelle dann einen [Pull Request](https://git.wtf-eg.de/kompetenzinventar/ki-backend/pulls).

### Kommunikation

Folgende Kanäle gibt es für die Kommunikation über das Kompetenzinventar:

- Die [Issues](https://git.wtf-eg.de/kompetenzinventar/ki-backend/issues) im WTF Gitea.
- Den Bereich [AG Entwicklung](https://forum.wtf-eg.de/c/interna/ag-entwicklung/21) im WTF Forum.
- Einen Raum in Matrix. Zutritt per Einladung, frlan lädt ein, eine einfache PN im Forum reicht.

### Repos

* **[ki-backend](https://git.wtf-eg.de/kompetenzinventar/ki-backend)** (dieses Repo) enthält das Backend
* [ki-frontend](https://git.wtf-eg.de/kompetenzinventar/ki-frontend) enthält das Frontend
* Weitere Repositories befinden sich in der Gitea Organisation [Kompetenzinventar](https://git.wtf-eg.de/kompetenzinventar).
## Entwicklung

### Abhängigkeiten

- Python 3.8
- [Pipenv](https://github.com/pypa/pipenv)


### Entwicklungsumgebung aufbauen und starten

Ggf. vorher aufräumen

```
rm storage/ki.sqlite
```

```
cp env.dev .env
pipenv install --dev
pipenv shell
flask db upgrade
flask seed --dev
flask run
```

http://localhost:5000/


### pre-commit einrichten

Damit mensch nicht verpeilt kaputten Code Style zu commiten,
kann pre-commit benutzt werden. Einmal im Virtualenv ausführen:

```
pre-commit install
```


### `alembic` Befehle

`alembic` ist über [Flask-Migrate](https://flask-migrate.readthedocs.io/en/latest/index.html) eingebunden.
Es wird über `flask db ...` aufgerufen.


### QA

```
python -m unittest discover ki

# Code formatieren
yapf -i --recursive ki/

# Code-Style prüfen
flake8
```


### Testbenutzer

#### Lokal ohne LDAP

Für ein Login ohne LDAP werden die Benutzer aus der [`auth.yml`](./data/auth.yml) benutzt.


#### Lokal mit LDAP

Einen LDAP Server aufsetzen. Z.B. https://directory.apache.org/apacheds/

In der `.env` die LDAP Dinge ausfüllen (siehe [`env.dev`](./env.dev)).


### Beispiel-Requests

Beispiele brauchen curl und jq.

```
curl -s \
    -D "/dev/stderr" \
    http://localhost:5000/skills?search=ph | jq
```

```
curl -s \
    -D "/dev/stderr" \
    http://localhost:5000/languages?search=fr | jq
```

```
curl -s \
    -D "/dev/stderr" \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{"username": "peter", "password": "geheim"}' \
    http://localhost:5000/users/login | jq
```

```
curl -s \
    -D "/dev/stderr" \
    -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer 22e6c5fc-8a5a-440e-b1f4-018deb9fd24e" \
    -d '{"pronouns": "Herr Dr. Dr."}' \
    http://localhost:5000/users/1/profile | jq
```

```
curl -s \
    -D "/dev/stderr" \
    -H "Authorization: Bearer 22e6c5fc-8a5a-440e-b1f4-018deb9fd24e" \
    http://localhost:5000/users/1/profile
```

Profilsuche nach Nickname:

```
curl -s \
    -D "/dev/stderr" \
    -H "Authorization: Bearer 22e6c5fc-8a5a-440e-b1f4-018deb9fd24e" \
    http://localhost:5000/users/profiles
```


## Docker

### Image bauen

```
docker build --tag ki_backed .
```


### Container starten

Im Beispiel wird die SQLite Datenbank `./data/ki_backend.sqlite` verwendet.

DB-Datei anlegen

```
touch data/ki_docker.sqlite
chmod a+rw data/ki_docker.sqlite
```

Container starten

```
docker run \
    --name=ki_backend \
    -v ${PWD}/data/ki_docker.sqlite:/app/data/ki_docker.sqlite \
    -e SQLALCHEMY_DATABASE_URI='sqlite:///data/ki_docker.sqlite' \
    -p 5000:5000 \
    ki_backend
```

Skills und Sprachen importieren

```
docker exec ki_backend sh -c "cd /app && /pyroot/bin/flask seed"
```


## Produktionsumgebung

Für die Produktionsumgebung wird [waitress](https://docs.pylonsproject.org/projects/waitress/en/latest/) benutzt.

[`run_prod.py`](./run_prod.py) führt die DB Migrationen aus und startet den Server.


## Integrationsumgebung

Per [`docker-compose`](https://docs.docker.com/compose/) kann eine Integrationsumgebung gestartet werden.  
Beide Projekte müssen nebeneinander ausgecheckt sein:

```
./
  ki-backend
  ki-frontend
```

Alles starten:

```
docker-compose up
```

Dann http://localhost:13337 aufrufen.

### Workaround, falls der Zugriff auf registry.wtf-eg.net nicht möglich ist

Voraussetzung: 

[ki-backend-docker](https://git.wtf-eg.de/kompetenzinventar/ki-backend-docker) muss parallel zum `ki-backend` ausgecheckt sein.

```
cd ki-backend-docker
docker build . --target base -t ki-backend-base
docker build . --target builder -t ki-backend-builder
```

Ändern der 2 Einträge im `Dockerfile` des `ki-backend`:

- registry.wtf-eg.net/ki-backend-builder:1.0.0 -> ki-backend-builder
- registry.wtf-eg.net/ki-backend-base:1.0.0 -> ki-backend-base

Danach sollte `docker-compose up` funktionieren.

## Lizenzen

Dieses Projekt erfüllt die [REUSE](https://reuse.software/) Spezifikation.

Die Lizenzen aller Dateien im Projekt können mit diesem Kommando aufgelistet werden:

```
reuse spdx
```