TimeTracker

Self-hosted time tracking, invoicing and Peppol e-invoicing for freelancers and teams — with no per-seat fees.

Live demo · Website · Docs · Changelog

Quick start (60 seconds)

No git clone, no certificate warning — plain HTTP on port 8080 with bundled PostgreSQL:

curl -fsSLO https://raw.githubusercontent.com/drytrix/TimeTracker/main/docker-compose.nas.yml
echo "SECRET_KEY=$(openssl rand -hex 32)" > .env
docker compose -f docker-compose.nas.yml up -d
# open http://localhost:8080 — first login creates the admin

Latest release: v5.18.2 — see CHANGELOG.md.

More install paths (HTTPS production, NAS UI paste, cloud): Install options.

Why TimeTracker?

Peppol & EN 16931 e-invoicing — Send invoices yourself via the bundled Peppol Bridge; embed Factur-X / ZUGFeRD XML in PDFs. No paid SaaS middleman for e-invoicing.
Self-hosted — Your timers, clients, and invoices stay on your server (Docker, NAS, VPS, or Raspberry Pi).
GPL-3.0 open source — Free to use, modify, and run commercially; features are never locked behind a paywall.
No per-user pricing — Unlimited users and projects; optional one-time supporter key only hides donate prompts.

Feature	TimeTracker	Traditional Time Trackers
Self-Hosted	✅ Complete data control	❌ Cloud-only, subscription fees
Open Source	✅ Free to use & modify	❌ Proprietary, locked features
Persistent Timers	✅ Runs server-side	❌ Browser-dependent
Docker Ready	✅ Deploy anywhere	⚠️ Complex setup
Invoicing Built-in	✅ Track to bill workflow	❌ Requires integration
No User Limits	✅ Unlimited users	❌ Per-user pricing

What is TimeTracker?

TimeTracker is a self-hosted, web-based time tracking application designed for freelancers, teams, and businesses who need professional time management with complete control over their data.

Perfect for:

Freelancers tracking billable hours across multiple clients
Small Teams managing projects and tracking productivity
Agencies needing detailed reporting and client billing
Privacy-focused organizations wanting self-hosted solutions

UI layout and navigation conventions: UI Guidelines.

✨ Features

TimeTracker includes 130+ features across 13 major categories. See the Complete Features Documentation for a comprehensive overview.

📖 Quick Links:

📋 Complete Features List — All features in detail
⏱️ Time Tracking — Timer and time entry features
📊 Project Management — Projects, tasks, and organization
🧾 Invoicing — Invoice generation and billing
💰 Financial Management — Expenses, payments, and tracking
📈 Reporting & Analytics — Reports and insights

⏱️ Smart Time Tracking

One-Click Timers — Start tracking with a single click
Persistent Timers — Timers keep running even after browser closes
Idle Detection — Automatic pause after configurable idle time
Manual Entry — Add historical time entries with notes and tags
Bulk Time Entry — Create multiple entries for consecutive days with weekend skipping (Guide)
Time Entry Templates — Save and reuse common time entries for faster logging (Guide)
Calendar View — Visual calendar interface for viewing and managing time entries (Guide)
Focus Sessions — Pomodoro-style focus session tracking
Recurring Time Blocks — Weekly recurring time block templates
Time Rounding — Configurable rounding intervals (Guide)
Real-time Updates — See live timer updates across all devices via WebSocket

📊 Project & Task Management

Unlimited Projects & Tasks — Organize work your way
Client Management — Store client details, contacts, and billing rates (Guide)
Task Board — Visual task management with priorities and assignments
Kanban Board — Drag-and-drop task management with customizable columns
Task Management — Complete task tracking system (Guide)
Issue & Bug Tracking — Full lifecycle issue and bug tracking system
Status Tracking — Monitor progress from to-do to completion
Budget Tracking — Monitor project budgets with alerts and forecasting (Guide)
Project Costs — Track direct project expenses
Task Comments — Collaborate with threaded comments on tasks
Markdown Support — Rich text formatting in project and task descriptions
Project Favorites — Quick access to frequently used projects

💼 CRM & Sales Management 🆕

