# TimeTracker Installation

This guide walks you through installing and running TimeTracker. For a quick overview, see the [README Quick Start](README.md#-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](https://docs.docker.com/get-docker/).

## Quick Install (Docker with HTTPS)

1. Clone the repository:

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

2. Create your environment file from the template:

   ```bash
   cp env.example .env
   ```

3. Edit `.env` and set at least:
   - **SECRET_KEY** — Required for sessions and CSRF. Generate one:
     ```bash
     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:
     ```bash
     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:

   ```bash
   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**:

   ```bash
   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](README.md) (AI Helper section) and [docs/admin/configuration/DOCKER_COMPOSE_SETUP.md](docs/admin/configuration/DOCKER_COMPOSE_SETUP.md).

To **turn off or remove** the AI helper (including bundled Ollama and API tokens), see [UNINSTALL.md](UNINSTALL.md#disabling-or-removing-the-ai-helper).

## 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](docs/admin/configuration/PEPPOL_EINVOICING.md)
- [Peppol Bridge (adapter)](docs/admin/configuration/PEPPOL_BRIDGE.md)

## 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](docs/GETTING_STARTED.md) for initial setup and core workflows.

## Alternative: SQLite Quick Test

To try TimeTracker without PostgreSQL:

```bash
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`](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):

```bash
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](docs/admin/deployment/NAS_DEPLOYMENT.md)

## 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](docs/admin/configuration/DOCKER_COMPOSE_SETUP.md) — Full configuration and env reference
- [Docker Public Setup](docs/admin/configuration/DOCKER_PUBLIC_SETUP.md) — Production deployment with published images

## Troubleshooting

| Problem | Documentation |
|--------|----------------|
| Docker won’t start | [Docker Startup Troubleshooting](docs/admin/configuration/DOCKER_STARTUP_TROUBLESHOOTING.md) |
| Database connection errors | [Database Connection Troubleshooting](docker/TROUBLESHOOTING_DB_CONNECTION.md) |
| CSRF or session errors | [CSRF Troubleshooting](docs/admin/security/CSRF_TROUBLESHOOTING.md) |
| Port already in use | Change ports in your `docker-compose` file or stop the conflicting service |
| Remove / uninstall | [UNINSTALL.md](UNINSTALL.md) |

For more help, see the [Documentation Index](docs/README.md) and [Support](README.md#-support).