TREK: Self-Hosted Travel Planner with Real-Time Maps, Budgets, and AI

Your trips. Your plan. Your server.

That is the tagline on TREK — a self-hosted, real-time collaborative travel planner that has climbed to 6.8k GitHub stars and 614 forks while most travel apps still require surrendering itineraries, photos, and location history to a SaaS vendor.

Latest release: v3.1.2 (June 2026), two days after v3.1.1 bug fixes. TREK ships maps, budgets, packing lists, a journey journal, expense splitting, an Atlas of visited countries, AI assistance, SSO, and a installable PWA — all on your hardware, backed by SQLite, synced over WebSockets.

TL;DR

What TREK Actually Does

TREK is not a static itinerary PDF generator. It is a live collaborative workspace for trip planning — closer to Wanderlog or TripIt in feature scope, but running on infrastructure you control.

Core modules

Real-time sync means multiple travelers can edit the same trip simultaneously — changes propagate over WebSocket (/ws) without manual refresh. That architecture choice matters for group trips where one person adds a restaurant while another adjusts the route.

AI built in

TREK includes AI features in the product surface (per the README hero). The repository ships MCP.md — Model Context Protocol documentation for integrating external AI tools with TREK's data layer. If you are building agent workflows that need structured trip context (dates, POIs, budgets), MCP is the integration path rather than scraping the UI.

For broader MCP patterns, see our MCP complete guide.

Get Started in 30 Seconds

The fastest path is Docker:

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

Open http://localhost:3000.

On first boot, TREK seeds an admin account. Either set environment variables:

-e ADMIN_EMAIL=you@example.com -e ADMIN_PASSWORD='your-secure-password'

Or read the generated credentials from the container log:

docker logs trek

Critical volume mount rule

Mount only ./data and ./uploads. Never mount a volume at /app — doing so hides the application code baked into the image and the container fails with Cannot find module 'tsconfig-paths/register'. If you previously used a full /app mount, switch to the two-directory pattern; your existing data in data/ and uploads/ is preserved.

Production Deployment

Docker Compose

Full compose examples with secure defaults are in the TREK docs. Production pattern: TLS-terminating reverse proxy in front, WebSocket upgrade support on /ws.

Helm (Kubernetes)

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

See charts/README.md for values — including PVC annotation support added in recent releases.

Unraid

TREK ships an unraid-template.xml and ca_profile.xml for Unraid Community Apps submission — relevant if your homelab already runs Immich or other self-hosted media stacks.

Reverse proxy

TREK requires WebSocket upgrade support on /ws for real-time sync. Nginx and Caddy examples are in the repository docs. Without WebSocket passthrough, collaboration appears to work locally but sync breaks behind the proxy.

Updating

docker compose pull && docker compose up -d

Or for plain Docker:

docker pull mauriceboe/trek
docker rm -f trek
docker run -d --name trek -p 3000:3000 \
  -v ./data:/app/data -v ./uploads:/app/uploads \
  --restart unless-stopped mauriceboe/trek

Check existing mount paths first: docker inspect trek --format '{{json .Mounts}}'.

Install as PWA (No App Store)

TREK works as a Progressive Web App:

1. Open TREK over HTTPS (required for PWA install)
2. iOS: Share → Add to Home Screen
3. Android: Menu → Install app (or Add to Home Screen)

The app launches fullscreen with its own icon — useful on trip days when you want quick access to the day plan without browser chrome.

Security and Encryption

TREK encrypts sensitive data with ENCRYPTION_KEY. To rotate keys (e.g. upgrading from a version that derived encryption from JWT_SECRET):

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

The script creates a timestamped DB backup before changes and prompts for old and new keys (input is not echoed).

Authentication stack:

• JWT for session tokens
• OAuth 2.1 + OIDC for enterprise SSO
• Passkeys (WebAuthn) for passwordless login
• TOTP MFA for second factor

