8b813c7e20
- Enhance documentation with details on automatic image builds and pushes to Gitea Container Registry. - Add instructions for pulling and running the container image, including usage in docker-compose. - Include information on the CI/CD workflow for building and pushing images based on version tags.
117 lines
3.8 KiB
Markdown
117 lines
3.8 KiB
Markdown
# 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
|
||
- tägliche Zeitplanung
|
||
- Versandprotokoll
|
||
- Docker/Compose Betrieb, inkl. automatischem Image-Build & Push in die Gitea Container Registry (per Versions-Tag)
|
||
|
||
## Start mit Docker
|
||
|
||
1. Konfiguration anlegen:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
docker compose up --build -d
|
||
```
|
||
|
||
4. Zugriff:
|
||
- [http://localhost:8080/login](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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```yaml
|
||
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):
|
||
|
||
```bash
|
||
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`).
|
||
|
||
## 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
|