mirror of
https://github.com/DRYTRIX/TimeTracker.git
synced 2025-12-19 01:40:04 -06:00
29f7186ee8
Complete reorganization of project documentation to improve discoverability, navigation, and maintainability. All documentation has been restructured into a clear, role-based hierarchy. ## Major Changes ### New Directory Structure - Created `docs/api/` for API documentation - Created `docs/admin/` with subdirectories: - `admin/configuration/` - Configuration guides - `admin/deployment/` - Deployment guides - `admin/security/` - Security documentation - `admin/monitoring/` - Monitoring and analytics - Created `docs/development/` for developer documentation - Created `docs/guides/` for user-facing guides - Created `docs/reports/` for analysis reports and summaries - Created `docs/changelog/` for detailed changelog entries (ready for future use) ### File Organization #### Moved from Root Directory (40+ files) - Implementation notes → `docs/implementation-notes/` - Test reports → `docs/testing/` - Analysis reports → `docs/reports/` - User guides → `docs/guides/` #### Reorganized within docs/ - API documentation → `docs/api/` - Administrator documentation → `docs/admin/` (with subdirectories) - Developer documentation → `docs/development/` - Security documentation → `docs/admin/security/` - Telemetry documentation → `docs/admin/monitoring/` ### Documentation Updates #### docs/README.md - Complete rewrite with improved navigation - Added visual documentation map - Organized by role (Users, Administrators, Developers) - Better categorization and quick links - Updated all internal links to new structure #### README.md (root) - Updated all documentation links to reflect new structure - Fixed 8 broken links #### app/templates/main/help.html - Enhanced "Where can I get additional help?" section - Added links to new documentation structure - Added documentation index link - Added admin documentation link for administrators - Improved footer with organized documentation links - Added "Complete Documentation" section with role-based links ### New Index Files - Created README.md files for all new directories: - `docs/api/README.md` - `docs/guides/README.md` - `docs/reports/README.md` - `docs/development/README.md` - `docs/admin/README.md` ### Cleanup - Removed empty `docs/security/` directory (moved to `admin/security/`) - Removed empty `docs/telemetry/` directory (moved to `admin/monitoring/`) - Root directory now only contains: README.md, CHANGELOG.md, LICENSE ## Results **Before:** - 45+ markdown files cluttering root directory - Documentation scattered across root and docs/ - Difficult to find relevant documentation - No clear organization structure **After:** - 3 files in root directory (README, CHANGELOG, LICENSE) - Clear directory structure organized by purpose and audience - Easy navigation with role-based organization - All documentation properly categorized - Improved discoverability ## Benefits 1. Better Organization - Documentation grouped by purpose and audience 2. Easier Navigation - Role-based sections (Users, Admins, Developers) 3. Improved Discoverability - Clear structure with README files in each directory 4. Cleaner Root - Only essential files at project root 5. Maintainability - Easier to add and organize new documentation ## Files Changed - 40+ files moved from root to appropriate docs/ subdirectories - 15+ files reorganized within docs/ - 3 major documentation files updated (docs/README.md, README.md, help.html) - 5 new README index files created - 2 empty directories removed All internal links have been updated to reflect the new structure.
175 lines
7.4 KiB
Markdown
175 lines
7.4 KiB
Markdown
## Docker Compose Setup Guide
|
||
|
||
This guide shows how to configure TimeTracker with Docker Compose, including all environment variables, a production-friendly example compose file, and quick-start commands.
|
||
|
||
### Prerequisites
|
||
- Docker and Docker Compose installed
|
||
- A `.env` file in the project root
|
||
|
||
### 1) Create and configure your .env file
|
||
|
||
Start from the example and edit values:
|
||
|
||
```bash
|
||
cp env.example .env
|
||
```
|
||
|
||
Required for production:
|
||
- SECRET_KEY: Generate a strong key: `python -c "import secrets; print(secrets.token_hex(32))"`
|
||
- TZ: Set your local timezone (preferred over UTC) to ensure correct timestamps based on your locale [[memory:7499916]].
|
||
|
||
Recommended defaults (safe to keep initially):
|
||
- POSTGRES_DB=timetracker
|
||
- POSTGRES_USER=timetracker
|
||
- POSTGRES_PASSWORD=timetracker
|
||
|
||
If you use the bundled PostgreSQL container, leave `DATABASE_URL` as:
|
||
`postgresql+psycopg2://timetracker:timetracker@db:5432/timetracker`
|
||
|
||
### 2) Use the example compose file
|
||
|
||
We provide `docker-compose.example.yml` with sane defaults using the published image `ghcr.io/drytrix/timetracker:latest` [[memory:7499921]]. Copy it as your working compose file or run it directly:
|
||
|
||
```bash
|
||
# Option A: Use example directly
|
||
docker-compose -f docker-compose.example.yml up -d
|
||
|
||
# Option B: Make it your default compose
|
||
cp docker-compose.example.yml docker-compose.yml
|
||
docker-compose up -d
|
||
```
|
||
|
||
Access the app at `http://localhost:8080`.
|
||
|
||
For a full stack with HTTPS reverse proxy and monitoring, see the root `docker-compose.yml` and the Monitoring section below.
|
||
|
||
### 3) Verify
|
||
```bash
|
||
docker-compose ps
|
||
docker-compose logs app --tail=100
|
||
```
|
||
|
||
### 4) Optional services
|
||
- Reverse proxy (HTTPS): See `docker-compose.yml` (services `certgen` and `nginx`).
|
||
- Monitoring stack: Prometheus, Grafana, Loki, Promtail are available in `docker-compose.yml`.
|
||
|
||
---
|
||
|
||
## Environment Variables Reference
|
||
|
||
All environment variables can be provided via `.env` and are consumed by the `app` container unless otherwise noted. Defaults shown are the effective values if not overridden.
|
||
|
||
### Core
|
||
- SECRET_KEY: Secret used for sessions/CSRF. Required in production. No default.
|
||
- FLASK_ENV: Flask environment. Default: `production`.
|
||
- FLASK_DEBUG: Enable debug. Default: `false`.
|
||
- TZ: Local timezone (e.g., `Europe/Brussels`). Default: `Europe/Rome` in env.example; compose defaults may override.
|
||
|
||
### Database
|
||
- DATABASE_URL: SQLAlchemy URL. Default: `postgresql+psycopg2://timetracker:timetracker@db:5432/timetracker`.
|
||
- POSTGRES_DB: Database name (db service). Default: `timetracker`.
|
||
- POSTGRES_USER: Database user (db service). Default: `timetracker`.
|
||
- POSTGRES_PASSWORD: Database password (db service). Default: `timetracker`.
|
||
- POSTGRES_HOST: Hostname for external DB (not needed with bundled db). Default: `db`.
|
||
|
||
### Application behavior
|
||
- CURRENCY: ISO currency code. Default: `EUR`.
|
||
- ROUNDING_MINUTES: Rounding step for entries. Default: `1`.
|
||
- SINGLE_ACTIVE_TIMER: Allow only one active timer per user. Default: `true`.
|
||
- IDLE_TIMEOUT_MINUTES: Auto-pause after idle. Default: `30`.
|
||
- ALLOW_SELF_REGISTER: Allow new users to self-register. Default: `true`.
|
||
- ADMIN_USERNAMES: Comma-separated admin usernames. Default: `admin`.
|
||
|
||
### Authentication
|
||
|
||
- **AUTH_METHOD**: Controls authentication method. Options:
|
||
- `none`: No password authentication (username only). Use only in trusted environments.
|
||
- `local`: Password authentication required (default). Users must set and use passwords.
|
||
- `oidc`: OIDC/Single Sign-On only. Local login form is hidden.
|
||
- `both`: OIDC + local password authentication. Users can choose either method.
|
||
|
||
Default: `local`. See [OIDC Setup Guide](OIDC_SETUP.md) for detailed explanations.
|
||
- OIDC_ISSUER: OIDC provider issuer URL.
|
||
- OIDC_CLIENT_ID: OIDC client id.
|
||
- OIDC_CLIENT_SECRET: OIDC client secret.
|
||
- OIDC_REDIRECT_URI: App redirect URI for OIDC callback.
|
||
- OIDC_SCOPES: Space-separated scopes. Default: `openid profile email`.
|
||
- OIDC_USERNAME_CLAIM: Default: `preferred_username`.
|
||
- OIDC_FULL_NAME_CLAIM: Default: `name`.
|
||
- OIDC_EMAIL_CLAIM: Default: `email`.
|
||
- OIDC_GROUPS_CLAIM: Default: `groups`.
|
||
- OIDC_ADMIN_GROUP: Optional admin group name.
|
||
- OIDC_ADMIN_EMAILS: Optional comma-separated admin emails.
|
||
- OIDC_POST_LOGOUT_REDIRECT_URI: Optional RP-initiated logout return URI.
|
||
|
||
### CSRF and Cookies
|
||
- WTF_CSRF_ENABLED: Enable CSRF protection. Default: `true` (example) or `false` in dev.
|
||
- WTF_CSRF_TIME_LIMIT: Token lifetime (seconds). Default: `3600`.
|
||
- WTF_CSRF_SSL_STRICT: Require HTTPS for CSRF referer checks. Default: `true` for production via compose; set `false` for HTTP.
|
||
- WTF_CSRF_TRUSTED_ORIGINS: Comma-separated allowed origins (scheme://host). Default: `https://localhost`.
|
||
- PREFERRED_URL_SCHEME: `http` or `https`. Default: `https` in production setups; set `http` for local.
|
||
- SESSION_COOKIE_SECURE: Send cookies only over HTTPS. Default: `true` (prod) / `false` (local test).
|
||
- SESSION_COOKIE_HTTPONLY: Default: `true`.
|
||
- SESSION_COOKIE_SAMESITE: `Lax` | `Strict` | `None`. Default: `Lax`.
|
||
- REMEMBER_COOKIE_SECURE: Default: `true` (prod) / `false` (local test).
|
||
- CSRF_COOKIE_SECURE: Default: `true` (prod) / `false` (local test).
|
||
- CSRF_COOKIE_HTTPONLY: Default: `false`.
|
||
- CSRF_COOKIE_SAMESITE: Default: `Lax`.
|
||
- CSRF_COOKIE_NAME: Default: `XSRF-TOKEN`.
|
||
- CSRF_COOKIE_DOMAIN: Optional cookie domain for subdomains (unset by default).
|
||
- PERMANENT_SESSION_LIFETIME: Session lifetime seconds. Default: `86400`.
|
||
|
||
### File uploads and backups
|
||
- MAX_CONTENT_LENGTH: Max upload size in bytes. Default: `16777216` (16MB).
|
||
- UPLOAD_FOLDER: Upload path inside container. Default: `/data/uploads`.
|
||
- BACKUP_RETENTION_DAYS: Retain DB backups (if enabled). Default: `30`.
|
||
- BACKUP_TIME: Backup time (HH:MM). Default: `02:00`.
|
||
|
||
### Logging
|
||
- LOG_LEVEL: Default: `INFO`.
|
||
- LOG_FILE: Default: `/data/logs/timetracker.log` or `/app/logs/timetracker.log` based on compose.
|
||
|
||
### Analytics & Telemetry (optional)
|
||
- SENTRY_DSN: Sentry DSN (empty by default).
|
||
- SENTRY_TRACES_RATE: 0.0–1.0 sampling rate. Default: `0.0`.
|
||
- POSTHOG_API_KEY: PostHog API key (empty by default).
|
||
- POSTHOG_HOST: PostHog host. Default: `https://app.posthog.com`.
|
||
- ENABLE_TELEMETRY: Anonymous install telemetry toggle. Default: `false`.
|
||
- TELE_SALT: Unique salt for anonymous fingerprinting (optional).
|
||
- APP_VERSION: Optional override; usually auto-detected.
|
||
|
||
### Reverse proxy & monitoring (compose-only variables)
|
||
- HOST_IP: Used by `certgen` (in `docker-compose.remote.yml`) to embed SANs in self-signed certs. Default: `192.168.1.100`.
|
||
- Grafana variables (service `grafana` in `docker-compose.yml`):
|
||
- GF_SECURITY_ADMIN_PASSWORD: Default: `admin` (set your own in prod).
|
||
- GF_USERS_ALLOW_SIGN_UP: Default: `false`.
|
||
- GF_SERVER_ROOT_URL: Default: `http://localhost:3000`.
|
||
|
||
---
|
||
|
||
## Monitoring stack (optional)
|
||
|
||
The root `docker-compose.yml` includes Prometheus, Grafana, Loki and Promtail. Start them together with the app:
|
||
|
||
```bash
|
||
docker-compose up -d # uses the root compose with monitoring
|
||
```
|
||
|
||
Open:
|
||
- App: `http://localhost` (or `https://localhost` if certificates are present)
|
||
- Grafana: `http://localhost:3000`
|
||
- Prometheus: `http://localhost:9090`
|
||
- Loki: `http://localhost:3100`
|
||
|
||
For CSRF and cookie issues behind proxies, see `docs/CSRF_CONFIGURATION.md`.
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
- CSRF token errors: Ensure `SECRET_KEY` is stable and set correct CSRF/cookie flags for HTTP vs HTTPS.
|
||
- Database connection: Confirm `db` service is healthy and `DATABASE_URL` points to it.
|
||
- Timezone issues: Set `TZ` to your local timezone [[memory:7499916]].
|
||
|
||
|