59 lines
3.5 KiB
Markdown
59 lines
3.5 KiB
Markdown
# 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
|
|
|
|
```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.
|
|
# 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`
|
|
|
|
```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.
|