How to Set Up TREK Using Docker: A Complete Self-Hosted Guide

TREK can be deployed in minutes using Docker Compose, which packages the React frontend, Node.js API, and PostgreSQL database into isolated containers with a single command.

TREK is a self-hosted travel-planning platform built with Node.js, TypeScript, and React. According to the mauriceboe/TREK source code, the Docker deployment uses a multi-container architecture defined in docker-compose.yml to orchestrate the web interface, API server, and PostgreSQL database. This guide covers the complete process to set up TREK using Docker on any Linux, macOS, or Windows host.

Understanding the TREK Docker Architecture

Before running commands, review how the containers interact. The docker-compose.yml file defines three primary services:

Web UI and API: Built from the repository's Dockerfile, this container serves both the React frontend and the REST/GraphQL API backend. The image compiles TypeScript and installs dependencies listed in shared/package.json, then exposes port 3000 by default.

PostgreSQL Database: Uses the official postgres:15-alpine image to persist trips, user accounts, and collaborative data. Data survives container restarts through a named Docker volume called trek-db-data.

Reverse Proxy (Optional): An nginx:alpine container can terminate TLS and forward traffic to the web service, ideal for production deployments requiring HTTPS.

Prerequisites

Ensure your system meets these requirements before proceeding:

• Docker Engine 20.10+ and Docker Compose v2.0+ installed
• Git for cloning the repository
• At least 2GB of available RAM and 5GB of disk space
• Ports 3000 (or your custom port) and 5432 available on the host

Step-by-Step Installation

Follow these commands to get TREK running locally.

1. Clone the Repository

git clone https://github.com/mauriceboe/TREK.git
cd TREK

2. Configure Environment Variables

Create a .env file in the project root to store sensitive configuration. Never commit this file to version control.

cat > .env <<EOF
POSTGRES_PASSWORD=SuperSecretPassword
JWT_SECRET=RandomJWTSecret
EOF

3. Build and Launch the Stack

Run the following command to build the images and start all services in detached mode:

docker compose up --build -d

4. Verify the Deployment

Check that all containers are healthy:

docker compose ps

The web interface will be accessible at http://localhost:3000.

Configuring Persistent Storage and Security

The Docker setup uses several mechanisms to protect your data.

Volume Persistence: PostgreSQL data is stored in the trek-db-data named volume. This volume persists across container restarts and updates, ensuring your travel plans and user accounts remain intact when you upgrade TREK.

Secret Management: Store all sensitive values—including POSTGRES_PASSWORD, JWT_SECRET, and encryption keys—in the .env file. The docker-compose.yml injects these variables into the containers at runtime without hardcoding them into the image.

Encryption Key Rotation: For production security, regularly rotate the encryption key following the steps in the wiki/Encryption-Key-Rotation.md documentation.

Customizing Ports and Adding a Reverse Proxy

You can modify the default configuration to suit your infrastructure.

Changing the Default Port

Edit docker-compose.yml to map a different host port to the container:

services:
  web:
    build: .
    ports:
      - "8080:3000"   # Host port 8080 maps to container port 3000

    env_file:
      - .env

After modifying, restart the stack:

docker compose up -d

Access TREK at http://localhost:8080.

Setting Up Nginx as a Reverse Proxy

For HTTPS termination, add an Nginx service. First, create nginx.conf:

events {}
http {
  server {
    listen 443 ssl;
    server_name trek.example.com;

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;

    location / {
      proxy_pass http://web:3000;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
    }
  }
}

Then append to docker-compose.yml:

  proxy:
    image: nginx:alpine
    ports:
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - web

Updating and Maintaining Your Instance

When a new release is available in the mauriceboe/TREK repository, upgrade with zero data loss:

git pull origin main
docker compose build
docker compose up -d

The build process pulls the latest code, compiles the TypeScript, and replaces the running containers while the trek-db-data volume preserves your database.

Monitoring Logs

View real-time logs for troubleshooting:

docker compose logs -f

For deeper observability, configure the Management Control Panel (MCP) to forward metrics to Prometheus or attach a Prometheus exporter to the stack.

Summary

• TREK uses Docker Compose to orchestrate the React frontend, Node.js API, and PostgreSQL database defined in docker-compose.yml.
• Store sensitive credentials in a .env file and never commit secrets to the repository.
• PostgreSQL data persists in the trek-db-data Docker volume, surviving updates and container restarts.
• The default port is 3000, but you can map any host port by editing the ports section in docker-compose.yml.
• Update the application by running git pull, docker compose build, and docker compose up -d without losing data.

Frequently Asked Questions

What are the minimum system requirements for running TREK in Docker?

TREK requires Docker Engine 20.10 or newer and Docker Compose v2.0 or higher. Allocate at least 2GB of RAM and 5GB of disk space for the container images, build cache, and database volume. The stack runs on Linux, macOS, and Windows hosts with Docker Desktop installed.

How do I backup my TREK data when using Docker?

Backup the PostgreSQL data by creating a snapshot of the trek-db-data Docker volume. Run docker run --rm -v trek-db-data:/data -v $(pwd):/backup alpine tar czf /backup/trek-backup.tar.gz -C /data . to export the database files. For complete disaster recovery, also backup your .env file containing the encryption keys and passwords.

Can I run TREK behind an existing reverse proxy or load balancer?

Yes. The TREK web container exposes port 3000 and functions as a standard HTTP backend. Configure your reverse proxy—whether Nginx, Traefik, or a cloud load balancer—to forward traffic to http://<host>:3000. Ensure the proxy sets the Host and X-Real-IP headers for proper request handling and IP logging.

Why does my database restart lose data, and how do I fix it?

Data loss occurs when PostgreSQL runs without a persistent volume. Verify that docker-compose.yml defines a named volume for the database service, such as trek-db-data, and that the volume is mounted to /var/lib/postgresql/data inside the container. Never use bind mounts or ephemeral storage for the database in production.

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