TREK Deployment Options: Complete Guide to Docker, Kubernetes, and Self-Hosted Install

TREK supports deployment via single-container Docker, production-grade Docker Compose, Kubernetes Helm charts, reverse proxies, and platform-specific methods including Unraid, Portainer, and Proxmox source builds.

TREK is an open-source application built with NestJS and React that can be deployed in environments ranging from a single container to enterprise Kubernetes clusters. The mauriceboe/TREK repository provides multiple configuration paths to accommodate different infrastructure requirements and security postures. This guide covers every officially supported TREK deployment option, referencing the actual source files and configuration examples maintained in the repository.

Docker Deployment Options

The simplest way to run TREK is through Docker, with two primary approaches depending on your security and orchestration needs.

Single Container (Docker Run)

The single-container deployment uses the official mauriceboe/trek image to run both the NestJS backend and React frontend in one process. This method persists data through bind-mounted volumes at /app/data and /app/uploads.

Run this command for a quick start:

ENCRYPTION_KEY=$(openssl rand -hex 32) \
docker run -d -p 3000:3000 \
  -e ENCRYPTION_KEY=$ENCRYPTION_KEY \
  -v ./data:/app/data \
  -v ./uploads:/app/uploads \
  mauriceboe/trek

This approach is defined in the repository's README.md and is ideal for personal use, testing, or when you need a single-process container with minimal overhead.

Production Docker Compose

For production deployments, the repository provides a hardened docker-compose.yml that adds security constraints and health monitoring. The configuration includes read-only root filesystem, no-new-privileges restrictions, and capability drops to minimize the attack surface.

Key security features in docker-compose.yml:

• read_only: true mounts the root filesystem as read-only
• security_opt: no-new-privileges:true prevents privilege escalation
• cap_drop: ALL removes all Linux capabilities, with only CHOWN, SETUID, and SETGID added back
• tmpfs mount for /tmp with noexec and nosuid flags
• Health check endpoint at /api/health

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:-}
      - TZ=${TZ:-UTC}
    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

This configuration is located at docker-compose.yml in the repository root and is documented in wiki/Install-Docker-Compose.md.

Kubernetes and Helm Deployment

For cloud-native environments, TREK provides a Helm chart located in the charts/ directory. The chart installs TREK as a Kubernetes Deployment with Persistent Volume Claims (PVCs) for data storage and optional Ingress configuration for external access.

Install the chart using the official repository:

helm repo add trek https://mauriceboe.github.io/TREK
helm repo update
helm install trek trek/trek \
  --set env.ENCRYPTION_KEY=$(openssl rand -hex 32) \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=trek.example.com

The Helm chart mirrors the Docker Compose security settings through PodSecurityContext and SecurityContext configurations. Environment variables and secrets are managed via values.yaml or command-line --set flags. Full documentation is available in charts/README.md and wiki/Install-Helm.md.

Reverse Proxy Configuration

TREK is designed to run behind TLS-terminating reverse proxies such as NGINX, Caddy, or Traefik. The application handles WebSocket traffic at the /ws endpoint and requires the TRUST_PROXY setting to correctly identify client IPs when running behind a proxy.

Example NGINX configuration from wiki/Reverse-Proxy.md:

