diff --git a/wiki/Install-Docker-Compose.md b/wiki/Install-Docker-Compose.md index 16b72821..c12806ac 100644 --- a/wiki/Install-Docker-Compose.md +++ b/wiki/Install-Docker-Compose.md @@ -4,63 +4,7 @@ Production-ready setup using Docker Compose with security hardening enabled. ## Compose File -Create a `docker-compose.yml` with the following content (taken directly from the repository): - -```yaml -services: - app: - image: mauriceboe/trek:latest - container_name: trek - read_only: true - security_opt: - - no-new-privileges:true - cap_drop: - - ALL - cap_add: - - CHOWN - - SETUID - - SETGID - tmpfs: - - /tmp:noexec,nosuid,size=64m - ports: - - "3000:3000" - environment: - - NODE_ENV=production - - PORT=3000 - - ENCRYPTION_KEY=${ENCRYPTION_KEY:-} # Recommended. Generate with: openssl rand -hex 32. If unset, falls back to data/.jwt_secret (existing installs) or auto-generates a key (fresh installs). - - TZ=${TZ:-UTC} # Timezone for logs, reminders and scheduled tasks (e.g. Europe/Berlin) - - LOG_LEVEL=${LOG_LEVEL:-info} # info = concise user actions; debug = verbose admin-level details -# - DEFAULT_LANGUAGE=en # Default language on the login page for users with no saved preference. Browser/OS language is auto-detected first; this is the fallback. Supported: de, en, es, fr, hu, nl, br, cs, pl, ru, zh, zh-TW, it, ar - - ALLOWED_ORIGINS=${ALLOWED_ORIGINS:-} # Comma-separated origins for CORS and email notification links -# - FORCE_HTTPS=true # Optional. Enables HTTPS redirect, HSTS, CSP upgrade-insecure-requests, and secure cookies behind a TLS proxy -# - COOKIE_SECURE=false # Escape hatch: force session cookies over plain HTTP even in production. Not recommended. -# - TRUST_PROXY=1 # Trusted proxy count for X-Forwarded-For / X-Forwarded-Proto. Required for FORCE_HTTPS to work. -# - ALLOW_INTERNAL_NETWORK=false # Set to true if Immich or other services are hosted on your local network (RFC-1918 IPs). Loopback and link-local addresses remain blocked regardless. -# - APP_URL=https://trek.example.com # Public base URL — required when OIDC is enabled (must match the redirect URI registered with your IdP); also used as base URL for links in email notifications -# - OIDC_ISSUER=https://auth.example.com # OpenID Connect provider URL -# - OIDC_CLIENT_ID=trek # OpenID Connect client ID -# - OIDC_CLIENT_SECRET=supersecret # OpenID Connect client secret -# - OIDC_DISPLAY_NAME=SSO # Label shown on the SSO login button -# - OIDC_ONLY=false # Set true to force SSO-only mode: disables password login and registration, overrides Admin > Settings toggles, cannot be changed at runtime -# - OIDC_ADMIN_CLAIM=groups # OIDC claim used to identify admin users -# - OIDC_ADMIN_VALUE=app-trek-admins # Value of the OIDC claim that grants admin role -# - OIDC_SCOPE=openid email profile # Fully overrides the default. Add extra scopes as needed (e.g. add groups if using OIDC_ADMIN_CLAIM) -# - OIDC_DISCOVERY_URL= # Override the OIDC discovery endpoint for providers with non-standard paths (e.g. Authentik) -# - ADMIN_EMAIL=admin@trek.local # Initial admin e-mail — only used on first boot when no users exist -# - ADMIN_PASSWORD=changeme # Initial admin password — only used on first boot when no users exist -# - MCP_RATE_LIMIT=300 # Max MCP API requests per user per minute (default: 300) -# - MCP_MAX_SESSION_PER_USER=20 # Max concurrent MCP sessions per user (default: 20) - volumes: - - ./data:/app/data - - ./uploads:/app/uploads - restart: unless-stopped - healthcheck: - test: ["CMD", "wget", "-qO-", "http://localhost:3000/api/health"] - interval: 30s - timeout: 10s - retries: 3 - start_period: 15s -``` +See https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml ## Security Hardening Explained @@ -81,6 +25,25 @@ The compose file ships with several hardening options enabled by default: | `./data` | `/app/data` | SQLite database, logs, `.jwt_secret`, `.encryption_key` | | `./uploads` | `/app/uploads` | Uploaded files (photos, documents, covers, avatars) | +### Named Volumes + +The compose file above uses bind mounts (`./data`, `./uploads`). You can switch to Docker named volumes, which are fully managed by Docker and not tied to a specific host path. See the [Docker Compose volumes reference](https://docs.docker.com/reference/compose-file/volumes/) for all options. + +```yaml +services: + app: + # ... (rest of service config unchanged) + volumes: + - trek_data:/app/data + - trek_uploads:/app/uploads + +volumes: + trek_data: + trek_uploads: +``` + +Docker creates the volumes automatically on first `docker compose up`. Use `docker volume ls` and `docker volume inspect` to manage them. + ## Environment Variables The compose file reads variables from a `.env` file placed alongside `docker-compose.yml`. At minimum, set: @@ -95,6 +58,23 @@ APP_URL=https://trek.example.com Uncomment and fill in the OIDC, initial setup, or MCP variables as needed. For a full description of every variable, see [Environment-Variables](Environment-Variables). +## Image Tags + +Three tag strategies are available: + +| Tag | Example | Behavior | +|---|---|---| +| `latest` | `mauriceboe/trek:latest` | Always the newest release across all major versions | +| Major version | `mauriceboe/trek:3` | Latest release pinned to that major version | +| Full version | `mauriceboe/trek:3.0.15` | Exact release; never changes | + +The compose file above uses `latest`. To pin, change the `image:` line: + +```yaml +image: mauriceboe/trek:3 # track major version 3 +image: mauriceboe/trek:3.0.15 # pin to exact release +``` + ## Start TREK ```bash diff --git a/wiki/Install-Docker.md b/wiki/Install-Docker.md index 62ddbf8d..6443ebc4 100644 --- a/wiki/Install-Docker.md +++ b/wiki/Install-Docker.md @@ -34,6 +34,16 @@ Pass additional `-e` flags for timezone and CORS/email link support: See [Environment-Variables](Environment-Variables) for the full list. +## Image Tags + +| Tag | Example | Behavior | +|---|---|---| +| `latest` | `mauriceboe/trek:latest` | Always the newest release across all major versions | +| Major version | `mauriceboe/trek:3` | Latest release pinned to that major version | +| Full version | `mauriceboe/trek:3.0.15` | Exact release; never changes | + +Replace `mauriceboe/trek:latest` in the run command with your chosen tag to pin to a major version or exact release. + ## Volume Reference | Volume | Container path | What lives there | @@ -43,6 +53,23 @@ See [Environment-Variables](Environment-Variables) for the full list. Both volumes must survive container replacement — they are your persistent state. Never remove them before pulling a new image. +### Named Volumes + +The run command above uses bind mounts (`./data`, `./uploads`). You can use Docker named volumes instead, which are fully managed by Docker and not tied to a host path: + +```bash +docker run -d \ + --name trek \ + -p 3000:3000 \ + -v trek_data:/app/data \ + -v trek_uploads:/app/uploads \ + -e ENCRYPTION_KEY= \ + --restart unless-stopped \ + mauriceboe/trek:latest +``` + +Docker creates `trek_data` and `trek_uploads` automatically on first run. Named volumes are easier to manage with `docker volume` commands and work better in some NAS or container-management environments. + ## Health Check The container exposes a health endpoint at: diff --git a/wiki/Install-Portainer.md b/wiki/Install-Portainer.md new file mode 100644 index 00000000..d9c555e0 --- /dev/null +++ b/wiki/Install-Portainer.md @@ -0,0 +1,99 @@ +# Install: Portainer + +Install TREK on Portainer using a Stack (Docker Compose). + +## Prerequisite + +Portainer must be installed and connected to your Docker environment. Use **Stacks** — it supports Docker Compose and gives you the full compose syntax including environment variables, volumes, and restart policies. + +## Create a Stack + +![Stacks page with arrows pointing to the Stacks menu item and the Add stack button](assets/portainer-add-stack.png) + +1. In Portainer, go to **Stacks → Add stack**. +2. Give the stack a name (e.g. `trek`). +3. Select **Web editor** and paste the compose file from [docker-compose.yml](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml). + +![Web editor with the docker-compose content pasted in](assets/portainer-stack-save.png) + +4. Fill in the environment variables at the bottom of the page. + +![Environment variables section with key/value fields filled in](assets/portainer-environment-variable.png) + +5. Click **Deploy the stack**. + +![Deploy the stack button highlighted](assets/portainer-deploy-stack.png) + +## Compose Content + +See https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml + +Set at minimum `ENCRYPTION_KEY`, `TZ`, and `APP_URL` in the **Environment variables** section of the stack editor. Generate an encryption key with: + +```bash +openssl rand -hex 32 +``` + +## Image Tags + +Three tag strategies are available: + +| Tag | Example | Behavior | +|---|---|---| +| `latest` | `mauriceboe/trek:latest` | Always the newest release across all major versions | +| Major version | `mauriceboe/trek:3` | Latest release pinned to that major version | +| Full version | `mauriceboe/trek:3.0.15` | Exact release; never changes | + +Use `latest` or a major-version tag (e.g. `3`) if you want automatic updates on redeploy. Use a full version tag (e.g. `3.0.15`) if you want explicit control over which release runs. + +## Updating + +How you update depends on the tag you chose: + +**`latest` or major-version tag** — In Portainer, open the stack, click **Redeploy**, enable the **Re-pull image and redeploy** switch, then confirm. Portainer will pull the newest matching image and recreate the container. + +![Re-pull image and redeploy switch ticked, with arrows pointing to the switch and the Update button](assets/portainer-force-pull.png) + +**Pinned full-version tag** — Edit the stack, change the tag in the `image:` line (e.g. `3.0.15` → `3.0.16`), then click **Update the stack**. No need to toggle the re-pull switch — a tag change forces a fresh pull. + +![Edit stack page with an arrow pointing to the image tag in the compose editor](assets/portainer-update-version.png) + +![Edit stack page with an arrow pointing to the Update the stack button](assets/portainer-update-stack.png) + +> Back up your data before any update. Go to **Admin Panel → Backups** or copy your `./data` and `./uploads` directories. See [Backups](Backups). + +## Volumes + +| Stack-relative path | Container path | Contents | +|---|---|---| +| `./data` | `/app/data` | SQLite database, logs, encryption key | +| `./uploads` | `/app/uploads` | Uploaded files (photos, documents, covers, avatars) | + +Portainer resolves `./` relative to the stack's working directory. Confirm the paths under **Stack details** after deploying. + +### Named Volumes + +You can use Docker named volumes instead of bind mounts. Named volumes are fully managed by Docker and not tied to a host path — a good fit for Portainer where the working directory can vary. See the [Docker Compose volumes reference](https://docs.docker.com/reference/compose-file/volumes/) for all options. + +Replace the `volumes:` block in the service and add a top-level declaration: + +```yaml +services: + app: + # ... (rest of service config unchanged) + volumes: + - trek_data:/app/data + - trek_uploads:/app/uploads + +volumes: + trek_data: + trek_uploads: +``` + +Portainer lists named volumes under **Volumes** in the sidebar, where you can inspect or back them up. + +## Next Steps + +- [Environment-Variables](Environment-Variables) — full variable reference +- [Reverse-Proxy](Reverse-Proxy) — HTTPS configuration +- [Updating](Updating) — update strategies across all install methods diff --git a/wiki/Updating.md b/wiki/Updating.md index 70d8cd6f..32f7733d 100644 --- a/wiki/Updating.md +++ b/wiki/Updating.md @@ -6,13 +6,33 @@ How to update TREK to a newer version without losing data. Back up your data first. Go to Admin Panel → Backups and create a manual backup, or copy your `./data` and `./uploads` directories to a safe location. See [Backups](Backups) for details. +## Image Tags + +| Tag | Example | Behavior | +|---|---|---| +| `latest` | `mauriceboe/trek:latest` | Always the newest release across all major versions | +| Major version | `mauriceboe/trek:3` | Latest release pinned to that major version | +| Full version | `mauriceboe/trek:3.0.15` | Exact release; never changes | + +Use `latest` or a major-version tag if you want updates on each redeploy. Use a full version tag for explicit control — update by changing the tag, not by re-pulling. + ## Docker Compose (Recommended) +**`latest` or major-version tag:** + ```bash docker compose pull && docker compose up -d ``` -This pulls the latest image and recreates the container with your existing volumes. Your data is untouched. +This pulls the newest matching image and recreates the container with your existing volumes. Your data is untouched. + +**Pinned full-version tag:** + +Edit `docker-compose.yml`, update the tag in the `image:` line (e.g. `3.0.15` → `3.0.16`), then redeploy: + +```bash +docker compose up -d +``` ## Docker Run @@ -63,6 +83,22 @@ To verify the update completed and check for errors: journalctl -u trek -n 50 ``` +## Portainer + +Open the **Stacks** list, click the TREK stack, then click **Redeploy**. + +**`latest` or major-version tag** — enable the **Re-pull image and redeploy** switch before confirming. Portainer pulls the newest matching image and recreates the container. + +![Re-pull image and redeploy switch ticked, with arrows pointing to the switch and the Update button](assets/portainer-force-pull.png) + +**Pinned full-version tag** (e.g. `3.0.15`) — edit the stack, update the tag in the `image:` line, then click **Update the stack**. No re-pull switch needed; the tag change forces a fresh pull. + +![Edit stack page with an arrow pointing to the image tag in the compose editor](assets/portainer-update-version.png) + +![Edit stack page with an arrow pointing to the Update the stack button](assets/portainer-update-stack.png) + +See [Install-Portainer](Install-Portainer) for the full installation walkthrough. + ## Unraid In the Unraid Docker tab, click the TREK container and select **Update**. Unraid will pull the latest image and restart with the same volumes. diff --git a/wiki/_Sidebar.md b/wiki/_Sidebar.md index 994e0c4b..6bb2120d 100644 --- a/wiki/_Sidebar.md +++ b/wiki/_Sidebar.md @@ -6,6 +6,7 @@ - [[Install: Helm|Install-Helm]] - [[Install: Proxmox VE (LXC)|Install-Proxmox]] - [[Install: Unraid|Install-Unraid]] +- [[Install: Portainer|Install-Portainer]] - [[Reverse Proxy|Reverse-Proxy]] - [[Environment Variables|Environment-Variables]] - [[Updating]] diff --git a/wiki/assets/portainer-add-stack.png b/wiki/assets/portainer-add-stack.png new file mode 100644 index 00000000..250b5357 Binary files /dev/null and b/wiki/assets/portainer-add-stack.png differ diff --git a/wiki/assets/portainer-deploy-stack.png b/wiki/assets/portainer-deploy-stack.png new file mode 100644 index 00000000..91f5f471 Binary files /dev/null and b/wiki/assets/portainer-deploy-stack.png differ diff --git a/wiki/assets/portainer-environment-variable.png b/wiki/assets/portainer-environment-variable.png new file mode 100644 index 00000000..d19c62cf Binary files /dev/null and b/wiki/assets/portainer-environment-variable.png differ diff --git a/wiki/assets/portainer-force-pull.png b/wiki/assets/portainer-force-pull.png new file mode 100644 index 00000000..351c5398 Binary files /dev/null and b/wiki/assets/portainer-force-pull.png differ diff --git a/wiki/assets/portainer-stack-save.png b/wiki/assets/portainer-stack-save.png new file mode 100644 index 00000000..5be06d47 Binary files /dev/null and b/wiki/assets/portainer-stack-save.png differ diff --git a/wiki/assets/portainer-update-stack.png b/wiki/assets/portainer-update-stack.png new file mode 100644 index 00000000..53c41de4 Binary files /dev/null and b/wiki/assets/portainer-update-stack.png differ diff --git a/wiki/assets/portainer-update-version.png b/wiki/assets/portainer-update-version.png new file mode 100644 index 00000000..e86b8237 Binary files /dev/null and b/wiki/assets/portainer-update-version.png differ