feat: build official Goldebek municipal website
Deploy / validate-dispatch (push) Successful in 1s
Deploy / scheduled-rebuild-dev (push) Skipped
Deploy / scheduled-rebuild-master (push) Skipped
Deploy / rollback-dev (push) Skipped
Deploy / rollback-master (push) Skipped
Deploy / changes (push) Successful in 6s
Deploy / app-quality (push) Successful in 1m16s
Deploy / secret-scan (push) Successful in 4s
Deploy / security-deps (push) Successful in 18s
Deploy / context (push) Successful in 1s
Deploy / app-image (push) Successful in 1m28s
Deploy / deploy-master (push) Skipped
Deploy / deploy-dev (push) Successful in 13s
Deploy / validate-dispatch (push) Successful in 1s
Deploy / scheduled-rebuild-dev (push) Skipped
Deploy / scheduled-rebuild-master (push) Skipped
Deploy / rollback-dev (push) Skipped
Deploy / rollback-master (push) Skipped
Deploy / changes (push) Successful in 6s
Deploy / app-quality (push) Successful in 1m16s
Deploy / secret-scan (push) Successful in 4s
Deploy / security-deps (push) Successful in 18s
Deploy / context (push) Successful in 1s
Deploy / app-image (push) Successful in 1m28s
Deploy / deploy-master (push) Skipped
Deploy / deploy-dev (push) Successful in 13s
This commit is contained in:
@@ -1,39 +1,10 @@
|
||||
# Next.js Website Starter
|
||||
# Website der Gemeinde Goldebek
|
||||
|
||||
Neutrale, wiederverwendbare technische Basis für eine neue Website. Das Repository enthält eine produktionsfähige Next.js-Anwendung mit Kalender-API, Bildpipeline, Tests, Containerisierung sowie CI/CD, aber bewusst keine fachlichen Inhalte oder produktiven Daten.
|
||||
Offizielle kommunale Informationswebsite auf Basis von Next.js 16 (App Router), React 19 und TypeScript. Die Anwendung rendert Seiten, Nachrichten und Termine serverseitig, lädt keine Tracker oder externen Schriftarten und wird als eigenständige Node.js-Anwendung gebaut.
|
||||
|
||||
## Technologie-Stack
|
||||
## Lokale Entwicklung
|
||||
|
||||
- Node.js 24 und npm
|
||||
- Next.js 16 App Router mit React 19 und TypeScript
|
||||
- Standalone-Serverausgabe für Docker
|
||||
- ICS-Kalender mit `ical.js`, `rrule` und Temporal
|
||||
- Zod für Runtime-Konfiguration
|
||||
- Vitest sowie ein produktionsnaher E2E-Smoke-Test
|
||||
- ESLint, Husky und lint-staged
|
||||
- Sharp für responsive Bildvarianten und Metadatenbereinigung
|
||||
- Docker Compose, Traefik und Trivy
|
||||
- Gitea-Actions-kompatible Workflows unter `.gitea/workflows/`
|
||||
|
||||
Eine Datenbank und eine Authentifizierung sind nicht Bestandteil dieser Vorlage, weil das technische Ausgangsprojekt keine solchen Systeme verwendet.
|
||||
|
||||
## Struktur
|
||||
|
||||
- `src/app/`: Seiten, Metadaten-, API- und Health-Routen
|
||||
- `src/components/`: wiederverwendbare Server- und Client-Komponenten
|
||||
- `src/server/calendar/`: ICS-Abruf, Parser, Cache, Fehlerbehandlung und Readiness
|
||||
- `src/trip-reports/`: registrierbare TSX-Beitragsmodule; im Starter leer
|
||||
- `src/data/`: neutrale Datenregistries für Downloads, Galerien und Inhaltskarten
|
||||
- `.media-source/`: Originalbilder für die Bildpipeline
|
||||
- `public/`: generierte Bilder, lokale Schriften und öffentliche Dateien
|
||||
- `scripts/`: Build-, Medien-, E2E-, Security- und Deploy-Hilfen
|
||||
- `.gitea/workflows/`: CI, Deployment, Rollback und geplante Rebuilds
|
||||
|
||||
Die vorhandenen deutschsprachigen Routen bleiben aus Kompatibilitätsgründen erhalten: `/`, `/ueber-uns`, `/informationen`, `/kalender`, `/fahrten`, `/fahrten/[slug]`, `/bilder`, `/impressum` und `/datenschutz`.
|
||||
|
||||
## Lokale Installation
|
||||
|
||||
Voraussetzungen sind Node.js gemäß `.node-version`, npm und für Container-Workflows Docker.
|
||||
Voraussetzungen: die in `.node-version` angegebene Node.js-Version und npm.
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
@@ -41,38 +12,12 @@ cp .env.example .env.local
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Die Anwendung ist anschließend standardmäßig unter `http://localhost:3000` erreichbar. Für echte Kalenderdaten muss `CALENDAR_URL` auf eine erreichbare HTTPS-ICS-Datei zeigen.
|
||||
`APP_URL` steuert Canonicals, Sitemap, robots.txt und absolute Metadaten. `CALENDAR_URL` wird vom weiterhin vorhandenen Laufzeit-Endpunkt `GET /api/events` benötigt, nicht vom Produktions-Build.
|
||||
|
||||
## Environment-Variablen
|
||||
|
||||
Alle Werte in `.env.example` sind ungefährliche Beispiele.
|
||||
|
||||
| Variable | Zweck |
|
||||
| --- | --- |
|
||||
| `APP_NAME` | Öffentlicher Name der Website |
|
||||
| `APP_URL` | Kanonische Basis-URL für SEO, Sitemap, Hostprüfung und CORS-Default |
|
||||
| `COMPANY_NAME` | Betreiber-/Organisationsname |
|
||||
| `CONTACT_EMAIL` | Öffentliche Kontaktadresse |
|
||||
| `CONTACT_PHONE` | Öffentliche Telefonnummer |
|
||||
| `CONTACT_ADDRESS` | Öffentliche Anschrift |
|
||||
| `PRIMARY_DOMAIN` | Hostname für Traefik |
|
||||
| `CALENDAR_URL` | HTTPS-URL des ICS-Kalenders; zur Laufzeit erforderlich |
|
||||
| `CORS_ORIGIN` | Kommagetrennte erlaubte Origins; Standard ist `APP_URL` |
|
||||
| `TRUSTED_PROXIES` | JSON-Liste oder CSV vertrauenswürdiger Proxy-Netze |
|
||||
| `CALENDAR_CACHE_DURATION_MS` | Cache-Dauer für Kalenderdaten |
|
||||
| `CALENDAR_FETCH_TIMEOUT_MS` | Timeout für den ICS-Abruf |
|
||||
| `DEFAULT_CALENDAR_TIMEZONE` | IANA-Zeitzone für schwebende ICS-Zeitangaben |
|
||||
| `MAX_RECURRENCE_WINDOW_MONTHS` | Maximales Vorschaufenster wiederkehrender Termine |
|
||||
| `MAX_ICS_BYTES` | Maximale Größe der Kalenderdatei |
|
||||
| `MAX_OCCURRENCES_PER_EVENT` | Obergrenze je wiederkehrendem Termin |
|
||||
| `ROUTINE_EVENT_TITLES` | Titel regulärer Termine, die nicht hervorgehoben werden |
|
||||
|
||||
`CALENDAR_URL` ist ein Runtime-Secret und wird nicht als Docker-Build-Argument verwendet. Öffentliche Identitätswerte werden beim Container-Build gesetzt, da Next.js Metadaten statisch erzeugen kann, und zusätzlich zur Laufzeit an den Container übergeben.
|
||||
|
||||
## Befehle
|
||||
## Qualitätschecks und Build
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
npm run data:validate
|
||||
npm run lint
|
||||
npm run typecheck
|
||||
npm run test
|
||||
@@ -80,64 +25,79 @@ npm run build
|
||||
npm run test:e2e
|
||||
```
|
||||
|
||||
`npm run build` bereinigt öffentliche Dateien, erzeugt beziehungsweise entfernt Bildvarianten, entfernt Bildmetadaten, prüft PDF-Metadaten und führt `next build` aus. Der E2E-Test baut die Standalone-Ausgabe, startet eine lokale ICS-Fixture und prüft Seiten, API, ETag sowie Health-Routen.
|
||||
Der Content-Validator prüft unter anderem Slugs, ISO-Daten, Quellen, `lastVerified`, abgelaufene Daten, private Veranstaltungsadressen und interne Links. Die CI- und Deployment-Workflows unter `.gitea/workflows/` bleiben maßgeblich. Das Docker-Image verwendet den Next.js-Standalone-Build.
|
||||
|
||||
Mit `npm run content:new` kann ein neues TSX-Beitragsmodul samt optionalen Originalbildern angelegt werden.
|
||||
## Content-Struktur
|
||||
|
||||
## Bilder und Dateien
|
||||
- `content/pages/pages.json`: statische redaktionelle Seiten
|
||||
- `content/news/*.json`: aktuelle Meldungen
|
||||
- `content/events/events.json`: Veranstaltungskalender
|
||||
- `data/municipality.json`: Basisdaten und Geschichte
|
||||
- `data/council.json`: Bürgermeister, Gemeindevertretung und Steuern
|
||||
- `data/services.json`: Dörpshuus, Alltagshilfe, Mobilität und Fahrbücherei
|
||||
- `data/clubs.json`: Vereine und Gruppen
|
||||
- `data/sources.json`: zentrales Quellenregister
|
||||
- `src/lib/content/`: Zod-Schemata und typisierter Zugriff
|
||||
- `src/lib/dates/`: Europe/Berlin-Datumslogik und ICS-Ausgabe
|
||||
|
||||
Originalbilder gehören in die Unterverzeichnisse von `.media-source/`. `npm run images` erzeugt responsive JPEG-, WebP- und AVIF-Varianten in `public/images/`; `npm run images:prune` entfernt Varianten ohne Quelle. Neue Alt-Texte werden projektspezifisch in der Medienkonfiguration oder im erzeugten Manifest gepflegt.
|
||||
Der öffentliche Stand darf nur verifizierte oder ausdrücklich dynamische Termine zeigen. `needs-verification` bleibt unsichtbar. Verwaltungsbezogene und volatile Daten benötigen `sourceId` und `lastVerified`.
|
||||
|
||||
Downloads werden in `public/downloads/` abgelegt und in `src/data/downloads.ts` registriert. Keine personenbezogenen, produktiven oder vertraulichen Dateien committen.
|
||||
## Neue Meldung anlegen
|
||||
|
||||
## Docker
|
||||
1. Eine JSON-Datei nach dem Schema `NewsItem` unter `content/news/` anlegen.
|
||||
2. Quelle, `lastVerified` und Status pflegen.
|
||||
3. Die Datei in `src/lib/content/index.ts` registrieren.
|
||||
4. `npm run data:validate` und die Tests ausführen.
|
||||
|
||||
Für einen lokalen Start über den vorhandenen Traefik-Stack:
|
||||
Ein Bild benötigt einen präzisen Alt-Text. Wenn der Rechteinhaber eine Kennzeichnung verlangt, muss außerdem `copyright` gepflegt werden. Bilder dürfen erst nach dokumentierter Freigabe eingebunden werden.
|
||||
|
||||
## Neuen Termin anlegen
|
||||
|
||||
Einen Datensatz in `content/events/events.json` ergänzen. Datum und Zeit werden als lokale Werte für `Europe/Berlin` gepflegt; der Wochentag wird nie gespeichert, sondern aus dem ISO-Datum berechnet. Pflicht sind mindestens ID, Slug, Titel, Startdatum, Zeitzone, Quelle, `lastVerified` und Status.
|
||||
|
||||
Straßenadressen werden nur ausgegeben, wenn `privacyApproved: true` gesetzt ist. Anschließend:
|
||||
|
||||
```bash
|
||||
CALENDAR_URL=https://example.com/calendar.ics docker compose up --build
|
||||
npm run data:validate
|
||||
npm run test
|
||||
```
|
||||
|
||||
Das externe Netzwerk heißt standardmäßig `traefik-external` und kann mit `TRAEFIK_NETWORK_NAME` geändert werden. Für einen isolierten Test ohne vorhandenes Traefik-Netz kann die Compose-Datei projektspezifisch überschrieben werden.
|
||||
Einzeltermine stehen automatisch als ICS-Datei unter `/termine/<slug>/kalender.ics` bereit, der Gesamtfeed unter `/termine/kalender.ics`.
|
||||
|
||||
Das Runtime-Image läuft ohne Root-Rechte, mit read-only Dateisystem, entfernten Linux-Capabilities, Healthcheck und Ressourcenlimits.
|
||||
## Ratsmitglieder aktualisieren
|
||||
|
||||
## CI/CD und Deployment
|
||||
Die aktuelle Liste steht in `data/council.json`. Vor einer Änderung die amtliche Quelle prüfen, `lastVerified` aktualisieren und den offenen Schreibweisen-Hinweis in `CONTENT_CHECKLIST.md` beachten. Ratsmitglieder werden ohne Rangfolge oder politische Wertung dargestellt.
|
||||
|
||||
Die Workflows bleiben vollständig erhalten:
|
||||
## Quellen und Prüfstände pflegen
|
||||
|
||||
- `.gitea/workflows/ci.yml` führt Lint, Tests, Typecheck, Build, E2E sowie Secret- und Schwachstellenscans aus.
|
||||
- `.gitea/workflows/deploy.yml` baut und scannt Images, deployt `dev` und `master`, prüft die laufende Anwendung, unterstützt Rollbacks und führt wöchentliche Rebuilds aus aktuellen Basis-Images aus.
|
||||
1. Quelle in `data/sources.json` anlegen oder aktualisieren.
|
||||
2. In den Fachdaten auf die `sourceId` verweisen.
|
||||
3. `lastVerified` auf das tatsächliche Prüfdatum setzen.
|
||||
4. Bei einem inhaltlichen Konflikt die Entscheidung aus `goldebek_website_briefing/goldebek_data_2026-09-18.json` beachten.
|
||||
5. Nicht bestätigte Angaben als `needs-verification` führen oder ganz aus dem öffentlichen Datensatz herauslassen.
|
||||
|
||||
CI ist für den lokalen Start nicht technisch erforderlich. Für gemeinsame Branches und Deployments sollte sie aktiv bleiben, weil sie reproduzierbar Build, Tests, Secret-Scans und Container prüft. Auf einem warmen Runner ist für die reine App-Prüfung typischerweise mit etwa 2–5 Minuten zu rechnen; ein kalter Runner mit LFS-, Container- und Trivy-Downloads kann etwa 5–15 Minuten benötigen. Die Security-Jobs laufen parallel. Die tatsächliche Dauer hängt von Runner, Cache, Medienumfang und Netzwerk ab; die Job-Timeouts liegen je nach Aufgabe bei 5–45 Minuten.
|
||||
## Bilder und Copyright
|
||||
|
||||
Vor dem ersten Deployment sind mindestens folgende Repository-Variablen zu setzen:
|
||||
Die derzeit eingebundenen Ortsbilder und die Wappengrafik liegen in `goldebek_website_briefing/`. Ihre Webnutzung wurde durch den Auftraggeber am 19.09.2026 bestätigt. Dateien werden weder hotgelinkt noch umgestaltet. Für neue Bilder sind Freigabe, Motivbeschreibung, Alt-Text und gegebenenfalls Fotografen-Copyright zu dokumentieren.
|
||||
|
||||
- `CI_RUNNER`, optional `PROD_RUNNER`
|
||||
- `CONTAINER_REGISTRY`
|
||||
- `APP_IMAGE_REPOSITORY`
|
||||
- `APP_NAME`, `COMPANY_NAME`, `CONTACT_EMAIL`, `CONTACT_PHONE`, `CONTACT_ADDRESS`
|
||||
- `DEV_PRIMARY_DOMAIN`, `PROD_PRIMARY_DOMAIN`
|
||||
- optional `DEV_APP_URL`, `PROD_APP_URL`, `DEV_CORS_ORIGIN`, `PROD_CORS_ORIGIN`
|
||||
- optional Stack- und Netzwerkwerte `*_DEPLOY_STACK_NAME`, `*_TRAEFIK_NETWORK_NAME`
|
||||
## Jährliche Aktualisierung
|
||||
|
||||
Benötigte Secrets:
|
||||
Mindestens jährlich sowie vor dem Livegang sind zu prüfen:
|
||||
|
||||
- `CALENDAR_URL`
|
||||
- `PACKAGES_USERNAME`, `PACKAGES_TOKEN`
|
||||
- `DEV_TRAEFIK_CERTRESOLVER`, `PROD_TRAEFIK_CERTRESOLVER`
|
||||
- Einwohnerzahl und Stichtag
|
||||
- Gemeindevertretung, Kontakte, Hebesätze und Hundesteuer
|
||||
- Dörpshuus-Gebühren und Nutzungsbedingungen
|
||||
- Buslinie und Betreiberlink
|
||||
- Fahrbücherei-Fahrplan
|
||||
- Veranstaltungskalender und Archivstatus
|
||||
- Projektstände und Bauleitplanung
|
||||
- externe Links, Quellen und `validUntil`
|
||||
- Erklärung zur Barrierefreiheit und Rechtstexte
|
||||
|
||||
Runner benötigen Docker, Zugriff auf das Zielnetzwerk und bei produktiven Deployments Zugriff auf den Zielhost.
|
||||
## Datenschutz und Suche
|
||||
|
||||
## Für ein neues Projekt anpassen
|
||||
Die Website verwendet keine Marketing-Cookies, Tracker, automatisch geladenen Karten, Drittanbieter-Schriftarten oder Video-Einbettungen. Ein Cookie-Banner ist für diese Grundkonfiguration nicht vorgesehen. Eine clientseitige Volltextsuche wurde bewusst nicht eingebaut: Die klare Informationsarchitektur und die geringe Inhaltsmenge erlauben kürzere Wege ohne zusätzlichen JavaScript-Suchindex. Das kann bei wachsendem Bestand neu bewertet werden.
|
||||
|
||||
1. Alle Werte aus `.env.example` für die neue Installation festlegen.
|
||||
2. Texte und Navigation in `src/app/` und `src/components/Header.tsx` ersetzen.
|
||||
3. Rechtstexte fachlich und rechtlich erstellen lassen.
|
||||
4. Neues Logo, Farbschema, Schriften und Medien einpflegen.
|
||||
5. Kalenderquelle und Titel regulärer Termine konfigurieren.
|
||||
6. Beitrags-, Download- und Galerie-Registries befüllen.
|
||||
7. Registry, Runner, Domains, Traefik und Secrets in CI/CD konfigurieren.
|
||||
8. Alle Qualitätsprüfungen und den finalen Secret-Scan ausführen.
|
||||
## Deployment
|
||||
|
||||
Die Beispielwerte sind nicht für eine produktive Veröffentlichung bestimmt.
|
||||
`npm run build` erzeugt einen Standalone-Build. Die vorhandenen Gitea-Workflows übernehmen Tests, Build, Container-Scan, Docker-Compose-Deployment, Healthchecks und Rollback. Produktionswerte werden über die dort dokumentierten Variablen gesetzt; Secrets gehören nicht ins Repository.
|
||||
|
||||
Reference in New Issue
Block a user