server {
    listen 80;
    server_name trek.example.com;
    return 301 https://$host$request_uri;
}
server {
    listen 443 ssl http2;
    server_name trek.example.com;

    ssl_certificate     /etc/ssl/fullchain.pem;
    ssl_certificate_key /etc/ssl/privkey.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

When using a reverse proxy, set FORCE_HTTPS=false in TREK's environment and allow the proxy to handle TLS termination. The TRUST_PROXY environment variable must be configured to ensure the application trusts the proxy headers.

Platform-Specific Deployment Methods

Beyond standard Docker and Kubernetes, TREK supports deployment through several popular container management platforms.

Unraid

Home-lab users can deploy TREK through Unraid's Docker UI. The wiki/Install-Unraid.md guide provides step-by-step instructions for configuring volume mounts (/app/data and /app/uploads) and environment variables through Unraid's "Add Container" form. The underlying image remains mauriceboe/trek.

Portainer

Teams using Portainer can deploy TREK as a Docker Compose stack. The wiki/Install-Portainer.md documentation explains how to paste the production docker-compose.yml content into Portainer's stack editor, enabling graphical management of the deployment while maintaining the same security hardening as the CLI method.

Proxmox (Source Install)

For environments requiring direct OS-level control, TREK can be built from source on a Proxmox VM. This method, documented in wiki/Install-Proxmox.md, involves installing Node.js, building the NestJS backend and Vite frontend, and binding the server to a specific host address via the HOST environment variable. This is the only deployment method that does not use containerization.

Progressive Web App (PWA) Installation

TREK's frontend functions as a Progressive Web App, allowing users to install it as a native-like application on mobile devices and desktops. After deploying the backend using any of the above methods and serving it over HTTPS:

1. Open TREK in a modern browser
2. On iOS: tap Share → Add to Home Screen
3. On Android: tap Menu → Install app

This creates a standalone application experience without requiring additional server components. The PWA functionality is documented in the README.md under "Install as App (PWA)".

Security and Architecture Considerations

All containerized deployment methods follow an immutable container pattern where state is stored externally in volumes (/app/data for the SQLite database and /app/uploads for files). This design allows containers to be replaced or upgraded without data loss.

Security configurations vary by method:

• Docker Compose: Implements read-only rootfs, capability dropping, and no-new-privileges
• Kubernetes: Enforces these same constraints via SecurityContext and PodSecurityContext in charts/values.yaml
• Environment Management: Sensitive values like ENCRYPTION_KEY and OIDC_* variables are passed via Docker -e flags, .env files, or Kubernetes secrets, as documented in wiki/Environment-Variables.md

TLS handling can be delegated to reverse proxies (recommended) or handled directly by setting FORCE_HTTPS=true when running TREK on a public host without a proxy.

Summary

• Single-container Docker (docker run) provides the fastest setup for testing and personal use using the mauriceboe/trek image
• Docker Compose (docker-compose.yml) adds production security hardening including read-only filesystems and capability drops
• Helm charts (charts/) enable Kubernetes deployments with PVCs, Ingress support, and pod security contexts
• Reverse proxies (NGINX, Caddy, Traefik) handle TLS termination and WebSocket forwarding for /ws endpoints
• Platform integrations include Unraid's Docker UI, Portainer stacks, and Proxmox source builds for non-containerized installs
• PWA installation allows end-users to install the frontend as a native app after HTTPS deployment

Frequently Asked Questions

What is the minimum hardware requirement for running TREK?

TREK runs efficiently on minimal hardware due to its containerized architecture. The single Docker image (mauriceboe/trek) containing both the NestJS backend and React frontend can operate on any system capable of running Docker, requiring only enough storage for the mapped volumes at /app/data and /app/uploads. For production workloads, allocate resources based on expected concurrent user load following the Docker Compose or Kubernetes specifications.

How do I secure TREK behind a reverse proxy?

Configure your reverse proxy to terminate TLS and forward traffic to TREK's HTTP port, then set TRUST_PROXY in TREK's environment variables so the application recognizes the real client IP. The wiki/Reverse-Proxy.md file contains complete configurations for NGINX, Caddy, and Traefik that properly handle WebSocket upgrade headers for the /ws endpoint. Ensure FORCE_HTTPS is set to false when the proxy handles TLS termination.

Can TREK run without Docker?

Yes, TREK supports non-containerized deployment through the source-based install method documented in wiki/Install-Proxmox.md. This approach requires building the application from source using Node.js, installing dependencies for the NestJS backend and Vite frontend, and configuring the HOST environment variable to bind to a specific network interface. This method is intended for advanced users who need direct OS-level control or integration with Proxmox-specific tooling.

How do I backup TREK data?

Backup the persistent volumes mounted at /app/data (containing the SQLite database) and /app/uploads (containing user files). In Docker deployments, these correspond to your host's ./data and ./uploads directories. For Kubernetes deployments, backup the Persistent Volume Claims (PVCs) defined in the Helm chart. The application stores all persistent state in these locations, making backup and migration straightforward across any deployment method.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}