Multiple Contacts per Client — Manage unlimited contacts with roles and designations
Sales Pipeline — Visual Kanban-style pipeline for tracking deals and opportunities
Deal Management — Track deal value, probability, stages, and expected close dates
Lead Management — Capture, score, and convert leads into clients or deals
Communication History — Track all emails, calls, meetings, and notes with contacts
Deal Activities — Complete activity tracking for sales processes
Lead Activities — Track all interactions and activities for leads
Lead Scoring — Automated lead scoring (0-100) for prioritization
Lead Conversion — Convert leads to clients or deals with one click

🧾 Professional Invoicing

Generate from Time — Convert tracked hours to invoices automatically
Invoice System — Complete invoicing solution (Guide)
Custom Line Items — Add manual items for expenses or services
Tax Calculation — Automatic tax calculations with configurable rates
PDF Export — Professional PDF invoice generation with customizable layouts
PDF Invoice Layout — Customize invoice and quote PDF layouts via Admin > PDF Layout; Items table includes time entries, extra goods, and expenses (Guide, Extra Goods in PDF)
Status Tracking — Track draft, sent, paid, and overdue invoices
Company Branding — Add logos and custom company information
Expense Integration — Include tracked expenses in invoices
Recurring Invoices — Automate recurring billing
Multi-Currency — Support for multiple currencies with conversion
Invoice Email — Send invoices directly to clients
Peppol & ZugFerd e-Invoicing (EN 16931) — Send via Peppol (generic or native); embed EN 16931 XML in PDFs (ZugFerd/Factur-X); optional PDF/A-3 and veraPDF (Setup Guide)

💰 Financial Management

Expense Tracking — Track business expenses with receipts and categories (Guide)
Payment Tracking — Monitor invoice payments and payment methods (Guide)
Reimbursement Management — Handle expense approvals and reimbursements
Billable Expenses — Mark expenses as billable and add to invoices
Payment Gateway Integration — Track gateway transactions and fees
Mileage Tracking — Track business mileage with rate calculation
Per Diem Tracking — Manage per diem expenses and rates
Multi-Currency — Support for multiple currencies with conversion

📈 Analytics & Reporting

Visual Dashboards — Charts and graphs for quick insights; dashboard includes time-by-project chart (last 7 days) and weekly goal progress bar
Summary Report — Today/week/month hours with time-by-project and daily trend (14 days) charts; export summary as PDF
Detailed Reports — Time breakdown by project, user, or date range
CSV Export — Export data for external analysis
Billable vs Non-billable — Separate tracking for accurate billing
Custom Date Ranges — Flexible reporting periods
Saved Filters — Save frequently used report filters for quick access
User Analytics — Individual performance metrics and productivity insights
Budget Alerts — Automatic alerts when budget thresholds are exceeded (Guide)
Budget Forecasting — Predict project completion dates based on burn rates
Weekly Time Goals — Set and track weekly hour targets (Guide)
Overtime Tracking — Monitor and report overtime hours

🔐 Multi-User & Security

Role-Based Access Control — Granular permissions system with custom roles (Guide)
User Management — Add team members and manage access
Self-Hosted — Complete control over your data
Flexible Authentication — Username-only, OIDC/SSO (Azure AD, Authelia, etc.) (Setup Guide)
Session Management — Secure cookies and session handling
Profile Pictures — Users can upload profile pictures
API Tokens — Generate tokens for API access and integrations (API Docs)
Audit Logs — Track all system activity and user actions

⌨️ Productivity Features

Command Palette — Keyboard-driven navigation with shortcuts (Ctrl+K / Cmd+K) (Guide)
Keyboard Shortcuts — 50+ shortcuts for lightning-fast navigation and actions
Quick Search — Enhanced instant search with autocomplete and categorized results (Ctrl+K)
Floating quick hub — Bottom-right dock: unified Actions menu (timer, log time, new task/project/client, reports), optional team chat toggle with a fixed viewport panel, and AI Helper; see UI guidelines
Enhanced Data Tables — Sortable, filterable, inline-editable tables with bulk operations
Email Notifications — Configurable email alerts for tasks, invoices, and more
Toast Notifications — Beautiful in-app notifications; post-timer toast shows "Logged Xh on Project" with link to time entries
Weekly Summaries — Optional weekly time tracking summaries via email (enable in Settings)
Remind to Log — Optional end-of-day email reminder to log time (Settings → Remind me to log time at end of day; set time in your timezone)
Activity Feed — Track recent activity across the system
Saved Filters — Save frequently used report filters for quick access
Recently Viewed — Quick access to recently viewed items
Favorites System — Mark frequently used projects, clients, and tasks as favorites

