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

> Easily set up TREK with Docker Compose. This self-hosted guide covers deploying the React frontend, Node.js API, and PostgreSQL database in minutes.

- Repository: [Maurice/TREK](https://github.com/mauriceboe/TREK)
- Tags: how-to-guide
- Published: 2026-07-03

---

**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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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**

```bash
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.

```bash
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:

```bash
docker compose up --build -d

```

**4. Verify the Deployment**

Check that all containers are healthy:

```bash
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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml) to map a different host port to the container:

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

    env_file:
      - .env

```

After modifying, restart the stack:

```bash
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`](https://github.com/mauriceboe/TREK/blob/main/nginx.conf):

```nginx
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`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml):

```yaml
  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:

```bash
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:

```bash
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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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.