TimeTracker/docs/GETTING_STARTED.md

Getting Started with TimeTracker

A complete guide to get you up and running with TimeTracker in minutes.

---

📋 Table of Contents

1. Installation
2. First Login
3. Initial Setup
4. Core Workflows
5. Next Steps

---

🚀 Installation

Option 1: Docker (Recommended)

The fastest way to get TimeTracker running:

# 1. Clone the repository
git clone https://github.com/drytrix/TimeTracker.git
cd TimeTracker

# 2. Set a strong SECRET_KEY (required for sessions & CSRF)
# Linux/macOS:
export SECRET_KEY=$(python -c "import secrets; print(secrets.token_hex(32))")
# Windows PowerShell:
$env:SECRET_KEY = python -c "import secrets; print(secrets.token_hex(32))"

# 3. (Optional) Set admin usernames
# Linux/macOS:
export ADMIN_USERNAMES=admin,manager
# Windows PowerShell:
$env:ADMIN_USERNAMES = "admin,manager"

# 4. Start TimeTracker
docker-compose up -d

# (Optional) Bundled AI helper with Ollama — large first-time model download:
# Set AI_ENABLED=true and AI_BASE_URL=http://ollama:11434 in .env, then:
# docker compose --profile ai up -d

# 5. Access the application
# Open your browser to: https://localhost
# (Self‑signed certificate; your browser will show a warning the first time.)

# Prefer plain HTTP on port 8080 instead?
# Use the example compose that publishes the app directly:
# docker-compose -f docker-compose.example.yml up -d
# Then open: http://localhost:8080

# Note: Login with the username you set in ADMIN_USERNAMES (default: admin) to get admin access

That's it! TimeTracker is now running with PostgreSQL (default install does not start bundled Ollama; see comments above for the optional --profile ai stack).

Important: The default docker-compose.yml expects SECRET_KEY to be set. You can also edit the file and replace SECRET_KEY=your-secret-key-here with a securely generated value. Never use weak or guessable keys.

To remove containers and data, see UNINSTALL.md. To disable or remove only the AI helper (Ollama, env, API tokens), see UNINSTALL.md — AI helper.

Option 2: Quick Test (SQLite)

Want to try it without setting up a database?

# Start with SQLite (no database setup needed)
docker-compose -f docker/docker-compose.local-test.yml up --build

# Access at: http://localhost:8080

Perfect for testing and development!

Option 3: Manual Installation

For advanced users who prefer manual setup:

# 1. Install dependencies
pip install -r requirements.txt

# 2. Configure environment
cp env.example .env
# Edit .env with your settings

# 3. Initialize database
python -c "from app import create_app; app = create_app(); app.app_context().push(); app.initialize_database()"

# 4. Run the application
python app.py

📖 See Requirements for detailed system requirements

---

🔑 First Login

1. Open TimeTracker in your browser: http://localhost:8080

2. Enter your credentials (depends on authentication method configured)

   • Default (AUTH_METHOD=local): Enter username and password. Note: The default admin user has no password set initially. On first login, enter the admin username (e.g. admin) and choose any password (minimum 8 characters). Your password is set and you are logged in.
   • No authentication (AUTH_METHOD=none): Enter username only (no password)
   • OIDC (AUTH_METHOD=oidc): Click "Sign in with SSO" button
   • Both (AUTH_METHOD=both): Choose either SSO or local username/password
   • LDAP (AUTH_METHOD=ldap): Sign in with directory username and password (no SSO button)
   • All methods (AUTH_METHOD=all): SSO button plus username/password (local and/or LDAP, depending on account)

3. Admin users are configured in the environment

   • Set via ADMIN_USERNAMES environment variable (default: admin)
   • When you login with a username matching the list, you get admin role
   • Example: If ADMIN_USERNAMES=admin,manager, logging in as "admin" or "manager" gives admin access
   • Important: Only the first username in the list is automatically created during database initialization. Additional admin usernames must either self-register (if ALLOW_SELF_REGISTER=true) or be created manually by an existing admin user.

