mauriceboe/TREK: Self-Hosted Travel Planner with Real-Time Collaboration

mauriceboe/TREK: Self-Hosted Travel Planner with Real-Time Collaboration

Planning group trips with spreadsheets and scattered apps creates friction that technical teams feel acutely. Version conflicts, lost reservations, and the privacy cost of SaaS tools compound into a workflow problem worth solving with infrastructure you control. mauriceboe/TREK addresses this directly: a self-hosted travel planner with real-time collaboration, interactive maps, and modular features that deploy via Docker^{↗ Bright Coding Blog} in under a minute. With 10,341 GitHub stars and active development as of July 2026, it represents a mature open-source alternative to commercial trip-planning platforms.

This article examines what TREK offers developers, how to deploy it, and where it fits against alternatives.

What is mauriceboe/TREK?

TREK is an AGPL v3-licensed, self-hosted travel and trip planning application built in TypeScript. The project is maintained by Maurice Böe and has attracted 980 forks and a growing contributor community. Its architecture reflects modern full-stack patterns: a NestJS 11 backend with SQLite for data persistence, React^{↗ Bright Coding Blog} 19 with Vite for the frontend, Tailwind CSS^{↗ Bright Coding Blog} for styling, and Leaflet/Mapbox GL for map rendering.

The tool's relevance stems from its combination of real-time WebSocket synchronization, progressive web app (PWA) capabilities, and enterprise-grade authentication (OIDC SSO, WebAuthn passkeys, TOTP MFA). Unlike SaaS alternatives, TREK keeps itinerary data, reservation details, and collaborative notes on infrastructure you own. The 20-language internationalization support, RTL handling for Arabic, and admin-configurable feature modules ("addons") suggest design for heterogeneous teams and deployment contexts.

TREK's last commit date of July 14, 2026 indicates active maintenance. The GNU Affero GPL v3 license requires source disclosure for network-deployed modifications—a consideration for teams planning commercial hosting.

Key Features

Trip Planning Core: Drag-and-drop day planners with cross-day reordering, interactive maps supporting 3D buildings and terrain visualization, and place search via Google Places or OpenStreetMap. Route optimization auto-sorts destinations for export to Google Maps. Weather forecasts use Open-Meteo without API key requirements.

Travel Management: Reservation tracking (flights, accommodations, restaurants) with booking confirmation email and PDF import via KDE Itinerary integration. Cost splitting with per-person/per-day breakdowns and multi-currency support. Packing lists with templates, user assignment, and progress tracking. Document attachments up to 50 MB per file.

Collaboration Infrastructure: WebSocket-based real-time sync across all connected clients. Role-based trip membership with expiring invite links. Full SSO via OIDC (Google, Apple, Authentik, Keycloak, or generic providers). WebAuthn passkeys with admin-toggleable enforcement. Group chat, shared notes, polls, and day check-ins.

PWA & Mobile: Service Worker caching via Workbox for offline tile and API access. Fullscreen standalone mode with themed status bars and splash screens. Mobile-optimized layouts with safe-area handling.

AI Integration: Built-in MCP (Model Context Protocol) server with OAuth 2.1 authentication, exposing 150+ tools and 30 resources across 27 granular scopes. AI assistants can create trips, generate packing lists, manage budgets, and update travel journals through structured prompts.

Administrative Control: Dashboard with card grid or compact list views. Dark mode with matching status bar theming. Auto-backups with configurable retention. Per-user notification routing across email (SMTP), webhook, ntfy, and in-app channels.

Use Cases

Development Team Offsites: Technical teams planning retreats benefit from TREK's self-hosted model—sensitive destination and timing data stays internal. The real-time collaboration eliminates spreadsheet version conflicts, while the cost-splitting addon handles shared expenses transparently.

Privacy-Conscious Families: Households avoiding SaaS data harvesting use TREK's PWA installation for mobile access without app store dependencies. The document manager consolidates passports, visas, and booking confirmations in one encrypted SQLite database.

Travel Agencies & Tour Operators: Small operators can white-label TREK with custom OIDC providers and language defaults. The admin panel controls which addons (costs, collab, vacay planner) are exposed per deployment. PDF export generates client-ready itinerary documents.

AI-Augmented Planning Workflows: Teams already using MCP-compatible assistants (Claude, Cursor, or custom implementations) can automate trip construction. The granular OAuth scopes let administrators restrict AI access to read-only operations or specific trip contexts.

Remote Worker Visa Runs: Digital nomads tracking country stays for tax residency purposes use the Atlas addon's visited-country visualization, streak tracking, and liquid-glass UI. Integration with self-hosted AirTrail instances imports flight history automatically.

Installation & Setup

TREK's documented quick-start requires Docker. The maintainers emphasize mounting only data and uploads directories—never /app itself, which overwrites application code.

30-Second 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 command:

• Generates a 256-bit encryption key for at-rest secret protection
• Maps host directories for persistent database and file storage
• Exposes the application on port 3000

On first boot, TREK seeds an admin account. If ADMIN_EMAIL and ADMIN_PASSWORD environment variables are unset, credentials print to container logs retrievable via docker logs trek.

Production Docker Compose:

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}
      - LOG_LEVEL=${LOG_LEVEL:-info}
      - ALLOWED_ORIGINS=${ALLOWED_ORIGINS:-}
      - APP_URL=${APP_URL:-}
    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

