Time Tracker

A responsive Flask-based time tracking application for tracking time spent on client projects.

Features

• Client & Project Management: Create and manage clients and their associated projects
• Time Tracking: Clock in/out functionality with visual feedback
• Real-time Sync: Automatically syncs status across multiple devices (updates every 5 seconds)
• Configurable Granularity: Round time to 1, 5, 15, 30, or 60 minutes
• Export Reports: Generate and download/email time reports as text files
• Responsive Design: Works seamlessly on mobile phones, tablets, and desktop computers
• Containerized: Easy deployment with Docker

Installation

Option 1: Docker (Recommended)

1. Clone the repository:

   cd timetracker
   

2. Create a .env file (optional, for email functionality):

   cp .env.example .env
   # Edit .env with your email settings
   

3. Build and run with Docker Compose:

   docker-compose up -d
   

4. Access the application at http://localhost:5000

Option 2: Local Development

1. Create a virtual environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Run the application:

   python app.py
   

4. Access the application at http://localhost:5000

Usage

Getting Started

1. Add Clients: On the main tracking page, scroll down to "Manage Clients" and add your clients
2. Add Projects: In "Manage Projects", select a client and add projects for that client
3. Configure Settings: Visit the Settings page to set your preferred time granularity
4. Track Time:
   • Select a client and project from the dropdowns
   • Click "Clock In" (green button) to start tracking
   • Click "Clock Out" (red button) to stop tracking
5. Export Data: Visit the Export page to generate reports for clients/projects

Real-time Sync

The application automatically syncs your clock-in/clock-out status every 5 seconds. This means:

• If you clock in on your phone, your desktop browser will update automatically
• If you clock out on your computer, your tablet will reflect the change
• No need to refresh the page manually

Email Configuration (Optional)

To enable email export functionality, configure the following environment variables:

MAIL_SERVER=smtp.gmail.com
MAIL_PORT=587
MAIL_USE_TLS=true
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password
MAIL_DEFAULT_SENDER=your-email@gmail.com

Note for Gmail users: You'll need to generate an App Password instead of using your regular password.

Reverse Proxy Configuration

If you're running the application behind a reverse proxy (like nginx) with a URL prefix (e.g., https://yourdomain.com/tt/), you need to set the URL_PREFIX environment variable:

Docker Compose

Add the URL_PREFIX to your environment variables:

environment:
  - URL_PREFIX=/tt

Or set it in your .env file:

URL_PREFIX=/tt

Local Development

Set the environment variable before running the application:

export URL_PREFIX=/tt
python app.py

Nginx Configuration Example

location /tt/ {
    proxy_pass http://localhost:5000/;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Important: The URL_PREFIX should match the path in your reverse proxy configuration. If your app is accessible at https://example.com/timetracker/, set URL_PREFIX=/timetracker.

Docker Commands

# Start the application
docker-compose up -d

# Stop the application
docker-compose down

# View logs
docker-compose logs -f

# Rebuild after changes
docker-compose up -d --build

# Access container shell
docker-compose exec timetracker sh

Data Persistence

When using Docker, your database is stored in the ./data directory on your host machine, which is mounted to /app/instance in the container. This ensures your data persists even if you rebuild or restart the container.

Technology Stack

• Backend: Python 3.11, Flask, SQLAlchemy
• Frontend: HTML5, CSS3, JavaScript (vanilla)
• Database: SQLite
• Email: Flask-Mail
• Deployment: Docker, Gunicorn

License

This project is provided as-is for personal use.

Support

For issues or questions, please create an issue in the repository.