4. You're in! Welcome to your dashboard

Note

: Authentication method is configured via the AUTH_METHOD environment variable:

• none: Username only (for trusted internal networks)
• local: Username + password (default, recommended)
• oidc: Single Sign-On only
• ldap: LDAP directory only
• both: OIDC and local password (no LDAP)
• all: Local + OIDC + LDAP

See OIDC Setup Guide and LDAP Setup for details.

---

⚙️ Initial Setup

Guided setup on first run

The first time you open TimeTracker (before setup is complete), you are shown a guided setup wizard at /setup. It walks you through:

• Region & time – Timezone, date/time format, currency
• Company – Company name, address, email (for invoices)
• System – Self-registration, time rounding, single active timer, idle timeout
• Integrations (optional) – Google Calendar OAuth; can be skipped
• Privacy – Opt-in for anonymous telemetry

After you complete the wizard, you can log in and fine-tune anything in Admin → Settings. If setup was already completed (e.g. by someone else), you go straight to the login/dashboard.

Step 1: Configure System Settings (Admin)

Important

: You need admin access for this step. Login with a username from ADMIN_USERNAMES (default: admin).

1. Go to Admin → Settings (in the left sidebar menu, expand "Admin", then click "Settings")

The Admin Settings page has multiple sections. Configure what you need:

General Settings

• Timezone: Your local timezone (e.g., America/New_York, Europe/Rome)
• Currency: Your preferred currency (e.g., USD, EUR, GBP)

Timer Settings

• Rounding (Minutes): Round to nearest 1/5/15 minutes
• Idle Timeout (Minutes): Auto-pause after idle (default: 30)
• Single Active Timer: When enabled (default), a user cannot start another timer until the current running entry is stopped. When disabled, multiple concurrent timers are allowed. The value is stored in the database (System Settings); the SINGLE_ACTIVE_TIMER environment variable only seeds that row on first install—after that, changes in the admin UI apply immediately to web, REST v1, and kiosk timer starts.

User Management

• Allow Self-Registration: ☑ Enable this to let users create accounts by entering any username and password on the login page. When enabled, anyone can create an app user with whatever credentials they type—there is no link to database credentials. Security note: Avoid using your database username (e.g. timetracker) as an app username, and do not share database passwords. With self-register enabled, someone could create an app account with credentials that match your DB user, which can be confusing or a security risk.
• Note: Admin users are set via ADMIN_USERNAMES environment variable, not in this UI

Company Branding

• Company Name: Your company or business name
• Company Email: Contact email for invoices
• Company Phone: Contact phone number
• Company Website: Your website URL
• Company Address: Your billing address (multi-line)
• Tax ID: Optional tax identification number
• Bank Information: Optional bank account details for invoices
• Company Logo: Upload your logo (PNG, JPG, GIF, SVG, WEBP)

Invoice Defaults

• Invoice Prefix: Prefix for invoice numbers (e.g., INV)
• Invoice Start Number: Starting number for invoices (e.g., 1000)
• Default Payment Terms: Terms text (e.g., "Payment due within 30 days")
• Default Invoice Notes: Footer notes (e.g., "Thank you for your business!")

Additional Settings

• Backup Settings: Retention days and backup time
• Export Settings: CSV delimiter preference
• Privacy & Analytics: Allow analytics to help improve the application

2. Click "Save Settings" at the bottom to apply all changes

💡 Tip: Don't confuse this with the Settings option in your account dropdown (top right) - that's for personal/user preferences. System-wide settings are in Admin → Settings in the left sidebar.

Step 2: Add Your First Client

1. Navigate to Clients → Create Client

2. Enter client information:

   • Name: Client or company name (required)
   • Contact Person: Primary contact
   • Email: Client email address
   • Phone: Contact number
   • Address: Billing address

3. Set billing defaults:

   • Default Hourly Rate: Your rate for this client (e.g., 100.00)
   • This will auto-populate when creating projects

4. Click Create to save the client

Step 3: Create Your First Project

