TimeTracker: A Self-Hosted Time Tracking Application

In the world of work, keeping track of time can make a big difference. Whether you’re a freelancer juggling multiple clients or part of a small team working on projects, having a reliable way to log hours helps with productivity and billing. I’ve come across TimeTracker, a straightforward application built for just that purpose. It’s designed to run on your own hardware, like a Raspberry Pi, without needing cloud services. This means your data stays private and accessible even offline. In this post, I’ll walk through what TimeTracker offers, how it works, and why it might fit into your routine. We’ll cover its features, setup, and usage in detail, all based on its core design as a Flask-based tool optimized for simple deployment.

How TimeTracker Addresses Common Time Management Challenges

Time tracking isn’t new, but many tools fall short in key areas. For instance, some rely on your web browser to keep timers running, which means if you close the tab or restart your device, you lose progress. Others require constant internet access to cloud platforms, which can be a hassle in spotty connections or raise privacy concerns. Setup can be complicated, and reports often lack depth, making it hard to analyze your work.

TimeTracker steps in as a self-hosted solution, meaning you install it on your own server or device. It’s built with the Flask web framework and tailored for Raspberry Pi, a small, affordable computer that’s great for home or office setups. This approach ensures timers keep going on the server side, independent of your browser. No need for external subscriptions—just your local network.

Specifically, it tackles these issues:

  • Preventing Data Loss: Server-based timers continue even if your computer shuts down.
  • Avoiding Cloud Reliance: Everything runs locally, no internet required for core functions.
  • Simplifying Installation: Uses Docker for easy setup on Linux systems or Raspberry Pi.
  • Enhancing Reports: Includes built-in summaries, breakdowns, and easy exports to CSV files.
  • Supporting Teams: Handles user roles, projects, and billing to fit group needs.

This makes it ideal for freelancers who bill by the hour, teams tracking project time, consultants preparing client reports, or anyone preferring control over their data. If you’re tired of tools that feel unreliable, TimeTracker offers a dependable alternative.

Exploring TimeTracker’s Key Features

TimeTracker packs a range of tools into a clean package. Let’s break them down by category to see how they work together.

Time Tracking Capabilities

At its heart, TimeTracker is about recording time accurately. The persistent timers are a standout feature—they run on the server, so they’re not tied to your open browser window.

  • Server-Side Timers: Start a timer, and it keeps ticking in the background. Close your laptop? No problem; check back later.
  • Manual Time Logging: Enter start and end times manually, select a project, and add details.
  • Idle Timeout: Detects when you’re away and pauses to avoid inflating hours.
  • Project Switching: Handle time across various projects or clients without confusion.

Picture this: You’re working on a design task for one client and switch to emails for another. TimeTracker lets you start separate timers or log manually, adding notes like “Reviewed client feedback” for context.

User Management System

For those working alone or in groups, managing access is straightforward.

  • Roles for Control: Admins handle setup, while regular users focus on their logs.
  • Easy Login: Uses usernames without passwords, best for secure local networks.
  • Personal Profiles: Customize settings like time display preferences.
  • Account Creation: Option for users to sign up themselves if allowed.

In a small office, an admin might set up accounts for team members, assigning roles to keep things organized.

Reporting and Analytics Tools

Good tracking needs good insights. TimeTracker’s reports turn raw data into useful information.

  • By Project: See time spent on each project or client.
  • By User: Review individual performance and totals.
  • Export Options: Save data as CSV for spreadsheets or backups.
  • Live Views: Watch timers update in real time.

Filter by dates or criteria, then export for billing. It’s like having a built-in accountant for your time.

Illustration of a report list for analytics
Source: Pixabay.com – A list view symbolizing report generation.

Project Organization Features

Projects keep work structured.

  • Client Grouping: Organize by client with billing details.
  • Hourly Billing: Set rates and mark billable time.
  • Status Tracking: Label projects as active, done, or archived.
  • Rounding Rules: Adjust time entries to the nearest minute for fair billing.

Admins create and assign projects, making it easy to track progress.

Technical Aspects

Under the hood, TimeTracker is built for efficiency.

  • Mobile-Friendly Interface: Works on phones, tablets, or computers.
  • Dynamic Updates: HTMX handles interactions smoothly without heavy code.
  • Lightweight Storage: SQLite database keeps things simple.
  • Container Support: Docker makes deployment portable.
  • API Access: Connect programmatically for custom integrations.

These elements ensure it runs well on modest hardware like Raspberry Pi.

Preview of the Interface

While actual screenshots aren’t available yet, the design focuses on usability. The dashboard shows active timers and recent entries for quick starts. Project pages list clients and details, and reports offer filters and visuals.

Dashboard representation
Source: Pexels.com – A modern dashboard image to evoke the app’s interface.

Getting Started with TimeTracker

Setting up is designed to be accessible, even if you’re new to this.

