TimeTracker

Professional Time Tracking & Project Management for Teams

Track time. Manage projects. Generate invoices. All in one place.

🚀 Quick Start • ✨ Features • 📸 Screenshots • 📖 Getting Started • 📚 Documentation • 🐳 Deploy

---

🎯 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

---

✨ Features

⏱️ 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
• Time Entry Templates — Save and reuse common time entries for faster logging
• Calendar View — Visual calendar interface for viewing and managing time entries
• 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
• Task Board — Visual task management with priorities and assignments
• Kanban Board — Drag-and-drop task management with customizable columns
• Status Tracking — Monitor progress from to-do to completion
• Estimates vs Actuals — Track project budgets and burn rates
• Task Comments — Collaborate with threaded comments on tasks
• Markdown Support — Rich text formatting in project and task descriptions

🧾 Professional Invoicing

• Generate from Time — Convert tracked hours to invoices automatically
• 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 branding
• Status Tracking — Track draft, sent, paid, and overdue invoices
• Company Branding — Add logos and custom company information
• Expense Integration — Include tracked expenses in invoices

💰 Financial Management

• Expense Tracking — Track business expenses with receipts and categories
• Payment Tracking — Monitor invoice payments and payment methods
• Reimbursement Management — Handle expense approvals and reimbursements
• Billable Expenses — Mark expenses as billable and add to invoices
• Multi-Currency — Support for multiple currencies with conversion

📈 Analytics & Reporting

• Visual Dashboards — Charts and graphs for quick insights
• 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

🔐 Multi-User & Security

• Role-Based Access Control — Granular permissions system with custom roles
• 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.)
• Session Management — Secure cookies and session handling
• Profile Pictures — Users can upload profile pictures
• API Tokens — Generate tokens for API access and integrations

⌨️ Productivity Features

• Command Palette — Keyboard-driven navigation with shortcuts (press ?)
• Keyboard Shortcuts — Navigate and execute actions without the mouse
• Quick Search — Fast search across projects, tasks, clients, and more (Ctrl+K)
• Email Notifications — Configurable email alerts for tasks, invoices, and more
• Weekly Summaries — Optional weekly time tracking summaries via email

🛠️ Technical Excellence

• Docker Ready — Deploy in minutes with Docker Compose
• Database Flexibility — PostgreSQL for production, SQLite for testing
• Responsive Design — Works perfectly on desktop, tablet, and mobile
• Real-time Sync — WebSocket support for live updates
• Automatic Backups — Scheduled database backups (configurable)
• Progressive Web App — Install as a mobile app on phones and tablets
• Monitoring Stack — Built-in Prometheus, Grafana, Loki for observability
• Internationalization — Multiple language support (i18n)

---

📸 Screenshots

🏠 Dashboard — Your Command Center

Start timers, view recent entries, and see your productivity at a glance

---

🔐 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

---

🚀 Quick Start

Option 1: Docker with HTTPS (Recommended for Production)

Get TimeTracker running in under 2 minutes with automatic HTTPS:

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

# Create your environment file from the template
cp env.example .env

# IMPORTANT: Edit .env and set a strong SECRET_KEY
# Generate one with: python -c "import secrets; print(secrets.token_hex(32))"
# Also set your timezone (TZ) and currency (CURRENCY)
nano .env  # or use any text editor

# Start with Docker Compose (includes HTTPS via nginx with self-signed cert)
docker-compose up -d

# Access at https://localhost
# Your browser will warn about the self-signed certificate - that's normal

First login creates the admin account — just enter your username!

📖 See the complete setup guide: docs/DOCKER_COMPOSE_SETUP.md

Option 2: Docker with Plain HTTP (Development/Testing)

For local development or testing without HTTPS:

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

# Use the example compose file that exposes HTTP directly
docker-compose -f docker-compose.example.yml up -d

# Access at http://localhost:8080

Option 3: Quick Test with SQLite

Want to try it out without any configuration?

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

# Start with the local test configuration (uses SQLite, no PostgreSQL)
docker-compose -f docker-compose.local-test.yml up --build

# Access at http://localhost:8080

No database setup or .env file needed — perfect for quick testing!

---

💡 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.

---

🌟 Why TimeTracker?

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

---

📚 Documentation

