TimeTracker/INSTALLATION.md

TimeTracker Installation

This guide walks you through installing and running TimeTracker. For a quick overview, see the README Quick Start.

Prerequisites

• Docker 20.10+ and Docker Compose 2.0+
• Git
• 2GB+ RAM for Docker containers
• Ports: 80/443 (HTTPS) or 8080 (HTTP)

Install Docker for your platform: Docker Installation Guide.

Quick Install (Docker with HTTPS)

1. Clone the repository:

   git clone https://github.com/drytrix/TimeTracker.git
   cd TimeTracker
   

2. Create your environment file from the template:

   cp env.example .env
   

3. Edit .env and set at least:

   • SECRET_KEY — Required for sessions and CSRF. Generate one:

     python -c "import secrets; print(secrets.token_hex(32))"
     

   • SETTINGS_ENCRYPTION_KEY — Recommended to encrypt stored secrets (SMTP password, OAuth client secrets, Peppol token, AI key, and 2FA secrets). Generate one:

     python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
     

   • TZ — Your timezone (e.g. America/New_York, Europe/Brussels).
   • CURRENCY — Default currency (e.g. USD, EUR).

4. Start the stack:

   docker compose up -d
   

5. Open https://localhost in your browser. The first run may show a self-signed certificate warning; proceed to continue.

The first user who logs in is created as an admin (or use ADMIN_USERNAMES in .env to predefine admin usernames).

First Login and Minimal Config

• Log in with the username you configured (e.g. from ADMIN_USERNAMES) or the first account you create.
• In Admin → Settings you can adjust timezone, currency, and other options.
• See Getting Started for initial setup and core workflows.

Alternative: SQLite Quick Test

To try TimeTracker without PostgreSQL:

git clone https://github.com/drytrix/TimeTracker.git
cd TimeTracker
docker-compose -f docker/docker-compose.local-test.yml up --build

Then open http://localhost:8080. No .env is required for this compose file. SQLite is for evaluation only; use PostgreSQL for production.

Production Deployment

For production:

• Use a strong SECRET_KEY and keep .env out of version control.
• Prefer PostgreSQL (included in the default Docker Compose setup).
• Put the app behind HTTPS (reverse proxy or Docker with HTTPS compose).

Note: The default docker-compose.yml requires SECRET_KEY to be set (32+ chars). If it is missing, docker compose will error during interpolation.

Detailed steps and options:

• Docker Compose Setup — Full configuration and env reference
• Docker Public Setup — Production deployment with published images

Troubleshooting

Problem	Documentation
Docker won’t start	Docker Startup Troubleshooting
Database connection errors	Database Connection Troubleshooting
CSRF or session errors	CSRF Troubleshooting
Port already in use	Change ports in your docker-compose file or stop the conflicting service

For more help, see the Documentation Index and Support.