# TimeTracker
### Professional Time Tracking & Project Management for Teams **Track time. Manage projects. Generate invoices. All in one place.** [๐Ÿ†• What's New](#-whats-new) โ€ข [๐Ÿš€ Quick Start](#-quick-start) โ€ข [โœจ Features](#-features) โ€ข [๐Ÿ“ธ Screenshots](#-screenshots) โ€ข [๐Ÿ“– Getting Started](docs/GETTING_STARTED.md) โ€ข [๐Ÿ“š Documentation](docs/) โ€ข [๐Ÿ“‹ Changelog](CHANGELOG.md) โ€ข [๐Ÿณ Deploy](#-deployment) ---
## ๐ŸŽฏ 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 --- ## ๐Ÿ†• What's New TimeTracker has been continuously enhanced with powerful new features! Here's what's been added recently: > **๐Ÿ“‹ For complete release history, see [CHANGELOG.md](CHANGELOG.md)** **Latest Release: v4.8.8** (January 2025) - ๐Ÿ“‹ **Project Analysis & Documentation** โ€” Comprehensive project analysis and documentation updates - ๐Ÿ”ง **Version Consistency** โ€” Fixed version inconsistencies across documentation files **Previous Releases:** - **v4.6.0** (December 2025) โ€” Comprehensive Issue/Bug Tracking System **Recent Releases:** - **v4.5.1** โ€” Performance optimizations and version management improvements - **v4.5.0** โ€” Advanced Report Builder, quick task creation, Kanban enhancements, and PWA improvements - **v4.4.1** โ€” Dashboard cache fixes and custom reports enhancements - **v4.4.0** โ€” Project custom fields, file attachments, and salesman-based report splitting ### ๐ŸŽฏ **Major Feature Additions** #### ๐Ÿงพ **Complete Invoicing System** - **Professional Invoice Generation** โ€” Convert tracked time directly into polished invoices - **PDF Export** โ€” Generate beautiful, branded PDF invoices with your company logo - **Multi-Currency Support** โ€” Invoice clients in their preferred currency - **Tax Calculations** โ€” Automatic tax computation with configurable rates - **Invoice Status Tracking** โ€” Monitor draft, sent, paid, and overdue invoices - **Recurring Invoices** โ€” Automate regular billing cycles - **Email Integration** โ€” Send invoices directly to clients from the platform - **Peppol e-Invoicing (BIS Billing 3.0)** โ€” Send invoices via Peppol through your access point ([setup guide](docs/admin/configuration/PEPPOL_EINVOICING.md)) #### ๐Ÿ“‹ **Advanced Task Management** - **Full Task System** โ€” Create, assign, and track tasks with priorities and due dates - **Kanban Board** โ€” Visual drag-and-drop task management with customizable columns - **Task Comments** โ€” Collaborate with threaded comments on tasks - **Task Activity Tracking** โ€” See complete history of task changes and updates - **Bulk Task Operations** โ€” Manage multiple tasks at once #### ๐Ÿ’ผ **Complete CRM Suite** ๐Ÿ†• - **Multiple Contacts per Client** โ€” Manage unlimited contacts for each client - **Sales Pipeline** โ€” Visual Kanban-style pipeline for tracking deals and opportunities - **Deal Management** โ€” Track deal value, probability, stages, and 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 & Lead Activities** โ€” Complete activity tracking for sales processes #### โฑ๏ธ **Enhanced Time Tracking** - **Calendar View** โ€” Visual calendar interface for viewing and managing time entries - **Bulk Time Entry** โ€” Create multiple time entries for consecutive days with weekend skipping - **Time Entry Templates** โ€” Save and reuse common time entries for faster logging - **Real-time Updates** โ€” See live timer updates across all devices via WebSocket #### ๐Ÿ’ฐ **Financial Management** - **Expense Tracking** โ€” Track business expenses with receipts, categories, and approval workflows - **Payment Tracking** โ€” Monitor invoice payments with multiple payment methods - **Billable Expenses** โ€” Mark expenses as billable and automatically include in invoices - **Reimbursement Management** โ€” Handle expense approvals and reimbursements #### ๐Ÿ” **Enterprise Security & Access** - **Role-Based Access Control (RBAC)** โ€” Granular permissions system with custom roles - **OIDC/SSO Authentication** โ€” Enterprise authentication support (Azure AD, Authelia, etc.) - **API Tokens** โ€” Generate secure tokens for API access and integrations - **Audit Logs** โ€” Track all system activity and user actions #### โŒจ๏ธ **Productivity Power-Ups** - **Command Palette** โ€” Keyboard-driven navigation (press `?` to open) - **Keyboard Shortcuts** โ€” 50+ shortcuts for lightning-fast navigation - **Quick Search** โ€” Fast search across projects, tasks, clients, and more (Ctrl+K) - **Saved Filters** โ€” Save frequently used report filters for instant access #### โœ๏ธ **Content & Formatting** - **Markdown Support** โ€” Rich text formatting in project and task descriptions - **Enhanced UI Components** โ€” Modern, accessible interface components - **Toast Notifications** โ€” Beautiful in-app notifications for actions and updates #### ๐ŸŽจ **Modern UX & Layout Enhancements** ๐Ÿ†• - **Enterprise-Grade Tables** โ€” Sortable columns, bulk actions, inline editing, and CSV export - **Enhanced Search** โ€” Instant search with autocomplete, recent searches, and categorized results (Ctrl+K) - **Data Visualization** โ€” Interactive charts with Chart.js (6 chart types, responsive, exportable) - **Progressive Web App (PWA)** โ€” Install as mobile app, offline support, background sync - **Accessibility Excellence** โ€” WCAG 2.1 AA compliant, keyboard navigation, screen reader support - **Interactive Onboarding** โ€” Step-by-step product tours for new users - **Advanced Forms** โ€” Auto-save, form state persistence, inline validation, smart defaults - **Design System** โ€” Unified component library with 20+ reusable UI components - **Loading States** โ€” Skeleton components and loading indicators throughout - **Enhanced Empty States** โ€” Beautiful, actionable empty states with guidance #### ๐Ÿ—๏ธ **Architecture & Performance Improvements** ๐Ÿ†• - **Service Layer Migration** โ€” Routes migrated to service layer pattern for better maintainability - **Query Optimization** โ€” Fixed N+1 query problems, reduced database queries by 80-90% - **Environment Validation** โ€” Comprehensive startup validation with helpful error messages - **Base CRUD Service** โ€” Reusable service classes reducing code duplication - **API Token Security** โ€” Enhanced token management with rotation, expiration, and scoping --- ## โœจ Features TimeTracker includes **130+ features** across 13 major categories. See the [Complete Features Documentation](docs/FEATURES_COMPLETE.md) for a comprehensive overview. ### โฑ๏ธ **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 - **Focus Sessions** โ€” Pomodoro-style focus session tracking - **Recurring Time Blocks** โ€” Weekly recurring time block templates - **Time Rounding** โ€” Configurable rounding intervals - **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 - **Budget Tracking** โ€” Monitor project budgets with alerts and forecasting - **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 - **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 - **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 e-Invoicing (BIS Billing 3.0)** โ€” Send invoices electronically via Peppol (configure in **Admin โ†’ System Settings**; docs: [PEPPOL_EINVOICING.md](docs/admin/configuration/PEPPOL_EINVOICING.md)) ### ๐Ÿ’ฐ **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 - **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 - **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 - **Budget Forecasting** โ€” Predict project completion dates based on burn rates - **Weekly Time Goals** โ€” Set and track weekly hour targets - **Overtime Tracking** โ€” Monitor and report overtime hours ### ๐Ÿ” **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 - **Audit Logs** โ€” Track all system activity and user actions ### โŒจ๏ธ **Productivity Features** - **Command Palette** โ€” Keyboard-driven navigation with shortcuts (press `?`) - **Keyboard Shortcuts** โ€” 50+ shortcuts for lightning-fast navigation and actions - **Quick Search** โ€” Enhanced instant search with autocomplete and categorized results (Ctrl+K) - **Quick Actions Menu** โ€” Floating action button with 6 quick actions (bottom-right) - **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 for actions and updates - **Weekly Summaries** โ€” Optional weekly time tracking summaries via email - **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 - **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
### ๐Ÿ  Dashboard โ€” Your Command Center Dashboard *Start timers, view recent entries, and see your productivity at a glance* --- ### ๐Ÿ” Simple Login & User Management
Login Profile
*Simple username-based authentication and customizable user profiles with avatar support* --- ### ๐Ÿ“ Projects & Tasks โ€” Stay Organized
Projects Tasks
*Manage multiple projects and break them down into actionable tasks* --- ### ๐Ÿ“‹ Kanban Board โ€” Visual Task Management Kanban Board *Drag-and-drop task management with customizable columns and visual workflow* --- ### โฑ๏ธ Time Tracking โ€” Flexible & Powerful
Log Time Time Entry Templates
*Manual time entry and reusable templates for faster logging* --- ### ๐Ÿงพ Invoicing & Clients โ€” Professional Billing
Invoices Client Management
*Generate invoices from tracked time and manage client relationships* --- ### ๐Ÿ“Š Reports & Analytics โ€” Data-Driven Insights
Reports User Reports
*Comprehensive reporting and user analytics for informed decisions* --- ### ๐Ÿ› ๏ธ Admin Dashboard โ€” Complete Control Admin Dashboard *Manage users, configure settings, and monitor system health* --- ### ๐ŸŽฏ Easy Creation โ€” Streamlined Workflows
Create Project Create Task Create Client
*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: ```bash # 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/admin/configuration/DOCKER_COMPOSE_SETUP.md`](docs/admin/configuration/DOCKER_COMPOSE_SETUP.md) ### Option 2: Docker with Plain HTTP (Development/Testing) For local development or testing without HTTPS: ```bash # 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? ```bash # 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/`](docs/) directory: ### Release Information - **[๐Ÿ“‹ Changelog](CHANGELOG.md)** โ€” Complete release history with all changes and new features (โญ See what's new!) ### Getting Started - **[๐Ÿ“– Getting Started Guide](docs/GETTING_STARTED.md)** โ€” Complete beginner's guide (โญ Start here!) - **[Installation Guide](docs/admin/configuration/DOCKER_PUBLIC_SETUP.md)** โ€” Detailed setup instructions - **[Requirements](docs/REQUIREMENTS.md)** โ€” System requirements and dependencies - **[Troubleshooting](docs/admin/configuration/DOCKER_STARTUP_TROUBLESHOOTING.md)** โ€” Common issues and solutions - **[CSRF Token Issues](docs/admin/security/CSRF_TROUBLESHOOTING.md)** โ€” Fix "CSRF token missing or invalid" errors - **[CSRF IP Access Fix](docs/admin/security/CSRF_IP_ACCESS_FIX.md)** โ€” ๐Ÿ”ฅ Fix cookies not working when accessing via IP address - **[HTTPS Auto-Setup](docs/admin/security/README_HTTPS_AUTO.md)** โ€” ๐Ÿš€ Automatic HTTPS at startup (one command!) - **[HTTPS Manual Setup (mkcert)](docs/admin/security/README_HTTPS.md)** โ€” ๐Ÿ”’ Manual HTTPS with no certificate warnings ### Features - **[๐Ÿ“‹ Complete Features Overview](docs/FEATURES_COMPLETE.md)** โ€” Comprehensive documentation of all 120+ features (โญ Complete reference!) - **[Task Management](docs/TASK_MANAGEMENT_README.md)** โ€” Break projects into manageable tasks - **[Invoice System](docs/INVOICE_FEATURE_README.md)** โ€” Generate professional invoices - **[Peppol e-Invoicing](docs/admin/configuration/PEPPOL_EINVOICING.md)** โ€” Enable and configure Peppol sending - **[Client Management](docs/CLIENT_MANAGEMENT_README.md)** โ€” Manage client relationships - **[Calendar Features](docs/CALENDAR_FEATURES_README.md)** โ€” Calendar and bulk entry features - **[Bulk Time Entry](docs/BULK_TIME_ENTRY_README.md)** โ€” Create multiple time entries at once - **[Command Palette](docs/COMMAND_PALETTE_USAGE.md)** โ€” Keyboard shortcuts for power users - **[Expense Tracking](docs/EXPENSE_TRACKING.md)** โ€” Track business expenses - **[Payment Tracking](docs/PAYMENT_TRACKING.md)** โ€” Track invoice payments - **[Budget Alerts & Forecasting](docs/BUDGET_ALERTS_AND_FORECASTING.md)** โ€” Monitor project budgets - **[Weekly Time Goals](docs/WEEKLY_TIME_GOALS.md)** โ€” Set and track weekly hour targets - **[Role-Based Permissions](docs/ADVANCED_PERMISSIONS.md)** โ€” Granular access control ### Technical Documentation - **[Project Structure](docs/development/PROJECT_STRUCTURE.md)** โ€” Codebase architecture - **[Database Migrations](migrations/README.md)** โ€” Database schema management - **[Version Management](docs/admin/deployment/VERSION_MANAGEMENT.md)** โ€” Release and versioning - **[CSRF Configuration](docs/admin/security/CSRF_CONFIGURATION.md)** โ€” Security and CSRF token setup for Docker - **[CI/CD Documentation](docs/cicd/)** โ€” Continuous integration setup ### Contributing - **[Contributing Guidelines](docs/development/CONTRIBUTING.md)** โ€” How to contribute - **[Code of Conduct](docs/development/CODE_OF_CONDUCT.md)** โ€” Community standards --- ## ๐Ÿณ Deployment ### Local Development ```bash # 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 ```bash # 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 ```bash # 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](docs/admin/security/CSRF_CONFIGURATION.md) for details. ### Raspberry Pi Deployment TimeTracker runs perfectly on Raspberry Pi 4 (2GB+ RAM): ```bash # Same Docker commands work on ARM architecture docker-compose up -d ``` ### HTTPS Configuration #### Automatic HTTPS (Easiest) ```bash # Uses self-signed certificates (generated automatically) docker-compose up -d # Access at https://localhost (accept browser warning) ``` #### Manual HTTPS with mkcert (No Browser Warnings) ```bash # Use mkcert for locally-trusted certificates docker-compose -f docker-compose.https-mkcert.yml up -d ``` **๐Ÿ“– See [HTTPS Setup Guide](README_HTTPS.md) for detailed instructions** ### Monitoring & Analytics ```bash # Deploy with full monitoring stack (Prometheus, Grafana, Loki) docker-compose up -d # Grafana: http://localhost:3000 # Prometheus: http://localhost:9090 ``` **๐Ÿ“– See [Deployment Guide](docs/admin/configuration/DOCKER_PUBLIC_SETUP.md) for detailed instructions** **๐Ÿ“– See [Docker Compose Setup](docs/admin/configuration/DOCKER_COMPOSE_SETUP.md) for configuration options** --- ## ๐Ÿ”ง Configuration TimeTracker is highly configurable through environment variables. For a comprehensive list and recommended values, see: - [`docs/admin/configuration/DOCKER_COMPOSE_SETUP.md`](docs/admin/configuration/DOCKER_COMPOSE_SETUP.md) - [`env.example`](env.example) Common settings: ```bash # 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 - 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](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 ```bash # 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: ```bash # 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](docs/privacy.md) for complete details** **๐Ÿ“– See [Analytics Documentation](docs/analytics.md) for configuration** **๐Ÿ“– See [Events Schema](docs/events.md) for tracked events** --- ## ๐Ÿ›ฃ๏ธ Roadmap ### Planned Features - ๐ŸŽจ **Custom Themes** โ€” Personalize your interface with custom color schemes - ๐Ÿ“Š **Advanced Analytics** โ€” More charts, insights, and reporting options - ๐Ÿ”Œ **API Extensions** โ€” Additional RESTful API endpoints for integrations - ๐Ÿ”” **Push Notifications** โ€” Real-time browser notifications - ๐Ÿ“ฑ **Mobile App** โ€” Native iOS and Android apps - ๐Ÿค– **Automation Rules** โ€” Automated workflows and task assignments - ๐Ÿ“ˆ **Advanced Forecasting** โ€” AI-powered project timeline predictions ### ๐ŸŽ‰ Recently Added Features #### ๐Ÿ’ผ Business & CRM Features - โœ… **Complete CRM Suite** โ€” Multiple contacts, sales pipeline, deal tracking, and lead management - โœ… **Invoice Generation** โ€” Full invoicing system with PDF export, multi-currency, and tax calculations - โœ… **Expense Tracking** โ€” Comprehensive expense management with receipts and categories - โœ… **Payment Tracking** โ€” Monitor invoice payments with multiple payment methods - โœ… **Recurring Invoices** โ€” Automate recurring billing cycles #### ๐Ÿ“‹ Project & Task Management - โœ… **Task Management System** โ€” Complete task tracking with priorities, assignments, and due dates - โœ… **Kanban Board** โ€” Visual drag-and-drop task management with customizable columns - โœ… **Task Comments** โ€” Threaded collaboration with comments on tasks - โœ… **Task Activity Tracking** โ€” Complete history of all task changes #### โฑ๏ธ Time Tracking Enhancements - โœ… **Calendar View** โ€” Visual calendar interface for viewing and managing time entries - โœ… **Bulk Time Entry** โ€” Create multiple entries for consecutive days with weekend skipping - โœ… **Time Entry Templates** โ€” Save and reuse common time entries for faster logging - โœ… **Real-time Updates** โ€” Live timer synchronization across all devices via WebSocket #### ๐Ÿ” Security & Access Control - โœ… **Role-Based Permissions (RBAC)** โ€” Granular access control system with custom roles - โœ… **OIDC/SSO Authentication** โ€” Enterprise authentication support (Azure AD, Authelia, etc.) - โœ… **API Tokens** โ€” Secure token generation for API access and integrations - โœ… **Audit Logs** โ€” Complete system activity and user action tracking #### โŒจ๏ธ Productivity Features - โœ… **Command Palette** โ€” Keyboard-driven navigation (press `?` to open) - โœ… **Keyboard Shortcuts** โ€” 50+ shortcuts for power users - โœ… **Quick Search** โ€” Fast search across all entities (Ctrl+K) - โœ… **Saved Filters** โ€” Save frequently used report filters for quick access #### โœจ User Experience - โœ… **Modern UX & Layout** โ€” Complete UI/UX overhaul with 16 major improvements - โœ… **Enterprise-Grade Tables** โ€” Sortable, filterable, inline-editable tables with bulk actions - โœ… **Enhanced Search** โ€” Instant search with autocomplete and categorized results - โœ… **Data Visualization** โ€” Interactive charts with Chart.js integration - โœ… **Progressive Web App** โ€” Full PWA capabilities with offline support - โœ… **Accessibility Excellence** โ€” WCAG 2.1 AA compliant with full keyboard navigation - โœ… **Interactive Onboarding** โ€” Step-by-step product tours for new users - โœ… **Design System** โ€” Unified component library with 20+ reusable components - โœ… **Markdown Support** โ€” Rich text formatting in descriptions - โœ… **Toast Notifications** โ€” Beautiful in-app notification system - โœ… **Enhanced UI Components** โ€” Modern, accessible interface elements #### ๐Ÿ—๏ธ Architecture & Performance - โœ… **Service Layer Migration** โ€” Routes migrated to service layer pattern - โœ… **Query Optimization** โ€” Fixed N+1 queries, reduced database queries by 80-90% - โœ… **Environment Validation** โ€” Comprehensive startup validation - โœ… **Base CRUD Services** โ€” Reusable service classes reducing code duplication - โœ… **API Token Security** โ€” Enhanced token management with rotation and scoping --- ## ๐Ÿค 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](docs/development/CONTRIBUTING.md) 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](LICENSE) for full details** --- ## ๐Ÿ†˜ Support - ๐Ÿ“– **Documentation**: Check the [`docs/`](docs/) directory - ๐Ÿ› **Bug Reports**: [Open an issue](https://github.com/drytrix/TimeTracker/issues) - ๐Ÿ’ฌ **Discussions**: [GitHub Discussions](https://github.com/drytrix/TimeTracker/discussions) - ๐Ÿ“ง **Contact**: [Create an issue](https://github.com/drytrix/TimeTracker/issues) 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](https://github.com/drytrix/TimeTracker)** --- **Built with โค๏ธ for the time-tracking community**