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

   This starts the app, PostgreSQL, and HTTPS reverse proxy without the optional bundled Ollama LLM (smaller footprint). See With AI helper (optional) below to add Ollama.

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).

With AI helper (optional)

To run the bundled Ollama service and enable the in-app AI helper:

1. In .env, set AI_ENABLED=true and ensure AI_BASE_URL=http://ollama:11434 (and AI_MODEL as desired; default llama3.1 is large on first pull).

2. Start Compose with the ai profile:

   docker compose --profile ai up -d

For a hosted OpenAI-compatible API only (no Ollama containers), set AI_ENABLED=true, AI_PROVIDER=openai_compatible, AI_BASE_URL, and AI_API_KEY in .env, then use plain docker compose up -d.

Details: README.md (AI Helper section) and docs/admin/configuration/DOCKER_COMPOSE_SETUP.md.

To turn off or remove the AI helper (including bundled Ollama and API tokens), see UNINSTALL.md.

With Peppol e-invoicing (optional, self-hosted)

If you want to send invoices over the Peppol network from a self-hosted TimeTracker instance, the recommended setup is:

• Run the included Peppol Bridge service (peppol-bridge) in Docker Compose
• Use the in-app wizard to apply settings and send a test invoice:
  • Admin → System Settings → Peppol → Setup wizard

Docs:

• Peppol e-invoicing setup
• Peppol Bridge (adapter)

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.

Alternative: NAS Install (QNAP / Synology / Portainer)

To run TimeTracker on a NAS without cloning the repository, use the self-contained NAS compose file:

1. Open your NAS Docker UI (QNAP Container Station, Synology Container Manager, or Portainer).
2. Create a new stack/project and paste the contents of docker-compose.nas.yml.
3. Set environment variables:
   • SECRET_KEY (required) — generate with: openssl rand -hex 32
   • TZ, CURRENCY, HTTP_PORT (optional)
4. Deploy the stack and open http://<your-nas-ip>:8080.

Or via SSH (no git clone):

curl -fsSL -o docker-compose.nas.yml \
  https://raw.githubusercontent.com/drytrix/TimeTracker/main/docker-compose.nas.yml
echo "SECRET_KEY=$(openssl rand -hex 32)" > .env
docker compose -f docker-compose.nas.yml up -d

Full guide: NAS Deployment Guide

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
Remove / uninstall	UNINSTALL.md

For more help, see the Documentation Index and Support.