Skip to content

INSTALLATION.md

Latest commit

 

History

History
148 lines (100 loc) · 5.99 KB

INSTALLATION.md

File metadata and controls

148 lines (100 loc) · 5.99 KB
Raw

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:

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:

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.