1. Go to Projects → Create Project

2. Basic information:

   • Name: Project name (required)
   • Client: Select from dropdown (auto-filled with client info)
   • Description: Brief project description

3. Billing information:

   • Billable: Toggle on if you'll invoice this project
   • Hourly Rate: Auto-filled from client (can override)
   • Estimated Hours: Optional project estimate

4. Advanced settings (optional):

   • Status: Active/Archived
   • Start/End Dates: Project timeline
   • Budget Alert Threshold: Get notified at X% budget used

5. Click Create to save the project

Step 4: Create Tasks (Optional)

Break your project into manageable tasks:

1. Go to Tasks → Create Task

2. Task details:

   • Project: Select your project
   • Name: Task name (e.g., "Design homepage")
   • Description: What needs to be done
   • Priority: Low/Medium/High/Urgent

3. Planning:

   • Estimated Hours: Time estimate for this task
   • Due Date: When it should be completed
   • Assign To: Team member responsible

4. Click Create to save the task

---

🎯 Core Workflows

Time entries feed into Projects and Invoices; use Reports to see time and billing summaries.

Workflow 1: Track Time with Timer

Quick time tracking for active work:

1. On the Dashboard, find the timer section
2. Select a project (and optionally a task)
3. Click Start — the timer begins
4. Work on your task — timer continues even if you close the browser
5. Use Pause to save the segment and resume later, or Stop when finished. Use the −15 / −5 / +5 / +15 buttons to adjust the current session time if needed.

💡 Tip: The timer runs on the server, so it keeps going even if you:

• Close your browser
• Switch devices
• Lose internet connection temporarily

Workflow 2: Manual Time Entry

Add historical or bulk time entries:

1. Go to Timer (sidebar) or use the timer on the Dashboard

2. Choose entry type:

   • Single entry
   • Bulk entry (multiple entries at once)
   • Calendar view (visual entry)

3. Fill in details:

   • Project: Required
   • Task: Optional
   • Start Time: When you started
   • End Time: When you finished
   • Notes: What you worked on
   • Tags: Categorize your work (e.g., design, meeting, bugfix)

4. Click Save to record the entry

Workflow 3: Generate an Invoice

Turn tracked time into a professional invoice:

1. Go to Invoices → Create Invoice

2. Select project and fill in client details

   • Client info auto-populated from project

3. Set invoice details:

   • Issue Date: Today (default)
   • Due Date: Payment deadline (e.g., 30 days)
   • Tax Rate: Your tax rate (e.g., 21.00 for 21%)

4. Click "Generate from Time Entries":

   • Select time entries to bill
   • Choose grouping (by task or project)
   • Preview the total

5. Review and customize:

   • Edit descriptions
   • Add manual line items
   • Adjust quantities or rates

6. Save and send:

   • Status: Draft → Sent → Paid
   • Export as CSV
   • Export as PDF (and optional ZUGFeRD)

Workflow 4: View Reports

Analyze your time and productivity:

1. Go to Reports

2. Choose report type:

   • Project Report: Time breakdown by project
   • User Report: Individual productivity
   • Summary Report: Overall statistics

3. Set filters:

   • Date Range: Today/This Week/This Month/Custom
   • Project: Specific project or all
   • User: Specific user or all
   • Billable: Billable only/Non-billable only/Both

4. View insights:

   • Total hours worked
   • Billable vs non-billable
   • Time distribution
   • Estimated costs

5. Export data:

   • Click Export CSV for spreadsheet analysis
   • Choose delimiter (comma, semicolon, tab)

---

🎓 Next Steps

Learn Advanced Features

• Task Management — Master task boards and workflows
• Calendar View — Visual time entry and planning
• Command Palette — Keyboard shortcuts for power users
• Bulk Operations — Batch time entry creation

Customize Your Experience

• Company branding: Upload your logo and set company info in Admin → Settings
• Configure notifications for task due dates
• Set up recurring time blocks for regular tasks
• Create saved filters for common report views
• Add custom tags for better categorization

Team Setup

