mi/werkator
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
c77de1c72595b0ec6be326ff8b622629c63ca309
werkator/docs/plan
T
History
mhoennigandClaude c77de1c725 Record the webspace's bwrap and kernel versions, and the glibc consequence 
bubblewrap 0.8.0 covers every option the sandbox design uses; only overlayfs is
missing, which the design does not need. The kernel version, however, points at
Debian 12 and thus a glibc older than the dev machine's, which would break the
jlink runtime bundle on that host -- noted as a check to run before deploying.

Co-Authored-By: Claude <noreply@anthropic.com>
2026-08-11 10:21:00 +02:00
..
00-legacy-analysis.md
added ADR 0005 and step 13: reintroduce managed nginx+certbot as an opt-in feature for hosts without a reverse proxy (e.g. Hostsharing); partially supersedes ADR 0004; updated plans, documentation, and migration guides
2026-07-07 14:40:11 +02:00
01-build-state-domain.md
implemented 01-build-state-domain: add execution notes and jackson-datatype-jsr310 dependency
2026-07-07 06:53:04 +02:00
02-git-gateway.md
implemented 02-git-gateway.md: added Git access layer with credentials bridge, duration parser, and extensive tests
2026-07-07 07:10:38 +02:00
03-gitea-client.md
implemented 03-gitea-client.md: added Gitea API client for commit statuses, status mapping, and extensive tests
2026-07-07 07:34:18 +02:00
04-build-executor.md
implemented 04-build-executor.md incl. concurrency amendment: async builds in per-branch worktrees, builds.maxConcurrent, cancellation, live logs; fix .gitignore build/ rule that silently excluded the de.hoennig.gittally.build package (also recovers the step-01 domain files)
2026-07-07 08:43:28 +02:00
05-artifact-store.md
implemented 05-artifact-store.md: filesystem artifact store with legacy-compatible naming, atomic persist from concurrent builds, retention pruning, and artifacts.rootDir config
2026-07-07 10:08:40 +02:00
06-watcher.md
implemented 06-watcher.md: non-blocking poll cycle enqueueing changed/new/auto-build branches via the async executor, startup recovery, retention/worktree pruning, JSON auto-build slot state, watcher.pollInterval config, and watcher health state
2026-07-07 10:28:28 +02:00
07-server-mode.md
implemented 08-web-ui.md: added Thymeleaf-based web UI: templates for builds, artifacts, current builds, and fragments; static assets for favicon, CSS, and JavaScript
2026-07-07 12:23:12 +02:00
08-web-ui.md
Stable per-branch report URLs and a reachable live view (v0.9.8)
2026-08-10 21:27:53 +02:00
09-system-metrics.md
implemented 09-system-metrics.md: added system metrics: introduced system monitoring with a metrics collector, REST API endpoint, Thymeleaf UI rendering, and lifecycle management
2026-07-07 12:55:11 +02:00
10-cli-commands.md
implemented 10-cli-commands.md: added CLI commands for branch name resolution, one-shot builds, failed build retries, and build status reports; includes tests for functionality and edge cases
2026-07-07 13:19:29 +02:00
11-docker-build-runtime.md
implemented 11-docker-build-runtime.md: added optional Docker-based build execution with configuration, per-branch runtime selection, image rebuild on input changes, Gradle cache volume, and ownership repair; updated docs and configuration
2026-07-07 13:49:08 +02:00
12-deployment.md
implemented 12-deployment.md: added systemd service generation (init --systemd) and migration guide from legacy script; introduced JSON-file persistence, server-rendered UI with polling, and reverse-proxy-based deployment; updated documentation
2026-07-07 14:18:41 +02:00
13-nginx-tls.md
added opt-in managed nginx/TLS container (ADR 0005, plan step 13): server.nginx.* config serves GitTally over HTTPS on hosts without a reverse proxy — two-phase startup (ACME webroot via certbot container, then full HTTPS config), daily certificate renewal with nginx reload, labelled container removed on shutdown; all failures are non-fatal, the plain HTTP server keeps running
2026-07-08 21:51:33 +02:00
14-build-phase-timing-and-overhead.md
Add build-phase timing and overhead optimization plan to docs
2026-08-10 13:32:17 +02:00
15-runtime-bundle-distribution.md
Record the v0.9.10 deployment to vm4006
2026-08-11 08:08:15 +02:00
16-git-in-docker-builds.md
Fix Docker builds under rootless daemons and expose git metadata to build containers
2026-08-10 15:34:39 +02:00
17-bwrap-build-runtime.md
Record the webspace's bwrap and kernel versions, and the glibc consequence
2026-08-11 10:21:00 +02:00
README.md
Plan step 17: web access on a Managed Webspace, alongside the sandbox
2026-08-11 08:37:58 +02:00

README.md

GitTally Rewrite Plan

