Getting Started

Set up TimeTrack locally with Docker Compose in under 5 minutes, or use the hosted version at timetracker.cargoffer.com.

Option 1: Use the Hosted Version

The fastest way to try TimeTrack is to sign up at the hosted instance:

1. Visit timetracker.cargoffer.com
2. Sign up with email, Google, or GitHub (via Clerk)
3. Create your first organization
4. Create a project and start a timer

That's it. The hosted version is free for up to 3 users.

Option 2: Self-Host with Docker

Self-hosting requires Docker, Docker Compose, and accounts with Clerk, MongoDB, and Stripe.

Prerequisites

• Docker 20.10+ and Docker Compose v2
• Python 3.12 (for local development)
• A Clerk account (free tier OK)
• MongoDB 7 (local or hosted, e.g. MongoDB Atlas)
• Redis 7 (local or hosted, e.g. Upstash)
• Stripe account (test mode OK for development)

Step 1: Clone the Backend

git clone https://github.com/cargoffer/timetracker_back.git
cd timetracker_back

Step 2: Configure Environment

Copy the example env file and edit it:

cp .env.example .env
nano .env

Required environment variables:

# App
APP_NAME="TimeTrack API"
APP_VERSION="1.0.0"
DEBUG=true
HOST=0.0.0.0
PORT=8017

# CORS
CORS_ORIGINS=*

# Clerk Authentication
CLERK_PUBLISHABLE_KEY=pk_test_xxx
CLERK_SECRET_KEY=sk_test_xxx
CLERK_JWKS_URL=https://your-clerk.clerk.accounts.dev/.well-known/jwks.json

# MongoDB
MONGODB_URL=mongodb://localhost:27017
MONGODB_DB=timetrack

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# Stripe
STRIPE_SECRET_KEY=sk_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
STRIPE_PRICE_ID_MONTHLY=price_xxx
STRIPE_PRICE_ID_YEARLY=price_xxx

# Internal
INTERNAL_TOKEN=generate-a-random-secret-here

Step 3: Start Services

Start MongoDB and Redis (or use hosted versions):

# Local MongoDB + Redis with Docker
docker run -d --name timetrack-mongo -p 27017:27017 mongo:7
docker run -d --name timetrack-redis -p 6379:6379 redis:7-alpine

Start the backend:

pip install -r requirements.txt
uvicorn src.main:app --reload --host 0.0.0.0 --port 8017

Or with Docker:

docker build -t timetrack-api .
docker run -p 8017:8017 --env-file .env timetrack-api

Step 4: Verify Installation

Check the API is running:

curl http://localhost:8017/api/v1/health
# Expected: {"status":"ok","service":"TimeTrack API","version":"1.0.0"}

View interactive docs:

• Swagger UI: http://localhost:8017/api/docs
• ReDoc: http://localhost:8017/api/redoc
• OpenAPI JSON: http://localhost:8017/api/openapi.json

Step 5: Set Up the Frontend

Clone and configure the frontend:

git clone https://github.com/cargoffer/timetracker_front.git
cd timetrack_front
npm install
cp .env.example .env

Edit .env with your Clerk publishable key and API URL:

VITE_API_URL=http://localhost:8017
VITE_CLERK_PUBLISHABLE_KEY=pk_test_xxx

Start the dev server:

npm run dev
# Open http://localhost:3007

Your First API Calls

Once you have a Clerk session, you can call the API with your JWT token:

Get your active timer

curl -H "Authorization: Bearer $CLERK_JWT" \
     https://api.timetracker.cargoffer.com/api/v1/time-entries/active

Start a timer

curl -X POST -H "Authorization: Bearer $CLERK_JWT" \
     -H "Content-Type: application/json" \
     -d '{"project_id": "proj_abc", "description": "Building feature X"}' \
     https://api.timetracker.cargoffer.com/api/v1/time-entries/start

List your projects

curl -H "Authorization: Bearer $CLERK_JWT" \
     https://api.timetracker.cargoffer.com/api/v1/projects

Next Steps

• Read the complete API reference
• Explore integrations with Stripe, MCP, and more
• Browse the source code on GitHub
• Join the community (Discord link coming soon)

Troubleshooting

"MongoDB connection failed"

Check that MongoDB is running and accessible:

mongosh "$MONGODB_URL" --eval "db.runCommand({ping:1})"

If using Docker, ensure the port mapping matches MONGODB_URL.

"Clerk JWT verification failed"

Ensure CLERK_JWKS_URL matches your Clerk instance. The URL format is:

https://<your-clerk-subdomain>.clerk.accounts.dev/.well-known/jwks.json

"Stripe webhook signature verification failed"

Use the Stripe CLI to forward webhooks locally:

stripe listen --forward-to localhost:8017/api/v1/billing/webhook

Copy the webhook signing secret from the CLI output to STRIPE_WEBHOOK_SECRET.