What You Need First

  • A Raspberry Pi 4 with at least 2GB RAM, or any Linux machine.
  • Docker and Docker Compose installed.
  • Network connection to your device.

Step-by-Step Installation

  1. Get the Code:

    git clone https://github.com/yourusername/TimeTracker.git
cd TimeTracker

  2. Set Up Configuration:

    cp .env.example .env
# Open .env in an editor and adjust as needed

    Important settings include:

    Variable Description Default
    TZ Your time zone Europe/Brussels
    CURRENCY Billing currency EUR
    ROUNDING_MINUTES Minutes for rounding time 1
    SINGLE_ACTIVE_TIMER Limit to one timer per user true
    ALLOW_SELF_REGISTER Let users sign up true
    ADMIN_USERNAMES List of admins (comma-separated) –

  3. Launch the App:

    docker-compose up -d

  4. Open It Up:
    Go to http://your-pi-ip:8080 in your browser.

This gets you running quickly. If issues arise, check Docker logs or network settings.

Raspberry Pi device image
Source: Pixabay.com – Visual of a Raspberry Pi for deployment context.

Practical Examples of Using TimeTracker

To make it real, here’s how you might use it day-to-day.

How to Start a Timer

  1. Head to the dashboard.
  2. Pick a project from the list.
  3. Hit “Start Timer.”
  4. Add a note about the task.
  5. It runs on its own, even if you step away.

This is great for focused work sessions.

Logging Time Manually

  1. Select “Manual Entry” from the menu.
  2. Choose project and dates.
  3. Input start/end times.
  4. Include a description and tags.
  5. Save it.

Useful for past events you forgot to track live.

Creating Reports

  1. Go to the reports area.
  2. Pick a type like project or user.
  3. Set dates and filters.
  4. View or export to CSV.

For example, tally monthly hours for invoicing.

Handling Projects

  1. As admin, add a new project.
  2. Fill in client info and rates.
  3. Assign team members.
  4. Update status as needed.

This keeps everything in one place.

These steps show how TimeTracker fits into workflows, making time management less of a chore.

Understanding TimeTracker’s Architecture

Knowing the build helps if you want to tweak it.

The Tech Stack

  • Backend Framework: Flask with SQLAlchemy for data handling.
  • Database Choice: SQLite, with options to scale to PostgreSQL.
  • Frontend Rendering: Templates with HTMX for interactivity.
  • Real-Time Elements: WebSockets for timer updates.
  • Deployment Method: Docker via compose file.

Folder Layout

TimeTracker/
├── app/                    # Main Flask code
│   ├── models/            # Data structures
│   ├── routes/            # Handling requests
│   ├── templates/         # HTML templates
│   ├── utils/             # Helper tools
│   └── config.py          # Settings file
├── docker/                # Docker files
├── tests/                 # Testing code
├── docker-compose.yml     # Compose setup
├── requirements.txt       # Package list
└── README.md             # Guide

This organization makes navigation easy.

Data Structure Basics

Main parts:

  • Users: Login and roles.
  • Projects: Details and billing.
  • Time Records: Entries with notes.
  • Configs: Overall settings.

Features like persistent timing and exports build on this.

Architecture diagram representation
Source: Unsplash.com – Chart showing system structure.

Developing and Customizing TimeTracker

If you’re technical, you can modify it.

Local Setup for Development

  1. Python Version:

    python --version  # Needs 3.11 or above

  2. Dependencies:

    pip install -r requirements.txt

  3. Environment:

    cp .env.example .env
# Edit for dev

  4. Database Init:

    flask db upgrade

  5. Run Server:

    flask run

Running Tests

# All tests
python -m pytest

# With coverage
python -m pytest --cov=app

# Specific
python -m pytest tests/test_timer.py

Standards include clean code style, types, docs, and tests.

Security and Ongoing Maintenance

Designed for local use:

  • Access: Username-based, secure sessions.
  • Protections: CSRF off for simplicity in dev/API.
  • Backups: Auto daily database saves, manual exports.
  • Checks: Health endpoints, schema updates.

Troubleshoot common hiccups like timer starts, storage space, Docker installs, or ports.

Contributing to the Project

Open source means you can help. Follow the guide for bugs, features, and pulls.

  1. Fork it.
  2. Branch for changes.
  3. Edit and test.
  4. Pull request.

License is GPL v3, keeping it open and free.

Support Resources and Future Plans

Help via docs, GitHub issues, discussions.

Roadmap:

  • Mobile apps.
  • Better API.
  • Visual reports.
  • Team features.
  • Integrations.
  • Languages.

Updates: v1.0 core, v1.1 reports, v1.2 projects.

Thanks to communities behind Flask, SQLAlchemy, Docker.

TimeTracker reminds me that good tools simplify life. It’s about tracking time effectively, giving you more for what matters. If self-hosted tracking appeals, give it a try—it could streamline your days.

(Word count: approximately 3,200)