Add self-hosted combined timesheet server

2026-09-14 13:14:47 +02:00
commit 25eb7f50e6
17 changed files with 584 additions and 0 deletions
@@ -0,0 +1,56 @@
+# Time Track Server
+
+A self-hosted, single-user combined timesheet server for `time_track` manual intervals and `zed_time_tracker` activity. It is designed for private access over Tailscale and groups days in `Europe/Vienna` by default.
+
+## What is implemented
+
+- Docker Compose deployment: FastAPI app and private PostgreSQL database.
+- Password-protected single-user web UI for browsing combined entries, filtering dates, adding manual time, and accepting/rejecting Zed suggestions.
+- Token-authenticated, idempotent ingestion endpoints for both local trackers.
+- Explicit `time_track` intervals are accepted time; Zed heartbeat blocks are **suggested only**, never included in accepted totals until approved.
+- PDF call-log upload with durable source-file storage and text extraction. A provider-specific parser is intentionally deferred until a redacted mobile-provider sample statement establishes the layout.
+
+## Deploy
+
+```sh
+cp .env.example .env
+# Generate three distinct high-entropy values for POSTGRES_PASSWORD, ADMIN_PASSWORD,
+# SYNC_API_TOKEN, and SESSION_SECRET. Keep .env private.
+docker compose up --build -d
+```
+
+Set `BIND_IP=100.103.83.12` to listen only on the Tailscale address. Browse to `http://100.103.83.12:3008` and log in using `ADMIN_PASSWORD`.
+
+`postgres` is not published to the host. Docker volumes `postgres_data` and `call_imports` contain the state that must be backed up.
+
+## Connect `time_track`
+
+```sh
+export TIME_TRACK_SERVER_URL=http://100.103.83.12:3008
+export TIME_TRACK_SERVER_TOKEN='the SYNC_API_TOKEN value'
+export TIME_TRACK_DEVICE_ID='desktop-1'
+python3 time_track/time_track.py sync
+```
+
+## Connect the Zed tracker
+
+```sh
+export ZED_HOURS_SERVER_URL=http://100.103.83.12:3008
+export ZED_HOURS_SERVER_TOKEN='the SYNC_API_TOKEN value'
+export ZED_HOURS_DEVICE_ID='desktop-1'
+python3 zed_time_tracker/sync.py --project-root /path/to/project --project-slug customer-project
+```
+
+The Zed client sends a project slug rather than local absolute project paths. Repeated requests are safe: source IDs and server uniqueness rules prevent duplicate events.
+
+## Call PDFs and Ollama
+
+The initial upload path accepts mobile-provider PDF call-detail records and safely records extracted text, including a clear `needs_ocr` status for image-only PDFs. It deliberately does **not** generate timesheet durations until a parser is implemented and tested against redacted sample PDFs from the provider.
+
+The Compose configuration reserves the local Ollama endpoint `http://100.103.83.12:11345` and recommends `qwen3:8b` for optional, review-only task/project suggestions. No Ollama requests are made in this initial release because deterministic PDF parsing and phone matching must come first.
+
+## Operational notes
+
+- Use an application password even on Tailscale; the network is not the sole access-control layer.
+- Back up the Postgres volume before upgrades. A simple host backup is `docker compose exec -T postgres pg_dump -U time_track time_track > backup.sql`.
+- HTTPS is not configured: Tailscale encrypts node-to-node traffic. If browser HTTPS is required, add a Tailscale-aware reverse proxy or Tailscale Serve in front of port 3008.