TK-Wiki-Newsletter/README.md

TK Wiki Newsletter Admin

Produktionsnahes internes Tool zur Erstellung von Thomas-Krenn.AG Newslettern auf Basis der letzten Wiki-Änderungen.

Funktionen

• Login und Benutzerverwaltung mit RBAC (admin, editor, reader)
• Verpflichtender CSRF-Schutz auf allen POST-Formularen
• Filter in der Web-UI:
  • Zeitraum in Tagen oder „Letzter Monat“
  • Artikel-Auswahl: alle, nur neue oder nur bearbeitete Artikel
  • Kategorie
• Redaktioneller Feinschliff pro Ausgabe:
  • Redaktionsnotiz – optionaler Hinweistext, der als eigene Box im Newsletter erscheint
  • Top-Highlights – bis zu 3 Artikel per Titel hervorheben (erscheinen oben als Highlight-Box)
• Datenquelle: MediaWiki API (recentchanges über wikiDE/api.php)
• E-Mail-Layout im Thomas-Krenn Corporate Design:
  • Hero-Header mit Logo, Artikel-Karten mit „Zum Beitrag“-Button, Kontakt- und Adress-Footer
  • Neu-/Bearbeitet-Trennung, Zusammenfassungs-Kacheln, Outlook-taugliche Kopiervorschau
• Export:
  • Plain Text (für Outlook)
  • Raw HTML
• Optionaler SMTP-Versand:
  • UI-konfigurierbar
  • Verteilerlisten
  • flexibler Zeitplan (täglich / wöchentlich an bestimmten Wochentagen / monatlich an einem Tag) über einen Hintergrund-Scheduler
  • eigene Inhalts-Vorgaben für den geplanten Versand (Zeitraum, Artikel-Auswahl, Kategorie)
  • manueller Versand nur per Button – „Generieren“ verschickt nie automatisch
  • Versandprotokoll
• Docker/Compose Betrieb, inkl. automatischem Image-Build & Push in die Gitea Container Registry (per Versions-Tag)

Start mit Docker

1. Konfiguration anlegen:

   cp .env.example .env
   

2. Wichtige Werte in .env setzen:

   • HOST_PORT (z. B. 8080, falls 8000 bereits belegt ist)
   • SECRET_KEY
   • ADMIN_BOOTSTRAP_EMAIL
   • ADMIN_BOOTSTRAP_PASSWORD

3. Start:

   docker compose up --build -d
   

4. Zugriff:

   • http://localhost:8080/login (oder dein HOST_PORT)

Container-Image (Gitea Packages)

Fertige Images werden automatisch in die Gitea Container Registry veröffentlicht:

git.hexahost.dev/smueller/tk-wiki-newsletter

Verfügbare Tags: latest, die Version (X.Y.Z, X.Y, X) sowie der kurze Commit-SHA.

Image ziehen und mit vorhandener .env starten:

docker login git.hexahost.dev
docker pull git.hexahost.dev/smueller/tk-wiki-newsletter:latest
docker run -d --name tk-newsletter-admin \
  --env-file .env \
  -p 8080:8000 \
  -v newsletter_data:/app/data \
  git.hexahost.dev/smueller/tk-wiki-newsletter:latest

Alternativ in docker-compose.yml statt build: . das Image referenzieren:

services:
  newsletter-admin:
    image: git.hexahost.dev/smueller/tk-wiki-newsletter:latest
    # build: .   # <- nicht mehr nötig, wenn das fertige Image genutzt wird

Automatischer Build (CI/CD)

Der Workflow .gitea/workflows/docker-build.yml baut und pusht das Image über Gitea Actions.

• Auslöser: nur beim Setzen eines Versions-Tags v* (kein Build bei normalen Pushes auf dev/main).

• Release-Ablauf (Build bei Merge dev → main mit Version):

  git checkout main
  git merge --no-ff dev
  git push origin main
  git tag v1.0.0
  git push origin v1.0.0   # <- startet Build & Push
  

• Benötigte Repo-Secrets (Settings → Actions → Secrets):

  • REGISTRY_TOKEN: Gitea Access-Token mit Scope Package: Read and write
  • REGISTRY_USER (optional): Registry-Benutzername, falls abweichend vom Repo-Owner

• Optionale Repo-Variable: REGISTRY, um den Registry-Host zu überschreiben (Default git.hexahost.dev).

Admin-Login & Passwort zurücksetzen

• Das Login erfolgt über E-Mail + Passwort (kein separater Benutzername). Beim ersten Start wird der Admin aus ADMIN_BOOTSTRAP_EMAIL / ADMIN_BOOTSTRAP_PASSWORD angelegt.

• Wichtig: Existiert der Admin bereits (persistente DB im Volume newsletter_data), wird eine spätere Passwort-Änderung in der .env normalerweise nicht übernommen.

• Um Passwort/Rolle/Status auf die .env-Werte zurückzusetzen: ADMIN_BOOTSTRAP_RESET=true setzen und Container neu starten:

  docker compose up -d --force-recreate
  

  Nach erfolgreichem Login ADMIN_BOOTSTRAP_RESET=false setzen, damit UI-Passwortänderungen nicht bei jedem Neustart überschrieben werden.

Sicherheits-Hinweise für Produktion

• Reverse Proxy (z. B. Nginx/Traefik) mit TLS vor den Container setzen.
• SECRET_KEY lang und zufällig setzen.
• Bootstrap-Admin-Passwort nach erstem Login ändern.
• Netzwerkzugriff auf interne IPs/Netze beschränken.
• Regelmäßige Backups des data Volumes.

Rollenmodell

• reader: darf Ergebnisse sehen
• editor: darf Newsletter generieren und sofort versenden
• admin: zusätzlich Benutzerverwaltung und SMTP-Konfiguration