Deploying TimeTagger

Introduction

TimeTagger is an open-source time tracking application with a clean, intuitive web interface. It allows you to track time spent on projects and tasks using a simple tag-based system. With interactive timeline visualization and detailed reports, TimeTagger helps you understand how you spend your time and improve productivity.

Key features of TimeTagger include:

• Tag-Based Tracking: Organize time entries with flexible tags
• Interactive Timeline: Visual representation of your day, week, or month
• Real-Time Tracking: Start and stop timers with one click
• Manual Entries: Add time entries retroactively
• Detailed Reports: Analyze time spent by tag, project, or period
• Data Export: Export data in various formats
• Multi-User Support: Each user has their own private data
• Mobile Friendly: Responsive design works on all devices
• Self-Hosted Privacy: Your time data stays on your infrastructure
• Simple Setup: Minimal configuration required

This guide walks you through deploying TimeTagger on Klutch.sh, setting up user accounts, and tracking your time effectively.

Why Deploy TimeTagger on Klutch.sh

Deploying TimeTagger on Klutch.sh provides several advantages:

Access Anywhere: Track time from any device, anywhere, without running a local server.

Data Privacy: Self-hosted solution keeps your time data under your control.

Simplified Deployment: Klutch.sh handles container orchestration automatically.

Persistent Storage: Time entries persist reliably across deployments.

HTTPS by Default: Secure access with automatic SSL certificates.

Prerequisites

Before deploying TimeTagger on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker

Preparing Your Repository

Create a GitHub repository with the following structure:

timetagger-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

FROM python:3.11-slim

# Install TimeTagger
RUN pip install --no-cache-dir timetagger

# Create data directory
RUN mkdir -p /data

# Set environment variables
ENV TIMETAGGER_DATADIR=/data
ENV TIMETAGGER_BIND=0.0.0.0:8080

# Credentials (set via environment variables)
ENV TIMETAGGER_CREDENTIALS=${TIMETAGGER_CREDENTIALS}

EXPOSE 8080

# Run TimeTagger
CMD ["python", "-m", "timetagger"]

Environment Variables Reference

Variable	Required	Default	Description
TIMETAGGER_DATADIR	No	~/.timetagger	Directory for data storage
TIMETAGGER_BIND	No	0.0.0.0:8080	Server bind address
TIMETAGGER_CREDENTIALS	Yes	-	User credentials (username:password format)
TIMETAGGER_LOG_LEVEL	No	info	Logging level

Deploying on Klutch.sh

Push Your Repository to GitHub

Commit and push your Dockerfile to GitHub.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “timetagger” or “time-tracking”.

Create the TimeTagger App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

Set the traffic type to HTTP with the internal port set to 8080.

Set Environment Variables

Configure user credentials:

Variable	Value
TIMETAGGER_CREDENTIALS	user1:password1,user2:password2

Multiple users are separated by commas.

Attach Persistent Volumes

Add persistent storage for time data:

Mount Path	Size	Purpose
/data	1 GB	User data and time entries

Deploy Your Application

Click Deploy to build and launch TimeTagger.

Access TimeTagger

Visit https://your-app-name.klutch.sh and log in with your credentials.

Using TimeTagger

Understanding the Interface

TimeTagger features a timeline-based interface:

• Timeline View: Visual representation of time entries
• Tag Panel: Quick access to frequently used tags
• Timer: Start/stop current time tracking
• Reports: Analyze your tracked time

Tracking Time

Start tracking time:

1. Click the timer button to start
2. Add tags to describe your activity
3. Click again to stop when finished

Or add entries manually:

1. Click on the timeline
2. Drag to set duration
3. Add tags to the entry

Using Tags

Tags organize your time entries:

• Use hashtags: #project #client #task
• Combine multiple tags: #projectA #coding #frontend
• Create hierarchies: #work #work/meetings

Tag Examples

Tag Pattern	Use Case
#client-acme	Client-specific work
#dev #frontend	Development category
#meeting #internal	Meeting types
#admin #email	Administrative tasks

Viewing Reports

Analyze your time:

1. Navigate to Reports section
2. Select date range
3. Filter by tags
4. View breakdown by category

Advanced Configuration

Multiple Users

Support multiple users:

TIMETAGGER_CREDENTIALS=alice:secret1,bob:secret2,carol:secret3

Each user has:

• Private time entries
• Separate tag namespace
• Individual reports

Custom Port

Change the default port:

TIMETAGGER_BIND=0.0.0.0:3000

Logging Configuration

Increase logging for debugging:

TIMETAGGER_LOG_LEVEL=debug

Data Management

Exporting Data

Export your time data:

1. Go to Settings
2. Select Export option
3. Choose format (JSON, CSV)
4. Download file

Importing Data

Import from backup:

1. Prepare import file
2. Use import function
3. Verify data integrity

Backup Strategy

Protect your time tracking data:

1. Regular backups of /data volume
2. Export data periodically
3. Store backups securely

Best Practices for Time Tracking

Consistent Tagging

Develop a tagging system:

1. Define standard tags for projects
2. Use consistent naming conventions
3. Create tag hierarchies for organization
4. Document your tagging system

Daily Habits

Build time tracking habits:

• Start timer at beginning of tasks
• Review and clean up at end of day
• Add descriptions for context
• Track breaks and transitions

Weekly Reviews

Analyze your time weekly:

1. Review time distribution
2. Identify time sinks
3. Adjust workflows
4. Set goals for next week

Production Best Practices

Security Recommendations

• Strong Passwords: Use secure passwords for all users
• HTTPS Only: Access only via HTTPS (automatic with Klutch.sh)
• Regular Updates: Keep TimeTagger updated
• Backup Regularly: Protect against data loss

Performance Tips

• TimeTagger is lightweight and efficient
• Minimal resource requirements
• Scales well for personal use
• Consider separate instances for teams

Troubleshooting

Cannot Log In

• Verify credentials in environment variables
• Check username:password format
• Ensure no extra spaces
• Review container logs

Data Not Persisting

• Verify volume mount at /data
• Check volume permissions
• Ensure adequate storage space

Timeline Not Loading

• Check browser JavaScript errors
• Clear browser cache
• Try incognito mode
• Verify server is running

Slow Performance

• Check server resources
• Review data volume size
• Clear old entries if needed

Additional Resources

• TimeTagger Official Website
• TimeTagger GitHub Repository
• TimeTagger Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying TimeTagger on Klutch.sh provides a simple, effective time tracking solution that respects your privacy. With its intuitive interface, flexible tagging system, and insightful reports, TimeTagger helps you understand and optimize how you spend your time. The combination of TimeTagger’s lightweight design and Klutch.sh’s reliable infrastructure ensures your time tracking is always available when you need it.