Self-Hosting Traggo with Docker Compose

What Is Traggo?

Traggo is a self-hosted time tracking tool that uses tags instead of rigid project hierarchies. Instead of organizing time into “Project → Task,” you tag entries with arbitrary key-value pairs — project:website, type:coding, client:acme, billable:yes. This lets you slice time data across any dimension. It replaces Clockify, Toggl, and Harvest for personal time tracking, running as a single container with zero external dependencies.

Official site: https://traggo.net

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended) or even a Raspberry Pi
• Docker and Docker Compose installed (guide)
• 128 MB of free RAM (Traggo is extremely lightweight)
• Minimal disk space (~100 MB total)

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  traggo:
    image: traggo/server:v0.8.3
    container_name: traggo
    restart: unless-stopped
    ports:
      - "3030:3030"
    volumes:
      - traggo-data:/opt/traggo/data    # SQLite database and config
    environment:
      TRAGGO_PORT: "3030"                       # Web UI port
      TRAGGO_DEFAULT_USER_NAME: admin            # Default admin username
      TRAGGO_DEFAULT_USER_PASS: change-this-password  # CHANGE THIS — default admin password
      TRAGGO_PASS_STRENGTH: "10"                 # Bcrypt strength (higher = slower hash, more secure)
      TRAGGO_LOG_LEVEL: info                     # debug, info, warn, error, fatal, panic
      TRAGGO_DATABASE_DIALECT: sqlite3           # Only SQLite is supported
      TRAGGO_DATABASE_CONNECTION: /opt/traggo/data/traggo.db  # Database file path

volumes:
  traggo-data:

Start the stack:

docker compose up -d

Traggo starts in under 5 seconds. No database migrations, no setup wizards, no waiting.

Initial Setup

1. Open http://your-server-ip:3030 in your browser
2. Log in with the credentials from your environment variables (admin / your password)
3. Create your first tags — click the tag icon and define key-value pairs:
   • project → values: website, api, docs
   • type → values: coding, meeting, review
   • client → values: acme, globex
4. Start a timer or create a manual time entry, then tag it
5. View time data by tag combinations on the dashboard

Configuration

Tags are the core concept. Unlike traditional time trackers where you pick a project from a dropdown, Traggo lets you create any tag key with any values. This means you can track time by project, client, task type, energy level, or anything else simultaneously.

Example tag structure for a freelancer:

Tag Key	Values
project	website-redesign, mobile-app, maintenance
client	acme-corp, globex, internal
type	coding, design, meeting, admin
billable	yes, no

Dashboards: Create custom dashboards with pie charts, bar charts, and time tables. Each dashboard widget can filter by tag combinations — “show me billable coding time for Acme Corp this month.”

Additional users: Create multiple users from the admin panel. Each user gets their own time entries and dashboard views. There’s no role-based access control — all users have equal access.

Log level: Set TRAGGO_LOG_LEVEL to debug for troubleshooting, info for normal operation.

Reverse Proxy

Traggo serves HTTP on port 3030. Put it behind a reverse proxy for HTTPS:

Setting	Value
Scheme	http
Forward hostname	traggo (container name)
Forward port	3030
Websockets	Not needed

For detailed reverse proxy setup: Reverse Proxy Setup

Backup

Traggo stores everything in a single SQLite database file. Back it up by copying the file:

docker exec traggo cp /opt/traggo/data/traggo.db /opt/traggo/data/traggo-backup-$(date +%Y%m%d).db

Or from the host, copy the file from the named volume:

docker cp traggo:/opt/traggo/data/traggo.db ./traggo-backup-$(date +%Y%m%d).db

For automated backups, add this to a cron job. The database is small — typically under 10 MB even after years of use.

For backup strategies: Backup Strategy

Troubleshooting

Cannot log in with default credentials

Symptom: Login fails with the credentials from environment variables. Fix: The default credentials are only used on first startup when the database is empty. If you changed the environment variables after the first run, the original credentials are still in the database. Either reset the named volume (docker volume rm traggo-data) and restart, or use the GraphQL API to reset the password.

Database locked errors

Symptom: “database is locked” errors in logs during concurrent access. Fix: SQLite doesn’t handle heavy concurrent writes well. For a personal time tracker this rarely matters, but if multiple users are writing simultaneously, you may see occasional lock errors. They resolve automatically — Traggo retries the operation.

Tags not appearing in dashboard

Symptom: Created tags don’t show up in dashboard widget configuration. Fix: Tags must have at least one value defined before they appear in dashboard filters. Click the tag icon, select your tag key, and add at least one value.

Resource Requirements

• RAM: 50–100 MB idle, 100–200 MB under load
• CPU: Very low — negligible even on a Raspberry Pi
• Disk: ~7.5 MB Docker image, ~100 MB with data, database grows slowly

Traggo is one of the lightest self-hosted applications available. The Go binary, SQLite database, and web UI all fit in under 10 MB. It runs comfortably alongside dozens of other services on even the smallest VPS.

Verdict

Traggo is the best self-hosted time tracker for personal use on minimal resources. The tag-based system is genuinely more flexible than project-based trackers — you’re not forced into a hierarchy that doesn’t match your workflow. At 50 MB of RAM in a 7.5 MB image, it’s essentially free to run.

The trade-off is clear: no invoicing, no team management, no exports, no integrations. If you need to bill clients or manage a team, Kimai is the right tool. If you want lightweight personal time tracking with maximum categorization flexibility, Traggo is excellent.

Related

• Kimai vs Traggo
• How to Self-Host Kimai
• Best Self-Hosted Time Tracking Tools
• Self-Hosted Alternatives to Clockify
• Docker Compose Basics
• Backup Strategy
• Reverse Proxy Setup