MIZDB - Musikarchiv Datenbank

Datenbankverwaltung für das Archiv für populäre Musik im Ruhrgebiet e.V.

Links:

• Dokumentation
• Webseite Musikarchiv

Installation

Das Installations-Skript richtet die Docker Container und das Management Programm mizdb ein. Außerdem fragt es bei der Installation, ob die Datenbank aus einem Backup wiederhergestellt werden soll.

Note

Docker und Docker Compose müssen installiert sein.

bash -c "$(curl -sSL https://raw.githubusercontent.com/Actionb/MIZDB/master/scripts/install-mizdb.sh)"

Nach dem Ausführen des Skripts sollte MIZDB unter http://localhost/miz/ verfügbar sein.

Siehe auch:

• Source Code des Installations-Scripts
• weitere Installationsmöglichkeiten
• Deinstallation

Verwaltung

Für die Verwaltung der Anwendung steht das Programm mizdb.sh im MIZDB Verzeichnis zur Verfügung:

cd MIZDB_VERZEICHNIS && bash mizdb.sh help

Wurde MIZDB mithilfe des Installations-Skripts erstellt, so steht für den Benutzer der Befehl mizdb zu Verfügung:

mizdb help

Dieser kann anstelle von bash mizdb.sh verwendet werden (also z.B. mizdb reload anstelle von bash mizdb.sh reload).

Weitere Informationen mit einer Auflistung der verfügbaren Befehle gibt es in der Dokumentation:

• Verwaltung

Development

Installation

System Requirements

• PostgreSQL
  • für Debian/Ubuntu
  • für Fedora
• Apache2 mit Dev Headern (benötigt von mod_wsgi)
• libpq-dev (benötigt von psycopg2)
• Git
• npm

Zum Beispiel für Debian:

sudo apt update && sudo apt install python3-pip python3-venv postgresql apache2-dev libpq-dev git nodejs npm

Datenbank einrichten

# Datenbankbenutzer erstellen:
sudo -u postgres createuser mizdb_user -P --createdb
# Datenbank erzeugen:
sudo -u postgres createdb mizdb --owner=mizdb_user

Note

Es wird empfohlen, für den Datenbankbenutzer das Passwort "mizdb" zu benutzen. Dies ist das Passwort, welches standardmäßig von den Docker Containern und den Django Settings für MIZDB benutzt wird.

MIZDB installieren

# Repository klonen:
git clone https://github.com/Actionb/MIZDB MIZDB
cd MIZDB
# Virtuelle Umgebung erstellen:
python3 -m venv .venv
echo 'export "DJANGO_DEVELOPMENT=1"' >> .venv/bin/activate
. .venv/bin/activate
# Projekt Abhängigkeiten und Git Hooks installieren:
pip install -r requirements/dev.txt
npm install
pre-commit install

Anschließend entweder die Migrationen ausführen:

python3 manage.py migrate

oder ein Backup einlesen:

pg_restore --user=mizdb_user --host=localhost --dbname mizdb < backup_datei

Scripts mit Poe ausführen

Mit Poe The Poet können nützliche, vordefinierte Scripts ausgeführt werden.

Installieren mit pipx (oder siehe andere Methoden):

pipx install poethepoet

Anschließend können einzelne Scripts so ausgeführt werden:

poe test

Die folgenden Scripts sind in pyproject.toml definiert (siehe Poe Docs - Defining tasks):

Script Name	Beschreibung
server	Development Server starten
shell	Django Shell starten
test	Pytest Tests ausführen (mit Coverage)
test-q	Pytest Tests ausführen (ohne Coverage, schneller)
test-pw	Playwright Tests ausführen
drop-testdb	Alle Test-Datenbanken löschen
tox	Python tox ausführen
ruff	ruff Linter und Formatter ausführen und Probleme beheben
ruff-check	ruff check . ausführen
serve-docs	Den mkdocs Entwicklungsserver starten
build-docs	Dokumentation bauen und bei Github hochladen
docker-restart	MIZDB Docker Container neustarten
build	Docker Image bauen
publish	Docker Image bauen und hochladen
restore-db	Lokale Development Datenbank wiederherstellen

Docker Container

Wenn man Docker im Project Root ausführen möchte, muss man die Pfade für docker-compose.yaml und docker-compose.env angeben, da sich diese Dateien in dem Unterordner docker befinden, wo Docker sie nicht sucht.

Dazu sei es empfohlen, in der activate Datei der virtuellen Umgebung die Umgebungsvariablen COMPOSE_FILE und COMPOSE_ENV_FILES zu setzen:

export COMPOSE_FILE=./docker/docker-compose.yaml
export COMPOSE_ENV_FILES=./docker/docker-compose.env

Alternativ können bei jedem Docker Befehl die Pfade als Argumente übergeben werden:

docker compose -f ./docker/docker-compose.yaml --env-file=./docker/docker-compose.env up

Dev Server (Docker)

Um den Test-/Development Server zu starten:

docker compose -f docker-compose.test-server.yaml up --build -d

Der Server ist dann unter http://host_name:8090 (lokal: http://127.0.0.1:8090) erreichbar.

Tests

Einfacher Testdurchlauf

Mit coverage und ohne Playwright Tests:

pytest -n auto -m "not e2e" --cov=. --cov-report html  --cov-branch tests

Playwright

Die Playwright Browser müssen installiert sein:

playwright install

Dann Playwright Tests auszuführen:

pytest -n auto --browser firefox tests/test_site/test_playwright

Tox

Teste MIZDB mit verschiedenen Python-Versionen und den Produktions-Settings:

tox

CSS, Sass & Theme

Benutze

npm run sass-build

oder

npm run sass-watch

Um die CSS Dateien zu erstellen.

Links:

• https://getbootstrap.com/
• https://bootswatch.com/flatly/
• https://sass-lang.com/

Hilfe Seiten erzeugen

Offline-Hilfe

Um die Hilfe Seiten der MIZDB "site" app zu erzeugen, benutze:

mkdocs build -f mkdocs-offline.yml

Ein post build hook erzeugt aus den mkdocs html Dateien Django Templates und legt sie unter dbentry/site/templates/help ab.

Online-Hilfe

Hilfe Seiten mit dem Materials Theme erzeugen und bei Github Pages hochladen:

mkdocs gh-deploy -f mkdocs-online.yml

Release erstellen

1. Git-Flow release branch erzeugen:

   git flow release start '1.0.1'

   (siehe hier für mehr Informationen)

2. Versionsdatei aktualisieren.
   Dazu können Git-Flow Hooks verwendet werden: https://github.com/jaspernbrouwer/git-flow-hooks. Der folgende Befehl installiert die notwendigen Hooks im lokalen git Verzeichnis:

   ./scripts/git-flow-hooks.sh

   Siehe auch: Git-Flow Hooks with smartgit

   Alternativ steht ein Skript zur Verfügung, um die Versionsdatei zu aktualisieren:

   ./scripts/bump_version.py {major,minor,patch}

3. release branch beenden:

   git flow release finish '1.0.1'

Note

Wird git-flow-hooks benutzt, um die Versionsdatei zu aktualisieren, muss bei dem Befehl git flow release start keine Version angegeben werden; git-flow-hooks ermittelt die neue Version aus der Versionsdatei.