mirror of
https://github.com/DRYTRIX/TimeTracker.git
synced 2026-05-24 15:20:52 -05:00
Dries Peeters
52c7e9f02a
- Honor AI_ENABLED across session AI, REST v1, LLM service, templates, and context; add regression tests for the AI helper gate. - Docker Compose: optional Ollama behind the ai profile; align env.example and example compose with safe defaults. - Add UNINSTALL.md with a dedicated AI teardown section; cross-link from README, INSTALLATION, Getting Started, docs index, and Docker setup guide. - Record 5.5.6 in CHANGELOG and sync version examples in BUILD_CONFIGURATION; bump setup.py to 5.5.6.
114 lines
4.6 KiB
Markdown
114 lines
4.6 KiB
Markdown
# 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).
|
||
|
||
## 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.
|
||
|
||
## 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).
|