Backups are configurable in the Admin Panel — manual create/restore plus scheduled auto-backups with retention policies.

TREK vs SaaS Travel Apps

TREK fits the same self-hosting philosophy as files.md local-first notes and Immich for photos: your data, your rules, with AGPL ensuring network-service modifications stay open if you offer TREK commercially to others.

Atlas and Data Sources

The Atlas module visualizes visited countries and sub-national regions. Boundaries come from geoBoundaries (Runfola et al., 2020), licensed CC BY 4.0. Full third-party attributions are in NOTICE.md.

Weather data uses Open-Meteo — no API key required, which keeps homelab setup friction low.

Who Should Use TREK

Good fit:

• Families or friend groups planning shared trips with live editing
• Privacy-conscious travelers who do not want itineraries in a third-party cloud
• Homelab users already running Docker/Compose/K8s stacks
• Teams wanting SSO (OIDC) on an internal trip-planning tool

Less ideal:

• Users who want zero maintenance — self-hosting has ops cost
• Trips requiring deep airline/hotel GDS integration (TREK is planner-first, not booking-first)
• AGPL-averse organizations that cannot comply with network-service copyleft

Test the trip workflow before inviting your group

Create a disposable itinerary before entering the real trip. Add two fictional travelers, a hotel, two activities on the same day, and expenses in different currencies. Open the plan in two browser sessions and change the same activity from both. Observe whether the second session updates, whether an edit is overwritten, and whether the interface makes the current state clear. Real-time collaboration is useful only if your group understands how conflicts are handled.

Try the actual roles your travelers will use. A person who can comment should not automatically receive permission to delete the entire itinerary. Check invitations, ownership transfer, and revocation with test accounts; do not infer permissions from the presence of an SSO button. Confirm what a shared link exposes before putting booking references or passport-related information anywhere in the plan. A link suitable for a public sightseeing schedule may be unsuitable for a private reservation.

Then test the phone you will take on the trip. Add the app to the home screen if supported, turn connectivity off, and inspect which information remains available. A PWA installation does not itself establish offline editing or reliable later synchronization. Keep a separate copy of essential addresses, booking confirmations, and emergency contacts if the application cannot serve them without a network. Reconnect and check for duplicated or missing edits before relying on offline behavior.

Separate an installation from a recoverable service

Keep the deployment's encryption and authentication secrets stable across container recreation. Generating new values for every restart can invalidate sessions or make stored encrypted material unreadable, depending on the application's use of those keys. Follow the settings for the version you actually deploy rather than copying an old example and silently substituting fresh secrets during an upgrade.

Inventory the state outside the container: database contents, uploaded attachments, configuration, and required keys. A running container image is not a backup of those items. Create a backup, restore it into a separate test installation, and verify that the sample itinerary, participants, expenses, and attachments survive. Restoration is the useful acceptance check; a successful archive command alone does not demonstrate that the trip can be recovered.

Pin the release you tested and record its configuration. The v3.1.2 details above describe the publication snapshot; the current TREK repository may change environment variables and deployment instructions. Read upgrade notes before replacing the image and retain a recovery copy made with the old version. Schedule that work before departure instead of discovering compatibility differences while travelers are already depending on the plan.

A practical launch decision is whether another traveler can use the system without you sitting beside them. Ask them to add an activity, find the accommodation, and record a shared expense. Their questions reveal missing instructions and permission problems earlier than a tour of the feature list does.

Related explainx.ai coverage

Summary

TREK v3.1.2 is the most complete open-source answer to "why does my trip planner need to live in someone else's cloud?" — real-time collaboration, 3D maps, budgets with expense splitting, packing lists, journal, Atlas, PWA install, Passkeys, and documented MCP hooks, deployable in one Docker command.

6.8k stars suggest the audience was waiting for this. If you are already self-hosting photos and notes, adding trips is a natural next tab.

Last updated: June 26, 2026. Version and stats from github.com/mauriceboe/TREK and release v3.1.2.