If you're setting up for a team:

1. Add team members:

   • Self-registration (recommended): Enable in Admin → Settings → "Allow Self-Registration"
   • Admin creates users: Go to Admin → Users → Create User
   • Admin roles: Set via ADMIN_USERNAMES environment variable (comma-separated list)
   • Regular users can be assigned Manager or User roles via Admin → Users → Edit

2. Assign projects:

   • Projects are visible to all users
   • Use project permissions (e.g. view_projects, create_projects, edit_projects) to control access

3. Assign tasks:

   • Create tasks and assign to team members
   • Set priorities and due dates
   • Track progress in task board

4. Review reports:

   • See team productivity
   • Identify bottlenecks
   • Optimize resource allocation

Production Deployment

Ready to deploy for real use?

1. Use PostgreSQL instead of SQLite:

   # Edit .env file
   DATABASE_URL=postgresql://user:pass@localhost:5432/timetracker
   

2. Set a secure secret key and admin users:

   # Generate a random key
   SECRET_KEY=$(python -c 'import secrets; print(secrets.token_hex(32))')
   
   # Set admin usernames (comma-separated)
   ADMIN_USERNAMES=admin,yourusername
   

3. Configure for production:

   FLASK_ENV=production
   FLASK_DEBUG=false
   SESSION_COOKIE_SECURE=true
   REMEMBER_COOKIE_SECURE=true
   

4. Set up backups:

   • Configure automatic database backups
   • Store backups off-site
   • Test restore procedures

5. Optional: Add reverse proxy:

   • Use Caddy or nginx for HTTPS
   • Add authentication layer if needed
   • Configure firewall rules

📖 See Docker Public Setup for production deployment

---

💡 Tips & Tricks

Keyboard Shortcuts

Press Ctrl+K (or Cmd+K on Mac) to open the command palette:

• Quickly start/stop timers
• Navigate to any page
• Search projects and tasks
• Log time entries

Mobile Access

TimeTracker is fully responsive:

• Access from any device
• Mobile-optimized interface
• Touch-friendly controls
• Works in any browser

Time Entry Best Practices

1. Add descriptive notes — Future you will thank you
2. Use consistent tags — Makes reporting easier
3. Track regularly — Don't let entries pile up
4. Review weekly — Catch missing time or errors
5. Categorize accurately — Billable vs non-billable matters

Project Management Tips

1. Set realistic estimates — Helps with planning
2. Break into tasks — Makes tracking easier
3. Use task priorities — Focus on what matters
4. Review progress regularly — Stay on track
5. Archive completed projects — Keep your list clean

---

❓ Common Questions

What is the default admin password?

There is no default password. The default admin user (from ADMIN_USERNAMES, typically admin) is created without a password. On first login with AUTH_METHOD=local, enter the admin username and choose any password (minimum 8 characters). Your password is set and you are logged in.

How do I reset my database?

# ⚠️ This deletes all data
docker-compose down -v
docker-compose up -d

How do I add more users?

• Enable self-registration: In Admin → Settings, enable "Allow Self-Registration" - then anyone can create an account by entering a username on the login page
• Admin creates users: In Admin → Users → Create User (requires admin access)
• Users in ADMIN_USERNAMES: Any username listed in the ADMIN_USERNAMES environment variable will automatically get admin role when they login

Can I export my data?

Yes! Multiple export options:

• CSV export from reports
• Database backup via scripts
• REST API v1 for custom integrations (see REST API)

How do I upgrade TimeTracker?

# Pull latest changes
git pull origin main

# Rebuild and restart
docker-compose up -d --build

# Migrations run automatically

Is there a mobile app?

TimeTracker is a web application that works great on mobile browsers. A Progressive Web App (PWA) version with offline support is planned.

---

🆘 Need Help?

• Documentation — Complete documentation index
• Troubleshooting — Fix common issues
• GitHub Issues — Report bugs or request features
• Contributing — Help improve TimeTracker

---

Ready to track your time like a pro? 🚀

← Back to Main README | View All Documentation