This directory contains the step-by-step plan for rewriting legacy/gitTally (bash) as the Kotlin/Spring application in this repository. Each step file is self-contained and sized for one focused Claude Code session.

How to Execute a Step

Start a fresh Claude Code session and prompt, for example: "Execute docs/plan/01-build-state-domain.md". The executing session should:

  1. Read this file, 00-legacy-analysis.md, and the step file.
  2. Read the referenced parts of legacy/gitTally only if the step file says so.
  3. Implement with tests, following CLAUDE.md conventions.
  4. Run ./gradlew ktlintFormat and then ./gradlew build until green.
  5. Update the step's checkbox below and note deviations inside the step file.

Guiding Principles

  • The legacy script defines intended behavior, but it is buggy — treat it as a reference, not a spec.
  • Fix the two known legacy defects by design, not by patching:
    • Build status must be observable while a build runs (event-driven status transitions, async build execution).
    • The web UI must never get stuck loading (JSON status endpoints with explicit error states instead of regex-rewritten HTML).
  • Do not port orphaned or half-implemented legacy config options (see 00-legacy-analysis.md).
  • Every step leaves the build green and the application runnable.
  • Config keys added by a step must be updated in three places: GitTallyConfig, the InitCommand templates, and docs/configuration.md.

Proposed Architecture Decisions

These are proposals baked into the steps. Revisit them in an ADR if a step uncovers problems.

  • Build results are persisted as a JSON file under .git/gittally/, behind a BuildResultRepository interface (no database, but replaceable).
  • Builds run concurrently up to builds.maxConcurrent (default 1), but never more than one build per branch at a time. Each branch builds in its own reusable git worktree under .git/gittally/worktrees/, checked out detached at the requested commit — never in the primary checkout. A later step must decide (possibly per config) whether a new commit on a branch cancels that branch's running build or waits for it; for now new builds queue behind the running one.
  • Artifacts stay on the filesystem, served by the Spring server.
  • The web UI is server-rendered HTML plus small JavaScript polling JSON endpoints (no SPA framework).
  • The watcher is a Spring-managed scheduled component, decoupled from the build executor via the result repository and events.
  • nginx/Let's Encrypt container management is NOT ported; deployment behind an existing reverse proxy is documented instead. Revised after step 12 (ADR 0005): an opt-in managed nginx/TLS container is required for Hostsharing container hosts — see step 13.

Steps

Foundation:

  • 01-build-state-domain.md — build result domain model and persistent repository
  • 02-git-gateway.md — full git access layer (fetch, branches, commits, checkout)
  • 03-gitea-client.md — Gitea API client for commit statuses

Core engine:

  • 04-build-executor.md — async build execution with logs, cancellation, status transitions
  • 05-artifact-store.md — artifact persistence, naming, retention
  • 06-watcher.md — branch watching, scheduling, auto-builds

Server and UI:

  • 07-server-mode.md — server subcommand, REST/JSON endpoints, artifact serving
  • 08-web-ui.md — HTML views with robust live updates
  • 09-system-metrics.md — system resource monitoring page

Completion:

  • 10-cli-commands.md — CLI build/status commands
  • 11-docker-build-runtime.md — optional Docker build execution
  • 12-deployment.md — systemd service, migration from legacy, docs

Added after the initial plan (ADR 0005):

  • 13-nginx-tls.md — opt-in managed nginx/TLS container for hosts without a reverse proxy

Added after the 2026-08-10 overhead measurements on vm2176:

  • 14-build-phase-timing-and-overhead.md — per-build phase timing, overhead budget warning, ownership/metrics fixes — deferred until after step 15; revisit relevance on vm4006

Added for the vm2176 → vm4006 migration (2026-08-10):

  • 15-runtime-bundle-distribution.md — self-contained runtime bundle (jlink JRE + jar) for hosts without a Java runtime
  • 16-git-in-docker-builds.md — read-only git metadata inside Docker build containers, with .git/gittally/ masked

Added for running GitTally on Hostsharing Managed Webspaces (2026-08-10):

  • 17-bwrap-build-runtime.md — GitTally on a Managed Webspace: bubblewrap user-namespace build sandbox with a prepared rootfs (precondition check first — see the step file), plus web access under a domain via the platform's Apache proxy and Let's Encrypt

Steps 01–03 are independent of each other. Steps 04–06 depend on 01–03. Steps 07–09 depend on 04–06. Steps 11 and 12 are optional/deferrable; 10 only needs 04–06. Step 13 depends on 07, 11, and 12. Step 15 depends on 12 and 13 and revises the containerized-runtime sketch in docs/bootstrapping.md (ADR 0006 is written as part of the step; GraalVM native image was evaluated and rejected there). Step 17 depends on 11, 15, and 16, and starts with a hard precondition check on the target webspace (ADR 0007 is written as part of the step).

Reference in New Issue View Git Blame Copy Permalink