🛠️ Technical Excellence

Docker Ready — Deploy in minutes with Docker Compose
Database Flexibility — PostgreSQL for production, SQLite for testing
Responsive Design — Mobile-first design works perfectly on desktop, tablet, and mobile
Native Mobile & Desktop Apps — Flutter mobile app (iOS/Android) and Electron desktop app with time tracking, offline support, and API integration (Build Guide, Docs)
Real-time Sync — WebSocket support for live updates across devices
Automatic Backups — Scheduled database backups (configurable)
Progressive Web App (PWA) — Install as mobile app with offline support and background sync
Monitoring Stack — Built-in Prometheus, Grafana, Loki for observability
Internationalization — Multiple language support (i18n) with translation system
REST API — Comprehensive REST API with token authentication and scoping
HTTPS Support — Automatic HTTPS setup with self-signed or trusted certificates
Modern Architecture — Service layer pattern, repository pattern, schema validation
Performance Optimized — Query optimization, eager loading, reduced N+1 queries
Accessibility — WCAG 2.1 AA compliant with full keyboard navigation and screen reader support

📸 Screenshots

🔐 Simple Login & User Management

Simple username-based authentication and customizable user profiles with avatar support

📁 Projects & Tasks — Stay Organized

Manage multiple projects and break them down into actionable tasks

📋 Kanban Board — Visual Task Management

Drag-and-drop task management with customizable columns and visual workflow

⏱️ Time Tracking — Flexible & Powerful

Manual time entry and reusable templates for faster logging

🧾 Invoicing & Clients — Professional Billing

Generate invoices from tracked time and manage client relationships

📊 Reports & Analytics — Data-Driven Insights

Comprehensive reporting and user analytics for informed decisions

🛠️ Admin Dashboard — Complete Control

Manage users, configure settings, and monitor system health

🎯 Easy Creation — Streamlined Workflows

Simple, intuitive forms for creating projects, tasks, and clients

Install options

Method	Best for	Get started
One-command (above)	Homelab, quick try	`docker-compose.nas.yml` + `SECRET_KEY`
Docker image	Servers, VPS	`docker pull ghcr.io/drytrix/timetracker:latest` or Docker Hub
NAS compose	QNAP, Synology, Portainer	Paste `docker-compose.nas.yml` — NAS guide
GitHub Release	Compose files + desktop/mobile	Releases
Cloud (Render)	Managed hosting
Railyard	Managed hosting

Full list of install paths: Distribution Guide (Portainer templates, Unraid, Railway, Fly.io, Coolify, Docker Hub)

Docker Hub namespace: images are published at drytrix/timetracker (formerly driesp/timetracker).

For a full step-by-step guide, see INSTALLATION.md.

Prerequisites

Docker (20.10+) and Docker Compose (2.0+)
2GB+ RAM available for Docker containers
Port 8080 (HTTP) or 80/443 (HTTPS production)

New to Docker? See Docker Installation Guide for your platform.

Option 1: NAS / one-file compose (recommended for first try)

Same stack as Quick start. Paste docker-compose.nas.yml into Container Station, Synology Container Manager, or Portainer; set SECRET_KEY; open http://<host>:8080.

Works on QNAP, Synology, Unraid/Portainer, and other Docker-capable NAS devices (amd64 and arm64).

Full guide: NAS Deployment Guide

Option 2: Production with HTTPS

Clone the repo and use the root compose file (nginx + self-signed cert):

git clone https://github.com/drytrix/TimeTracker.git
cd TimeTracker
cp env.example .env
# Set a strong SECRET_KEY, TZ, and CURRENCY in .env
docker compose up -d
# Access at https://localhost — accept the self-signed certificate warning

First login creates the admin account. For setup problems, see INSTALLATION.md.

Default install (no bundled AI): the main docker-compose.yml starts the app and PostgreSQL only. Optional Ollama: see AI Helper.

Complete setup guide: docs/admin/configuration/DOCKER_COMPOSE_SETUP.md · Uninstall: UNINSTALL.md

Troubleshooting: Docker Startup · CSRF · Database

Option 3: Docker with plain HTTP (development)

git clone https://github.com/drytrix/TimeTracker.git
cd TimeTracker
docker compose -f docker-compose.example.yml up -d
# Access at http://localhost:8080

Option 4: Quick test with SQLite