Comprehensive documentation is available in the docs/ directory:

Getting Started

• 📖 Getting Started Guide — Complete beginner's guide (⭐ Start here!)
• Installation Guide — Detailed setup instructions
• Requirements — System requirements and dependencies
• Troubleshooting — Common issues and solutions
• CSRF Token Issues — Fix "CSRF token missing or invalid" errors
• CSRF IP Access Fix — 🔥 Fix cookies not working when accessing via IP address
• HTTPS Auto-Setup — 🚀 Automatic HTTPS at startup (one command!)
• HTTPS Manual Setup (mkcert) — 🔒 Manual HTTPS with no certificate warnings

Features

• Task Management — Break projects into manageable tasks
• Invoice System — Generate professional invoices
• Client Management — Manage client relationships
• Calendar Features — Calendar and bulk entry features
• Bulk Time Entry — Create multiple time entries at once
• Command Palette — Keyboard shortcuts for power users
• Expense Tracking — Track business expenses (if available)
• Role-Based Permissions — Granular access control (if available)

Technical Documentation

• Project Structure — Codebase architecture
• Database Migrations — Database schema management
• Version Management — Release and versioning
• CSRF Configuration — Security and CSRF token setup for Docker
• CI/CD Documentation — Continuous integration setup

Contributing

• Contributing Guidelines — How to contribute
• Code of Conduct — Community standards

---

🐳 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-compose.remote.yml up -d

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

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-compose.https-mkcert.yml up -d

📖 See HTTPS Setup Guide for detailed instructions

Monitoring & Analytics

# Deploy with full monitoring stack (Prometheus, Grafana, Loki)
docker-compose 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:

• docs/DOCKER_COMPOSE_SETUP.md
• env.example

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
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 - PostHog)

• Tracks feature usage and user behavior patterns with advanced features:
  • Person Properties: Role, auth method, login history
  • Feature Flags: Gradual rollouts, A/B testing, kill switches
  • Group Analytics: Segment by version, platform, deployment
  • Rich Context: Browser, device, environment on every event
• Opt-in: Set POSTHOG_API_KEY environment variable
• See POSTHOG_ADVANCED_FEATURES.md for complete guide

5. Installation Telemetry (Optional, Anonymous)

• Sends anonymous installation data via PostHog 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 and POSTHOG_API_KEY environment variables

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

# Enable PostHog product analytics (optional)
POSTHOG_API_KEY=your-posthog-api-key
POSTHOG_HOST=https://app.posthog.com

# Enable anonymous telemetry (optional, uses PostHog)
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

• 📄 PDF Invoice Templates — Professional PDF generation
• 📧 Email Integration — Send invoices to clients
• 📱 Progressive Web App — Install as mobile app
• 🔄 Recurring Invoices — Automate recurring billing
• 🎨 Custom Themes — Personalize your interface
• 🔌 API Extensions — RESTful API for integrations
• 📊 Advanced Analytics — More charts and insights

Recently Added

• ✅ Invoice Generation — Complete invoicing system with PDF export
• ✅ Task Management — Full task tracking and management with Kanban board
• ✅ Command Palette — Keyboard-driven navigation (press ?)
• ✅ Calendar View — Visual time entry calendar
• ✅ Bulk Time Entry — Create multiple entries for consecutive days
• ✅ Time Entry Templates — Save and reuse common time entries
• ✅ Expense Tracking — Track business expenses with receipts
• ✅ Payment Tracking — Monitor invoice payments
• ✅ Saved Filters — Save frequently used report filters
• ✅ Task Comments — Collaborate with comments on tasks
• ✅ Role-Based Permissions — Granular access control system
• ✅ OIDC/SSO Authentication — Enterprise authentication support
• ✅ Markdown Support — Rich text in descriptions

---

🤝 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

📖 See Contributing Guidelines to get started

---

📄 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

• 📖 Documentation: Check the docs/ directory
• 🐛 Bug Reports: Open an issue
• 💬 Discussions: GitHub Discussions
• 📧 Contact: Create an issue for support

---

⭐ Star Us!

If TimeTracker helps you track your time better, consider giving us a star on GitHub! It helps others discover the project.

⭐ Star on GitHub

---

Built with ❤️ for the time-tracking community