emiTMachine is a multi-user time tracking web app for work sessions, tags, reports, TOTP, passkeys, recovery codes, CSV history, admin workflows, and overtime/time-bank tracking.
 |
 |
 |
 |
 |
 |
Start here if you want the shortest path to a running deployment:
- Open doc/deployment-quickstart.md.
- Pick Caddy, Nginx Proxy Manager with SQLite, or Nginx Proxy Manager with MariaDB.
- Copy the listed
.examplefiles. - Replace the placeholder domain, passwords, and encryption key.
- Start the selected Compose stack.
Use domain.example.com in the docs as a placeholder for your real HTTPS hostname.
| Goal | Use | Command |
|---|---|---|
| Local development | docker-compose.yml |
docker compose up --build |
| Production with included Caddy reverse proxy | docker-compose-reverse.yml |
docker compose -f docker-compose-reverse.yml up -d --build |
| Production with Nginx Proxy Manager and SQLite NPM storage (*) | docker-compose-npm.yml |
docker compose -f docker-compose-npm.yml up -d --build |
| Production with Nginx Proxy Manager and MariaDB NPM storage | docker-compose-npm-advanced.yml |
docker compose -f docker-compose-npm-advanced.yml --env-file docker-compose-npm-advanced.env up -d --build |
Only .example env files are committed. Real env files contain secrets and deployment-specific domains, are ignored by Git, and must not be pushed.
Most deployment stacks need these private files:
cp docker-compose-reverse.postgres.env.example docker-compose-reverse.postgres.env
cp docker-compose-reverse.backend.env.example docker-compose-reverse.backend.env
cp docker-compose-reverse.frontend.env.example docker-compose-reverse.frontend.envIf you use docker-compose-npm-advanced.yml, also run:
cp docker-compose-npm-advanced.env.example docker-compose-npm-advanced.envFor Caddy, also copy docker-compose-reverse.example.yml to docker-compose-reverse.yml and caddy/config/Caddyfile.example to caddy/config/Caddyfile.
docker compose up --buildServices:
- Frontend:
http://localhost:5173 - Backend API:
http://localhost:4000/api - PostgreSQL:
localhost:5432
The database is persisted in the postgres_data Docker volume and initialized from backend/db/init.sql when the volume is first created.
Backups are intentionally handled by the host or infrastructure layer, not by a long-running backup container. Use doc/backups.md for the recommended PostgreSQL backup, retention, off-site copy, cron, and restore procedure.
- Deployment quickstart: shortest deployment path with copy/paste commands.
- Deployment guide: full Compose selection, env files, diagrams, and deployment recipes.
- Local development: default local stack and local commands.
- Backups and restore: production backup policy, cron setup, off-site copy, and restore procedure.
- Operations: logs, validation, and post-deploy checks.
- Caddy reverse proxy guide: detailed Caddy setup.
- Nginx Proxy Manager guide: detailed NPM setup.
- Architecture: container and application architecture.
- Troubleshooting: logs, request ids, and operational checks.
- Root/admin behavior: admin and root user workflows.
- Activity management: activity editing and deletion behavior.
- Overtime/time-bank: overtime and time-bank rules.
- Countdowns: countdown behavior.
- Username/password registration and login.
- Optional TOTP setup with QR code verification.
- Passkey registration/login flow with native WebAuthn ceremonies.
- Recovery codes for account recovery.
- Clock in/out workflow with editable client time confirmation.
- Tags with colors, including default tags.
- Daily, weekly, and monthly hour charts.
- CSV export and restore import.
- Admin/root user management workflows.
- PostgreSQL database initialized from SQL, not backend startup code.
- Docker Compose support for local development and reverse-proxy deployment.
This repository includes workspace agents for planning and implementing the project from todo.txt.
- Main coordination file:
AGENTS.md - Per-agent definitions:
.github/agents/ - Technical workflow notes: doc/agentic-ai.md