git clone https://github.com/drytrix/TimeTracker.git
cd TimeTracker
docker compose -f docker/docker-compose.local-test.yml up --build
# Access at http://localhost:8080

No PostgreSQL or .env required. SQLite is not recommended for production.

Need help? Getting Started Guide

💻 System Requirements

Minimum Requirements

For Small Teams (1-5 users):

CPU: 1 core (2.0 GHz+)
RAM: 2 GB
Storage: 10 GB free space
OS: Linux, macOS, or Windows (with Docker)
Docker: 20.10+ and Docker Compose 2.0+

For Production (5+ users):

CPU: 2+ cores (2.4 GHz+)
RAM: 4 GB
Storage: 20 GB free space (SSD recommended)
OS: Linux (Ubuntu 20.04+, Debian 11+, or similar)
Docker: 20.10+ and Docker Compose 2.0+
PostgreSQL: 13+ (included in Docker Compose)

Recommended Requirements

For Optimal Performance:

CPU: 4+ cores (3.0 GHz+)
RAM: 8 GB
Storage: 50+ GB SSD
Network: Stable internet connection (for updates and optional telemetry)
Backup: Automated backup solution for database

Platform Support

✅ Linux (Ubuntu, Debian, CentOS, RHEL, etc.)
✅ macOS (Intel and Apple Silicon)
✅ Windows (Windows 10/11 with WSL2 or Docker Desktop)
✅ Raspberry Pi (Raspberry Pi 4 with 2GB+ RAM)
✅ Cloud Platforms (AWS, Azure, GCP, DigitalOcean, etc.)

Database Options

PostgreSQL (Recommended for production)
- Version 13+ required
- Included in Docker Compose setup
- Supports all features including full-text search
SQLite (Development/Testing only)
- No setup required
- Suitable for single-user or testing
- Limited concurrent write performance

Browser Support

TimeTracker works with all modern browsers:

✅ Chrome/Edge 90+
✅ Firefox 88+
✅ Safari 14+
✅ Opera 76+

📖 For detailed requirements, see Requirements Documentation

💡 Use Cases

For Freelancers

Track time across multiple client projects, generate professional invoices, and understand where your time goes. TimeTracker helps you bill accurately and identify your most profitable clients.

For Teams

Assign tasks, track team productivity, and generate reports for stakeholders. See who's working on what, identify bottlenecks, and optimize team performance.

For Agencies

Manage multiple clients and projects simultaneously. Track billable hours, generate client invoices, and analyze project profitability — all in one place.

For Personal Projects

Even if you're not billing anyone, understanding where your time goes is valuable. Track personal projects, hobbies, and learning activities to optimize your time.

📚 Documentation

Comprehensive documentation is available in the docs/ directory. See the Documentation Index for a complete overview.

📖 Documentation by Use Case

For New Users:

Getting Started Guide — Complete beginner's tutorial (⭐ Start here!)
Installation Guide — Step-by-step installation (Docker, SQLite test)
Docker Public Setup — Production deployment
Quick Start Guide — Get up and running quickly

For Administrators:

Docker Compose Setup — Production deployment guide
Configuration Guide — All configuration options
Uninstall / remove data — Tear down Docker, volumes, and optional AI (Ollama); AI helper only
OIDC/SSO Setup — Enterprise authentication
Email Configuration — Email setup
Version Management — Updates and releases

For Developers:

Contributing — How to contribute (quick link)
Contributing Guidelines (full) — Setup, standards, PR process
Development Guide — Run locally, test, release process
Architecture — System overview and design
Project Structure — Codebase layout
API Documentation — API quick reference · Full REST API
Database Migrations — Schema management
CI/CD Documentation — Build and deployment

For Troubleshooting:

Docker Startup Issues — Common startup problems
CSRF Token Issues — Fix CSRF errors
Database Connection — Database issues
Solution Guide — General problem solving

🎯 Feature Documentation

Core Features:

📋 Complete Features Overview — All 130+ features (⭐ Complete reference!)
Time Tracking — Timer and entry features
Task Management — Task tracking system
Client Management — Client relationships
Invoice System — Invoice generation

Advanced Features:

Calendar & Bulk Entry — Calendar view and bulk operations
Bulk Time Entry — Create multiple entries
Time Entry Templates — Reusable templates
Expense Tracking — Business expenses
Payment Tracking — Invoice payments
Budget Alerts & Forecasting — Budget monitoring
Weekly Time Goals — Weekly targets

