Technologien

Diese Seite gibt einen Überblick über die im Vogelschlagmelder eingesetzten Technologien. Sie richtet sich an Entwickler*innen, die am Projekt mitarbeiten oder es erweitern möchten.

Kurzprofil

Der Vogelschlagmelder ist eine Python-Webanwendung auf Basis von FastAPI, die als Docker-Container betrieben wird. Das Frontend wird serverseitig mit Jinja2-Templates gerendert und kommt ohne JavaScript-Framework aus. Als Datenbank dient SQLite.

Schicht

Technologie

Version

Programmiersprache

Python

3.11

Web-Framework

FastAPI

0.115.0

ASGI-Server

Uvicorn

0.30.1

ORM

SQLModel (SQLAlchemy + Pydantic)

0.0.22

Datenbank

SQLite

3.x

Template-Engine

Jinja2

≥ 3.1.6

Karten

Leaflet.js

1.9.4

Container

Docker + Docker Compose

–

Backend

Python und FastAPI

Die Anwendung nutzt FastAPI als Web-Framework. FastAPI basiert auf Starlette (ASGI) und Pydantic (Datenvalidierung) und bietet asynchrone Request-Verarbeitung, automatische OpenAPI-Dokumentation sowie typisierte Request-/Response-Modelle.

Als ASGI-Server kommt Uvicorn zum Einsatz, der die Anwendung auf Port 8000 ausliefert.

Abhängigkeiten

Paket

Version

Zweck

fastapi

0.115.0

Web-Framework, Routing, OpenAPI

uvicorn[standard]

0.30.1

ASGI-Server

sqlmodel

0.0.22

ORM (SQLAlchemy + Pydantic)

jinja2

≥ 3.1.6

Serverseitige HTML-Templates

python-multipart

0.0.9

Multipart-Formulardaten und Datei-Uploads

email-validator

2.2.0

E-Mail-Validierung nach RFC 5321/5322

httpx

0.27.0

Asynchroner HTTP-Client (Matrix-API)

Pillow

10.4.0

Bildverarbeitung und Formatkonvertierung

pillow-heif

0.18.0

HEIC-/HEIF-Unterstützung (iPhone-Fotos)

nh3

≥ 0.2.14

HTML-Sanitisierung gegen XSS

pytest

8.3.3

Test-Framework

Datenbank

Als Datenbank wird SQLite eingesetzt – eine dateibasierte, serverlose Datenbank, die direkt in den Anwendungsprozess eingebettet ist. Die Datenbankdatei liegt unter /app/data/vogelschlagmelder.db und wird über ein Docker-Volume persistiert.

Der Datenbankzugriff erfolgt über SQLModel, ein ORM das SQLAlchemy und Pydantic vereint. Datenbankmodelle sind gleichzeitig Pydantic-Modelle mit Typhinweisen und Validierung.

Schema-Migrationen werden manuell über ALTER TABLE-Befehle mit PRAGMA-Prüfungen durchgeführt (kein Alembic).

Bildverarbeitung

Pillow und pillow-heif übernehmen die Bildverarbeitung:

  • Automatische HEIC → JPEG-Konvertierung (iPhone-Unterstützung)

  • EXIF-basierte Orientierungskorrektur (Auto-Rotation)

  • RGBA → RGB-Umwandlung mit weißem Hintergrund

  • JPEG-Qualitätsoptimierung (Qualitätsstufe 85)

Kommunikation

E-Mail: Benachrichtigungen werden über das in Python eingebaute smtplib mit TLS-Verschlüsselung versendet.

Element/Matrix: Die Integration mit dem Matrix-Protokoll erfolgt über httpx (asynchroner HTTP-Client), der direkt die Matrix-Client-API anspricht (/_matrix/client/r0/). Ein dediziertes SDK wird nicht verwendet.

Frontend

Rendering

Das Frontend wird vollständig serverseitig mit Jinja2 gerendert. Es gibt kein Single-Page-Application-Framework – alle Seiten werden als HTML vom Server ausgeliefert.

CSS

Das Styling erfolgt über eine einzige, handgeschriebene CSS-Datei (style.css) mit CSS-Custom-Properties für die Farbgestaltung. Es wird kein CSS-Framework (kein Bootstrap, kein Tailwind) eingesetzt.

  • Schriftart: Inter (via CDN rsms.me) + System-Fonts als Fallback

  • Layout: Flexbox-basiertes responsives Design

  • Breakpoint: 900 px für mobile Ansichten

  • Farbsystem: Dynamisch über Admin konfigurierbar (CSS-Custom-Properties)

JavaScript

Das Frontend nutzt Vanilla JavaScript (ES6+) ohne Framework (kein React, Vue oder Angular).

Karten

Für die interaktive Kartenansicht wird Leaflet.js 1.9.4 über CDN (unpkg.com) eingebunden. Als Kartenkacheln dienen die Tiles von OpenStreetMap (primär tile.openstreetmap.org, Fallback tile.openstreetmap.de).

Funktionen: Markersetzung, Geolokalisierung, Radius-Anzeige (erlaubte/eingeschränkte Zonen), Heatmap-Overlay.

Sicherheit

Mechanismus

Umsetzung

Passwort-Hashing

PBKDF2-SHA256, 120.000 Iterationen (hashlib)

CSRF-Schutz

HMAC-SHA256-Token mit Zeitstempelablauf (1 h)

HTML-Sanitisierung

nh3-Bibliothek als Jinja2-Filter

Datei-Upload-Validierung

Magic-Byte-Prüfung + Größenbegrenzung

HTTP-Security-Header

CSP, HSTS, X-Frame-Options, X-Content-Type-Options

Sitzungsverwaltung

HttpOnly/SameSite/Secure-Cookies (24 h Gültigkeit)

Rate-Limiting

Max. 5 Fehlversuche / 5 Min. → 15 Min. Sperre

Infrastruktur

Die Anwendung wird als Docker-Container betrieben:

  • Basis-Image: python:3.11-slim

  • Nicht-Root-Benutzer: appuser (UID 1001)

  • Persistenz: Docker-Volume ./data:/app/data für Datenbank und Uploads

  • Healthcheck: GET /healthz alle 30 Sekunden

  • Neustart-Richtlinie: unless-stopped

Die Konfiguration erfolgt vollständig über Umgebungsvariablen in der docker-compose.yaml (Zugangsdaten, SMTP, Matrix, CSRF-Secret, Produktionsmodus).

Handbuch

Dieses Handbuch wird mit folgenden Werkzeugen erstellt:

Werkzeug

Version

Zweck

Sphinx

≥ 9.0

Dokumentationsgenerator

MyST-Parser

≥ 2.0

Markdown-Unterstützung für Sphinx (.md statt .rst)

sphinx-design

≥ 0.5

Erweiterte UI-Komponenten (Grids, Cards, Tabs)

Theme: Alabaster (klassisches, responsives Sphinx-Theme) mit angepasstem Stylesheet (nabu.css) in den NABU-Markenfarben.

MyST-Erweiterungen: Colon-Fence-Syntax (:::), Definitionslisten, Feldlisten, Substitutionen ({{ }}), HTML-Bilder und automatische Überschriftenanker bis Ebene 3.

Build-Befehl:

make html

Die kompilierte HTML-Dokumentation wird im Verzeichnis handbuch/ abgelegt.