124 lines
9.1 KiB
Markdown
124 lines
9.1 KiB
Markdown
# Werkjournal
|
|
|
|
Private Arbeitszeit- und Habit-Erfassung mit Kotlin, Vaadin Flow und Spring Boot.
|
|
|
|
**Stand: E-Mail-Anmeldung aktiv; Ersteinrichtung erfolgreich bestätigt.** Private Konten und der getrennte gemeinsame Gastzugang sind verfügbar. Vorhandene Daten müssen bei allen weiteren Migrationen erhalten bleiben.
|
|
|
|
## Planung und Arbeitsweise
|
|
|
|
- `werkjournal.werkbaum`: Entscheidungen und aktueller Umsetzungsstand.
|
|
- `gherkin/`: englische Abnahmeszenarien; noch nicht vollständig implementiert.
|
|
- `docs/implementation/`: geprüfte Infrastruktur, Toolchain und Testzuordnung.
|
|
|
|
Ein Umsetzungsknoten wird vor Beginn mit `[~]` committet und gepusht. Nach erfolgreicher Prüfung folgt `[x]` mit Abschlusscommit und Push. Abgeschlossene Entscheidungen sind ausdrücklich als solche beschriftet und nicht mit ausgelieferter Funktion gleichzusetzen.
|
|
|
|
## Anwendung bauen
|
|
|
|
```bash
|
|
./gradlew test bootJar -Pproduction=true
|
|
```
|
|
|
|
Der gepinnte Gradle-Wrapper prüft seine Distribution per SHA-256. Build und Tests verwenden Temurin JDK 25; Download und Prüfsumme sind in `packaging/jdk.properties` fixiert. Das Produktionsartefakt ist `build/libs/werkjournal.jar`. `tools/ci-jvm` baut, testet und prüft das JAR mit 256 MiB Heap und 192 MiB Metaspace in einer isolierten Testumgebung.
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
remote backend install-jdk
|
|
# Nach Änderung des gepinnten JDK-Stands:
|
|
remote backend install-jdk --force
|
|
```
|
|
|
|
Die Installation benötigt keine Root-Rechte, verwendet eine SSH-Verbindung und aktiviert erst das vollständig heruntergeladene, geprüfte JDK. Ziel ist standardmäßig `~/opt/jdk25` beim Werkjournal-User. Bestehende JDK-Releases bleiben erhalten, damit laufende JVMs ihre Bibliotheken weiter erreichen. Geheimnisse gehören nicht in die JDK-Konfiguration.
|
|
|
|
GraalVM ist optional zurückgestellt. Nur `-Pnative=true` aktiviert dessen Gradle-Plugin; `tools/ci-native` bleibt ein experimenteller Einstieg ohne CI-Trigger oder Freigabeanspruch. Die bisherigen Ergebnisse stehen in `docs/implementation/native-spike.md`.
|
|
|
|
Die Anwendung bindet standardmäßig an `127.0.0.1:18090`. `/api/v1/info` liefert die Buildversion, `/` das Heute-Dashboard.
|
|
|
|
Ein separates Bookworm-Rootfs für Werkdock lässt sich lokal über `tools/build-rootfs` vorbereiten. Dazu wird ein lokaler Docker-Dienst verwendet; auf Hostsharing laufen Builds anschließend in Werkdock. Die erzeugten Dateien liegen unter dem git-ignorierten `work/`.
|
|
|
|
Mit direnv und `direnv allow` nimmt `.envrc` das Verzeichnis `tools/` in den PATH auf. Produktionsgeheimnisse bleiben außerhalb des Repositorys.
|
|
|
|
## Konten und Gastzugang
|
|
|
|
Auf dem Server ist `WERKJOURNAL_GUEST_MODE=false` gesetzt. Die Loginseite bietet E-Mail-Anmeldung und einen ausdrücklichen Gastzugang. Der bisherige gemeinsame Gastbereich bleibt getrennt von privaten Konten. Die Datenbank liegt unter `data/werkjournal.mv.db`. Die frühere Erlaubnis, Gastdaten zu verwerfen, gilt nicht mehr. Migrationen benötigen erhaltende Changesets, einen Test mit befülltem Vorgängerstand und eine konsistente Sicherung vor der Migration; siehe `docs/implementation/deployment.md`.
|
|
|
|
Das Datenfundament ist unter `docs/implementation/foundation.md` beschrieben. Die Kunden-/Projektpflege ist unter `/catalog` verfügbar. Der Quellstand enthält unter `/habits` frei konfigurierbare Gewohnheiten mit Tageszählern und optionalen Tages-/Wochenminima und -maxima. Grenzen sind Hinweise und blockieren das Zählen nicht. Einmalige, veränderbare Startvorgaben sind Kunde/Projekt „Allgemein“ sowie „Lesen“ und „Spaziergänge“ (Tagesminimum 1, Wochenminimum 5). Details und Testnachweise: `docs/implementation/habits.md`. Unter `/work` lassen sich Arbeitszeiten erfassen und ändern; Konflikte erhalten den Entwurf und erfordern eine ausdrückliche Auflösung. Entwürfe bleiben pro Tab erhalten und lassen sich auf demselben Gerät wiederaufnehmen. Details: `docs/implementation/work.md`. Dieser Funktionsstand ist öffentlich verfügbar.
|
|
|
|
## Erstdeployment
|
|
|
|
```bash
|
|
remote backend deploy-prototype --artifact /pfad/zum/geprueften-ci-release
|
|
```
|
|
|
|
Das Verzeichnis enthält `werkjournal.jar` und das dazugehörige `manifest.json` aus einem erfolgreichen Werkator-Build. Der Befehl prüft den Hash lokal und auf dem Zielserver und baut nicht neu. Er richtet den systemd-User-Service sowie HTTP-Weiterleitung und HTTPS-Proxy auf dem Werkjournal-Host ein. Bereits vorhandene Releases, Dienste oder H2-Dateien werden abgelehnt: für reguläre Upgrades mit Datensicherung und Rollback dient `remote backend deploy`.
|
|
|
|
Betriebsstand, Verzeichnisse und Prüfergebnisse: `docs/implementation/first-deploy.md`.
|
|
|
|
Der laufende Dienst lässt sich mit `remote backend status` prüfen und mit
|
|
`remote backend start|stop|restart` steuern. `remote backend enable|disable`
|
|
ändert nur den Autostart. `remote backend log --lines 30` zeigt Journalzeilen,
|
|
`remote backend log --follow` folgt neuen Meldungen. Mutierende Befehle verwenden
|
|
die Deployment-Sperre; vorhandene Wartung bleibt bestehen. Details und Fehlerfälle:
|
|
`docs/implementation/service-control.md`.
|
|
|
|
`remote backend setup` schreibt die versionierte Unit und lädt systemd neu,
|
|
ohne den Dienst neu zu starten. `remote backend info` prüft Version/Commit
|
|
sowie interne und öffentliche Bereitschaft. `remote ssh [COMMAND ARG...]`
|
|
öffnet eine Shell oder führt einen Befehl mit getrennten Argumenten aus.
|
|
Details und vollständiger Befehlsabgleich: `docs/implementation/remote-utilities.md`.
|
|
|
|
Die angebundenen Fach- und Chromium-Gherkin-Szenarien laufen im normalen Testlauf mit. Die vollständige Pipeline ergänzt die Firefox-Abnahme und den Produktions-JAR-Smoke. Lokal zuerst die gepinnten Browser installieren:
|
|
|
|
```sh
|
|
JAVA_HOME=/pfad/zum/jdk25 ./gradlew --no-daemon installBrowsers
|
|
```
|
|
|
|
Der Werkdock-Build nutzt die Browser aus seinem vorbereiteten Image. Fehlende Browser werden im Testlauf nicht automatisch heruntergeladen oder übersprungen.
|
|
|
|
| Bereich | Suite | Details |
|
|
|---|---|---|
|
|
| Arbeitszeit | `WorkCucumberTest` | `docs/implementation/work-gherkin.md` |
|
|
| Habits | `HabitCucumberTest` | `docs/implementation/habit-gherkin.md` |
|
|
| Push | `PushCucumberTest` | `docs/implementation/push-gherkin.md` |
|
|
| Konten | `IdentityCucumberTest` | `docs/implementation/identity-gherkin.md` |
|
|
| Chromium | `BrowserCucumberTest` | `docs/implementation/browser-gherkin.md` |
|
|
| Firefox | `firefoxAcceptance` | `docs/implementation/firefox-acceptance.md` |
|
|
| Produktions-JAR | `productionAcceptance` | `docs/implementation/production-smoke-gherkin.md` |
|
|
|
|
Aufruf beispielsweise: `./gradlew test --tests '*BrowserCucumberTest' -Pproduction=true` mit gesetztem `JAVA_HOME`. Berichte stehen unter `build/reports/cucumber`; noch offene Bindungen in `docs/implementation/acceptance.md`.
|
|
|
|
## Erste Gastvorschau
|
|
|
|
`remote backend deploy-guest-preview --artifact DIRECTORY` ermöglicht ausschließlich den einmaligen Wechsel vom bekannten datenlosen Prototyp. Der Übergang wurde ausgeführt. Bei vorhandener Datenbank verweigert der Befehl weitere Deployments; allgemeine sichere Upgrades erfolgen über `remote backend deploy`. Details: `docs/implementation/guest-preview.md`.
|
|
|
|
Die zentrale [Betriebsanleitung](docs/RUNBOOK.md) beschreibt Konfiguration, Releases, Wiederherstellung, Admin-Recovery und den geplanten Trixie-Wechsel.
|
|
|
|
## Updates und Wiederherstellung
|
|
|
|
```bash
|
|
remote backend deploy --artifact /pfad/zum/geprueften-ci-release
|
|
remote backend recover
|
|
```
|
|
|
|
Mit `remote backend upload --artifact DIRECTORY` lässt sich ein geprüftes Release
|
|
vorab bereitstellen. Es bleibt inaktiv, bis `remote backend deploy --artifact DIRECTORY`
|
|
es mit Sicherung und Bereitschaftsprüfung aktiviert. Ein gewöhnlicher Neustart
|
|
aktiviert den Upload nicht. Details: `docs/implementation/candidate-upload.md`.
|
|
|
|
`remote backend backup [FILE]` erstellt eine konsistente private Sicherung von
|
|
H2-Daten und passendem Programmstand. Ohne Dateinamen landet sie in `backups/`.
|
|
Der Dienst wird dafür kurz unter Wartung gestoppt und anschließend nur dann
|
|
wieder gestartet, wenn er vorher lief. Vorhandene Dateien werden nicht
|
|
überschrieben. Ablauf und Fehlerbehandlung: `docs/implementation/operator-backup.md`.
|
|
|
|
`remote backend restore --backup FILE` spielt diese Sicherung erst nach expliziter
|
|
Bestätigung ein und sichert zuvor den bisherigen Stand. `remote backend restore --recover`
|
|
behandelt einen unterbrochenen Versuch. Vorab lässt sich die Sicherung mit
|
|
`JAVA_HOME=/path/to/jdk25 tools/probe-restore --backup FILE` isoliert prüfen.
|
|
Details: `docs/implementation/operator-restore.md`.
|
|
|
|
Updates verwenden Wartungsseite, Dienststopp, konsistente H2-Dateisicherung und einen dauerhaften Wiederherstellungszustand. Überholte Kandidaten werden abgewiesen. Ein fehlgeschlagener Versuch bleibt in der Pipeline fehlgeschlagen, auch wenn die bisherige Version erfolgreich wiederhergestellt wurde. Einzelheiten: `docs/implementation/deployment.md`. Werkator führt dieses Deployment nach erfolgreichem Build im selben Pipeline-Skript aus.
|
|
|
|
## Push-Schlüssel vorbereiten
|
|
|
|
Mit `remote backend setup-push` werden die VAPID-Schlüssel direkt auf dem Server in der geschützten systemd-Umgebungsdatei erzeugt. Wiederholter Aufruf erhält die vorhandenen Schlüssel. Der Befehl startet keinen Dienst neu und aktiviert keinen Versand. Details: `docs/implementation/web-push-transport.md`.
|