Productivity:

Command Palette — Keyboard shortcuts
Role-Based Permissions — Access control
Multiple instances (independent companies) — One deployment per company

Integrations & Apps:

Mobile & Desktop Apps — Flutter mobile and Electron desktop apps
Build Guide (Mobile & Desktop) — Build scripts for Android, iOS, Windows, macOS, Linux
Peppol & ZugFerd e-Invoicing — Peppol sending and ZugFerd/Factur-X PDF embedding (EN 16931)
API Documentation — REST API reference
API Token Scopes — Token permissions

🔧 Technical Documentation

Project Structure — Codebase architecture
Database Migrations — Schema management
Version Management — Release process
CSRF Configuration — Security setup
CI/CD Setup — Continuous integration

🔒 Security & Configuration

HTTPS Setup (Auto) — Automatic HTTPS
HTTPS Setup (mkcert) — Manual HTTPS
CSRF Troubleshooting — CSRF issues
CSRF IP Access Fix — IP access issues
OIDC/SSO Setup — Enterprise auth

🤝 Contributing

Contributing Guidelines — How to contribute
Code of Conduct — Community standards
Development Setup — Local development

📋 Reference

📋 Changelog — Complete release history (⭐ See what's new!)
Requirements — System requirements
Documentation Index — Complete documentation overview

🐳 Deployment

Local Development

# Start with HTTPS (recommended)
docker-compose up -d

# Or use plain HTTP for development
docker-compose -f docker-compose.example.yml up -d

Production Deployment

Option 1: Build from Source

# Clone the repository
git clone https://github.com/drytrix/TimeTracker.git
cd TimeTracker

# Configure your .env file
cp env.example .env
# Edit .env with production settings:
# - Set a strong SECRET_KEY: python -c "import secrets; print(secrets.token_hex(32))"
# - Configure TZ (timezone) and CURRENCY
# - Set PostgreSQL credentials (POSTGRES_PASSWORD, etc.)

# Start the application
docker-compose up -d

Option 2: Use Pre-built Images

# Use the remote compose file with published images
docker-compose -f docker/docker-compose.remote.yml up -d

⚠️ Security Note: Always set a unique SECRET_KEY in production! See CSRF Configuration for details.

AI Helper (Ollama or hosted)

TimeTracker includes an optional server-side AI helper for the web app and API clients. New installs default to AI off (AI_ENABLED=false in env.example and in the root docker-compose.yml app service) so time tracking works without downloading a large language model.

Enable (any setup): set AI_ENABLED=true (environment or Admin → System Settings → AI Helper).
Ollama: set AI_PROVIDER=ollama, AI_MODEL=..., and AI_BASE_URL to http://ollama:11434 when Ollama runs in Docker on the same Compose network, or http://127.0.0.1:11434 when Ollama runs on the host.
Hosted OpenAI-compatible: set AI_PROVIDER=openai_compatible and AI_API_KEY=...

The AI helper is exposed as:

Session web UI JSON: POST /api/ai/chat (same-origin, login required)
REST API v1: POST /api/v1/ai/chat (API token required, scopes read:ai/write:ai)

Time entry suggestions (when AI_ENABLED=true):

GET /api/ai/suggest — deterministic suggestions from recent patterns and active tasks; optional ?q= filters by notes/project name; ?rich=true merges LLM suggestions when configured. AI failures return deterministic results only.
Start Timer modal: horizontal suggestion chips above the project field (refresh for LLM-enhanced suggestions).
Log Time form: “✦ Autofill” popover and ghost-text autocomplete on the notes field (app/static/js/ai_autocomplete.js).

All suggestion UI is hidden when AI is disabled (ai_enabled in template context).

Bundled Ollama service (Docker Compose, opt-in)

The root docker-compose.yml defines a CPU-only ollama service and a one-shot ollama-init sidecar that pulls AI_MODEL (default llama3.1, ~4.7 GB) into the ollama_data volume. These services use the Compose ai profile so they do not start by default.

Enable bundled Ollama:

In .env, set AI_ENABLED=true, AI_PROVIDER=ollama, AI_BASE_URL=http://ollama:11434, and your desired AI_MODEL.
Start the stack with the profile:
```
docker compose --profile ai up -d
```

The app reaches Ollama at http://ollama:11434 over the Docker network — no host ports need to be opened.
Change the model by setting AI_MODEL in .env (e.g. AI_MODEL=qwen2.5:3b for lighter hardware) and re-running docker compose --profile ai up -d; the init sidecar will pull the new model when needed.
Pulled models are cached in the ollama_data named volume, so subsequent boots are faster.
Verify in the UI: Admin → System Settings → AI helper, then click Test connection.
To pull additional models manually: docker compose exec ollama ollama pull <model> (with the ai profile active).
Hosted provider only (no Ollama containers): set AI_PROVIDER=openai_compatible, AI_BASE_URL, and AI_API_KEY in .env; keep docker compose up -d without the ai profile.

Disable or remove AI (turn off LLM calls, stop Ollama, revoke tokens, delete ollama_data safely): UNINSTALL.md.

Encrypting stored secrets (recommended)

To store sensitive settings (OAuth secrets, mail password, AI API key, Peppol token, 2FA secret) encrypted at rest, set:

SETTINGS_ENCRYPTION_KEY (Fernet key), or
SETTINGS_ENCRYPTION_KEY_FILE (file path with the key on the first line)

Raspberry Pi Deployment

TimeTracker runs perfectly on Raspberry Pi 4 (2GB+ RAM):

# Same Docker commands work on ARM architecture
docker-compose up -d

HTTPS Configuration

Automatic HTTPS (Easiest)

# Uses self-signed certificates (generated automatically)
docker-compose up -d
# Access at https://localhost (accept browser warning)

Manual HTTPS with mkcert (No Browser Warnings)

# Use mkcert for locally-trusted certificates
docker-compose -f docker/docker-compose.https-mkcert.yml up -d

📖 See HTTPS Setup Guide for detailed instructions. HTTPS helper scripts live in scripts/ (e.g. from project root: bash scripts/setup-https-mkcert.sh, bash scripts/start-https.sh).

Monitoring & Analytics

# Alternate compose files (local-test, remote, analytics, https) are in docker/; use -f docker/docker-compose.xxx.yml

# Deploy with full monitoring stack (Prometheus, Grafana, Loki)
docker-compose -f docker-compose.yml -f docker/docker-compose.analytics.yml --profile monitoring up -d
# Grafana: http://localhost:3000
# Prometheus: http://localhost:9090

📖 See Deployment Guide for detailed instructions
📖 See Docker Compose Setup for configuration options

🔧 Configuration

TimeTracker is highly configurable through environment variables. For a comprehensive list and recommended values, see:

Common settings:

# Timezone and locale
TZ=America/New_York
CURRENCY=USD

# Timer behavior
SINGLE_ACTIVE_TIMER=true
IDLE_TIMEOUT_MINUTES=30
ROUNDING_MINUTES=1

# User management
# Note: Only the first username in ADMIN_USERNAMES is auto-created during initialization.
# Additional usernames must self-register (if ALLOW_SELF_REGISTER=true) or be created manually.
ADMIN_USERNAMES=admin,manager
ALLOW_SELF_REGISTER=false

# Security (production)
SECRET_KEY=your-secure-random-key
SESSION_COOKIE_SECURE=true

📊 Analytics & Telemetry

TimeTracker includes optional analytics and monitoring features to help improve the application and understand how it's being used. All analytics features are:

✅ Disabled by default — You must explicitly opt-in
✅ Privacy-first — No personally identifiable information (PII) is collected
✅ Self-hostable — Run your own analytics infrastructure
✅ Transparent — All data collection is documented

What We Collect (When Enabled)

1. Structured Logs (Always On, Local Only)

Request logs and error messages stored locally in logs/app.jsonl
Used for troubleshooting and debugging
Never leaves your server

2. Prometheus Metrics (Always On, Self-Hosted)

Request counts, latency, and performance metrics
Exposed at /metrics endpoint for your Prometheus server
Stays on your infrastructure

3. Error Monitoring (Optional - Sentry)

Captures uncaught exceptions and performance issues
Helps identify and fix bugs quickly
Opt-in: Set SENTRY_DSN environment variable

4. Product Analytics (Optional - Grafana OTLP)

Tracks feature usage and user behavior patterns with advanced features:
- Person Properties: Role, auth method, login history
- Group Analytics: Segment by version, platform, deployment
- Rich Context: Browser, device, environment on every event
Sink config: Set GRAFANA_OTLP_ENDPOINT and GRAFANA_OTLP_TOKEN

Rollouts and kill switches in this application are not driven by remote PostHog feature flags. Use environment variables and app/config.py (for example DEMO_MODE, ALLOW_SELF_REGISTER, ENABLE_TELEMETRY, SINGLE_ACTIVE_TIMER). Per-user UI visibility preferences are stored on the user record in the database, not in PostHog. With DEMO_MODE, the auto-created login is a standard user (no admin or settings access); see docs/deploy/RENDER.md for demo setup and upgrading old demo databases.

5. Installation Telemetry (Optional, Anonymous)

Sends anonymous installation data via Grafana OTLP with:
- Anonymized fingerprint (SHA-256 hash, cannot be reversed)
- Application version
- Platform information
No PII: No IP addresses, usernames, or business data
Opt-in: Set ENABLE_TELEMETRY=true for detailed analytics; base telemetry remains anonymous

How to Enable Analytics

# Enable Sentry error monitoring (optional)
SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
SENTRY_TRACES_RATE=0.1  # 10% sampling for performance traces

# Configure Grafana Cloud OTLP sink (optional)
GRAFANA_OTLP_ENDPOINT=https://otlp-gateway-prod-eu-west-2.grafana.net/otlp/v1/logs
GRAFANA_OTLP_TOKEN=your-grafana-otlp-token

# Enable detailed analytics (optional)
ENABLE_TELEMETRY=true
TELE_SALT=your-unique-salt
APP_VERSION=1.0.0

Self-Hosting Analytics

You can self-host all analytics services for complete control:

# Use docker-compose with monitoring profile
docker-compose --profile monitoring up -d

This starts:

Prometheus — Metrics collection and storage
Grafana — Visualization dashboards
Loki (optional) — Log aggregation
Promtail (optional) — Log shipping

Privacy & Data Protection

Telemetry: TimeTracker can optionally send anonymized usage data to help improve the product (errors, feature usage, install counts). All telemetry is opt-in. No personal data is collected. To disable telemetry, set ENABLE_TELEMETRY=false or simply don't set the environment variable (disabled by default).

What we DON'T collect:

❌ Email addresses or usernames
❌ IP addresses
❌ Project names or descriptions
❌ Time entry notes or client data
❌ Any personally identifiable information (PII)

Your rights:

📥 Access: View all collected data
✏️ Rectify: Correct inaccurate data
🗑️ Erase: Delete your data at any time
📤 Export: Export your data in standard formats

📖 See Privacy Policy for complete details
📖 See Analytics Documentation for configuration
📖 See Events Schema for tracked events

🛣️ Roadmap

Planned Features

📊 Advanced Analytics — More charts, insights, and reporting options
🔌 API Extensions — Additional RESTful API endpoints for integrations
🔔 Push Notifications — Real-time browser notifications
📱 Mobile & Desktop App Enhancements — Additional features for the native Flutter mobile and Electron desktop apps
🤖 Automation Rules — Automated workflows and task assignments
📈 Advanced Forecasting — AI-powered project timeline predictions

Technology stack

Flask, SQLAlchemy, PostgreSQL/SQLite, Tailwind CSS, Docker — see Architecture · Project Structure · UI Guidelines.

🤝 Contributing

We welcome contributions! Whether it's:

🐛 Bug Reports — Help us identify issues
💡 Feature Requests — Share your ideas
📝 Documentation — Improve our docs
💻 Code Contributions — Submit pull requests

Quick Start for Contributors

Fork and Clone

git clone https://github.com/your-username/TimeTracker.git
cd TimeTracker

Set Up Development Environment

# Use SQLite for quick local testing
docker-compose -f docker/docker-compose.local-test.yml up -d

Make Your Changes
- Follow the Contributing guidelines and full Contributing doc
- Write tests for new features
- Update documentation as needed
Submit a Pull Request
- Create a clear description of your changes
- Reference any related issues
- Ensure all tests pass

📖 CONTRIBUTING.md — Quick contributing overview
📖 Full Contributing Guidelines — Setup, standards, PR process
📖 DEVELOPMENT.md — Run locally, tests, releases
📖 Local Testing with SQLite — Docker SQLite setup

📄 License

TimeTracker is licensed under the GNU General Public License v3.0.

This means you can:

✅ Use it commercially
✅ Modify and adapt it
✅ Distribute it
✅ Use it privately

See LICENSE for full details

Support

If TimeTracker saves you money, a star on GitHub helps others find it.

Support the project / hide donate prompts: Support & Purchase Key — donate or buy a one-time key to remove donate prompts in your instance
Documentation: docs/
Bug reports: Open an issue
Discussions: GitHub Discussions

★ Star on GitHub

Built with care for the time-tracking community

Name		Name	Last commit message	Last commit date
.github		.github
app		app
browser-extension		browser-extension
desktop		desktop
docker		docker
docs		docs
examples/zapier		examples/zapier
grafana/provisioning/datasources		grafana/provisioning/datasources
loki		loki
migrations		migrations
mobile		mobile
nginx		nginx
peppol_bridge		peppol_bridge
prometheus		prometheus
promtail		promtail
scripts		scripts
tasks		tasks
templates		templates
tests		tests
translations		translations
.bandit		.bandit
.coveragerc		.coveragerc
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.flake8		.flake8
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.safety-policy.yml		.safety-policy.yml
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
INSTALLATION.md		INSTALLATION.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
UNINSTALL.md		UNINSTALL.md
VERSION		VERSION
app.py		app.py
babel.cfg		babel.cfg
crowdin.yml		crowdin.yml
docker-compose.example.yml		docker-compose.example.yml
docker-compose.nas.yml		docker-compose.nas.yml
docker-compose.yml		docker-compose.yml
donate_hide_public.pem		donate_hide_public.pem
env.example		env.example
env.local-test.example		env.local-test.example
fly.toml		fly.toml
package.json		package.json
playwright.config.mjs		playwright.config.mjs
postcss.config.js		postcss.config.js
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
railway.toml		railway.toml
render.yaml		render.yaml
requirements-dev.txt		requirements-dev.txt
requirements-test.txt		requirements-test.txt
requirements.txt		requirements.txt
setup.py		setup.py
tailwind.config.js		tailwind.config.js

Latest commit

History

Folders and files

Repository files navigation

TimeTracker

Self-hosted time tracking, invoicing and Peppol e-invoicing for freelancers and teams — with no per-seat fees.

Quick start (60 seconds)

Why TimeTracker?

What is TimeTracker?

✨ Features

⏱️ Smart Time Tracking

📊 Project & Task Management

💼 CRM & Sales Management 🆕

🧾 Professional Invoicing

💰 Financial Management

📈 Analytics & Reporting

🔐 Multi-User & Security

⌨️ Productivity Features

🛠️ Technical Excellence

📸 Screenshots

🔐 Simple Login & User Management

📁 Projects & Tasks — Stay Organized

📋 Kanban Board — Visual Task Management

⏱️ Time Tracking — Flexible & Powerful

🧾 Invoicing & Clients — Professional Billing

📊 Reports & Analytics — Data-Driven Insights

🛠️ Admin Dashboard — Complete Control

🎯 Easy Creation — Streamlined Workflows

Install options

Prerequisites

Option 1: NAS / one-file compose (recommended for first try)

Option 2: Production with HTTPS

Option 3: Docker with plain HTTP (development)

Option 4: Quick test with SQLite

💻 System Requirements

Minimum Requirements

Recommended Requirements

Platform Support

Database Options

Browser Support

💡 Use Cases

For Freelancers

For Teams

For Agencies

For Personal Projects

📚 Documentation

📖 Documentation by Use Case

🎯 Feature Documentation

🔧 Technical Documentation

🔒 Security & Configuration

🤝 Contributing

📋 Reference

🐳 Deployment

Local Development

Production Deployment

Option 1: Build from Source

Option 2: Use Pre-built Images

AI Helper (Ollama or hosted)

Bundled Ollama service (Docker Compose, opt-in)

Encrypting stored secrets (recommended)

Raspberry Pi Deployment

HTTPS Configuration

Automatic HTTPS (Easiest)

Manual HTTPS with mkcert (No Browser Warnings)

Monitoring & Analytics

🔧 Configuration

📊 Analytics & Telemetry

What We Collect (When Enabled)

1. Structured Logs (Always On, Local Only)

2. Prometheus Metrics (Always On, Self-Hosted)

3. Error Monitoring (Optional - Sentry)

4. Product Analytics (Optional - Grafana OTLP)

5. Installation Telemetry (Optional, Anonymous)

How to Enable Analytics

Self-Hosting Analytics

Privacy & Data Protection

🛣️ Roadmap

Planned Features

Technology stack

🤝 Contributing