Security-hardening elements include read-only root filesystem, dropped capabilities, tmpfs for temporary files, and healthcheck probes. The FORCE_HTTPS=true flag (commented in the example) activates only behind TLS-terminating reverse proxies.

Kubernetes Deployment:

helm repo add trek https://mauriceboe.github.io/TREK
helm repo update
helm install trek trek/trek

Values customization references charts/README.md in the repository.

Real Code Examples

Nginx Reverse Proxy Configuration (from README, with WebSocket support):

server {
    listen 80;
    server_name trek.yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name trek.yourdomain.com;

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

    # 500 MB covers backup-restore uploads (capped at 500 MB server-side).
    client_max_body_size 500m;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /ws {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 86400;
    }
}

The /ws location is non-negotiable: TREK's real-time synchronization depends on WebSocket upgrades. The 86400-second read timeout accommodates long-lived connections for collaborative sessions.

Encryption Key Rotation (from README):

docker exec -it trek node --import tsx scripts/migrate-encryption.ts

This script addresses key rotation when upgrading from versions that derived encryption from JWT_SECRET. It creates a timestamped database backup before migration and prompts for old and new keys with suppressed terminal echo.

Caddy Reverse Proxy (from README):

trek.yourdomain.com {
    reverse_proxy localhost:3000
}

Caddy's automatic TLS and WebSocket handling reduces configuration surface area compared to Nginx. This suits teams prioritizing operational simplicity over granular control.

The README contains these three explicit configuration examples. Additional deployment patterns (systemd, Podman, Nomad) would require community contribution or custom derivation from the Docker specifications.

Advanced Usage & Best Practices

Backup Strategy: The SQLite database at ./data/travel.db and uploads directory constitute all persistent state. Admin-panel backups create timestamped archives; auto-backup scheduling with retention policies prevents storage bloat. For enterprise deployments, consider volume snapshots at the infrastructure layer for point-in-time recovery.

OIDC Configuration: The APP_URL environment variable is mandatory for OIDC callback routing and email notification links. Misconfiguration produces subtle failures in authentication flows rather than explicit errors. Test with OIDC_ONLY=false before disabling password authentication entirely.

MCP Security: The built-in MCP server's 27 OAuth scopes enable fine-grained AI access control. Administrators should start with read-only scopes (trip:read, place:read) before granting mutation capabilities. The MCP_RATE_LIMIT (default 300 requests/minute/user) and MCP_MAX_SESSION_PER_USER (default 20) provide baseline DoS protection.

PWA Deployment: HTTPS is mandatory for service worker registration and passkey functionality. The TRUST_PROXY setting must accurately reflect proxy depth—incorrect values break IP-based rate limiting and WebSocket connection stability.

Addon Lifecycle: Admin-toggleable addons (costs, collab, vacay, atlas, journey, airtrail, MCP) enable feature discovery without code changes. Disable unused addons to reduce client bundle size and attack surface.

Comparison with Alternatives

Traccar excels at GPS tracking and fleet management but lacks trip planning semantics, collaborative features, and the document management TREK provides. Google Travel offers superior place data and flight integration but requires accepting Google's data practices and lacks self-hosting, SSO flexibility, or cost-splitting tools.

TREK's trade-off is operational responsibility: teams must manage backups, updates, and infrastructure scaling. The SQLite backend suits small-to-medium deployments; high-concurrency scenarios may require connection pooling or migration to PostgreSQL^{↗ Bright Coding Blog} (not currently documented).

FAQ

What are the minimum server requirements? The README does not specify hardware minimums. Docker-based deployment suggests any Linux host with 512 MB RAM and persistent storage suffices for personal use.

Can I use PostgreSQL instead of SQLite? Not documented. The backend explicitly targets SQLite with ./data/travel.db as the default path.

How do I update without losing data? Pull the latest image and recreate the container with identical volume mounts. Data persists in ./data and ./uploads.

Is there a hosted version available? The demo at demo.liketrek.com exists for evaluation. The AGPL v3 license requires source disclosure for any network-deployed modifications offered to third parties.

Does TREK work behind Cloudflare? Yes, with TRUST_PROXY configured appropriately. WebSocket support requires Cloudflare's proxy mode with "WebSockets" enabled.

Can I restrict sign-ups to my organization? Yes: enable OIDC_ONLY with your identity provider, or use invite-link controls in the admin panel.

What happens if I lose my encryption key? Stored secrets (API keys, SMTP credentials, OIDC configuration) become unrecoverable. The migration script requires the old key for rotation.

Conclusion

mauriceboe/TREK delivers a technically credible self-hosted alternative to commercial travel planners. Its strength lies in combining real-time collaboration, comprehensive authentication options, and modular feature expansion through a clean Docker deployment. The 10,341-star repository reflects genuine developer interest in data-sovereign tooling.

This tool suits teams with existing container infrastructure, privacy requirements preventing SaaS adoption, or integration needs with self-hosted services like AirTrail and Immich. The MCP server implementation positions it for AI-augmented workflows without vendor lock-in.

Deployment complexity is low for Docker-experienced teams but requires attention to reverse proxy WebSocket configuration and encryption key management. For organizations already running [INTERNAL_LINK: self-hosted productivity stack], TREK extends that philosophy to travel planning coherently.

Explore the repository, try the demo, and evaluate against your stack at https://github.com/mauriceboe/TREK.