forked from kompetenzinventar/ki-backend
234 lines
5.2 KiB
Markdown
234 lines
5.2 KiB
Markdown
<!--
|
|
SPDX-FileCopyrightText: WTF Kooperative eG <https://wtf-eg.de/>
|
|
|
|
SPDX-License-Identifier: AGPL-3.0-or-later
|
|
-->
|
|
|
|
# Kompetenzinventar Backend
|
|
|
|
[](https://drone.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.
|
|
|
|
## 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
|
|
```
|