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: day-grouped timesheets with per-day totals, "Accept day" for suggested time, expandable day views showing every entry (accept/reject individually), and the synced Zed git-commit history per day.
Token-authenticated, idempotent ingestion endpoints for both local trackers.
Monthly report export as Markdown or CSV: GET /export/monthly?month=YYYY-MM&format=md|csv (also in the UI). Full-calendar-month day summaries, totals, per-day detail with accepted and suggested time kept separate, and the month's git commits. Rejected entries are excluded.
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

cp .env.example .env
# Generate three distinct high-entropy values for POSTGRES_PASSWORD, ADMIN_PASSWORD,
# SYNC_API_TOKEN, and SESSION_SECRET. Keep .env private.
# Values containing special characters (for example @ or :) are safe.
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`

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

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.

3.5 KiB Raw Blame History