# How to Test the TREK Server Locally: Docker and Development Setup

> Easily test the TREK server locally using Docker for quick setup or run from source with npm run dev for full development control. Get your local TREK environment running fast.

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

---

**You can test the TREK server locally using Docker (quick-start or compose) for containerized testing, or run it directly from source with `npm run dev` for debugging and development.**

TREK is an open-source trip planning application built on a **NestJS** and **SQLite** stack. According to the `mauriceboe/TREK` source code, the server boots an Express and WebSocket server, initializes the database schema from [`server/src/db/schema.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/db/schema.ts), and registers all API routes in [`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/index.ts). This guide covers three verified methods to run the server on your own machine: a quick Docker one-liner, a Docker Compose setup for persistent testing, and a local Node.js development mode for debugging and running the Jest test suite.

## Quick-Start Docker Method

The fastest way to test the TREK server locally is a single `docker run` command that spins up the complete application on port **3000**.

### Essential Configuration

Before starting the container, you must configure five critical settings documented in the repository's [`wiki/Quick-Start.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/Quick-Start.md) and [`wiki/Environment-Variables.md`](https://github.com/mauriceboe/TREK/blob/main/wiki/Environment-Variables.md):

- **Encryption key**: Generate a 32-byte hex key to encrypt stored secrets (API keys, MFA seeds). If omitted, the container generates one automatically at `./data/.encryption_key`.
- **Admin credentials**: Provide `ADMIN_EMAIL` and `ADMIN_PASSWORD` to pre-seed the admin user; otherwise, a random password prints to the container logs on first start.
- **Cookie security**: Set `COOKIE_SECURE=false` for local HTTP testing (production auto-derives this from `NODE_ENV`).
- **Volume mounts**: Bind host directories to `/app/data` (SQLite persistence) and `/app/uploads` (file attachments) to survive container restarts.

### Docker Run Command

```bash
ENCRYPTION_KEY=$(openssl rand -hex 32) \
docker run -d \
  --name trek \
  -p 3000:3000 \
  -e ENCRYPTION_KEY=$ENCRYPTION_KEY \
  -e COOKIE_SECURE=false \
  -e ADMIN_EMAIL=admin@example.com \
  -e ADMIN_PASSWORD=StrongPass! \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/uploads:/app/uploads \
  --restart unless-stopped \
  mauriceboe/trek:latest

```

After the container starts, open `http://localhost:3000`. The server listens on port 3000, serving the REST API under `/api/*` and the WebSocket endpoint at `ws://localhost:3000/ws` (handled by [`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts) for real-time collaboration).

## Docker Compose for Persistent Local Testing

For a production-like local environment with dedicated volumes and easier configuration management, use the [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml) file included in the repository root.

```bash
docker compose up -d

```

This approach mounts the `data` and `uploads` volumes automatically, ensuring your SQLite database and uploaded files persist across restarts. You can edit the compose file to pin specific versions (e.g., `image: mauriceboe/trek:3.0.15`) or add additional environment variables for testing different configurations.

## Local Development Mode with Node.js

To debug the server or run the test suite without rebuilding Docker images, execute TREK directly from the source tree. This method references the exact entry point in [`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/index.ts) and allows hot-reloading during development.

### Setup and Start Commands

```bash

# Install dependencies for all workspaces

npm install

# Build shared code (required before server startup)

npm run build --workspace=shared

# Start the server in watch mode

npm run dev --workspace=server

```

The server initializes the SQLite schema from [`server/src/db/schema.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/db/schema.ts) and registers all service layers (located in `server/src/services/`) before binding to `http://localhost:3000`.

### Running the Test Suite

Local development mode enables direct execution of the Jest test suite located in `server/tests/`:

```bash

# Run all tests

npm run test --workspace=server

# Run only unit tests

npm run test:unit --workspace=server

# Run integration tests (API endpoints and database)

npm run test:integration --workspace=server

```

The integration tests spin up an in-memory SQLite instance, invoke services directly, and assert HTTP responses through SuperTest—verifying that your local changes behave correctly before committing.

## Verifying Your Local Setup

Confirm your local TREK instance is functioning correctly by testing both the REST API and WebSocket layers.

### Test the REST API

Create a test trip via curl after authenticating with the admin credentials:

```bash

# Obtain JWT (replace with your admin credentials)

curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"StrongPass!"}'

# Create a trip (replace <admin-jwt> with the token from above)

curl -X POST http://localhost:3000/api/trips \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-jwt>" \
  -d '{"name":"Demo Trip","startDate":"2024-01-01","endDate":"2024-01-07"}'

```

### Test Real-Time WebSocket Updates

Verify the WebSocket implementation in [`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts) by subscribing to trip updates:

```javascript
const ws = new WebSocket('ws://localhost:3000/ws');
ws.onopen = () => ws.send(JSON.stringify({type:'subscribe',tripId:1}));
ws.onmessage = e => console.log('Update:', JSON.parse(e.data));

```

The server broadcasts mutations (adding places, toggling todos) to all connected clients in real-time.

## Summary

- **Docker Quick-Start**: Use `docker run` with `ENCRYPTION_KEY`, volume mounts for `data` and `uploads`, and `COOKIE_SECURE=false` for immediate local testing on port 3000.
- **Docker Compose**: Utilize the repository's [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml) for persistent local deployments with pre-configured volumes and environment variables.
- **Development Mode**: Run `npm run dev --workspace=server` after building the shared workspace to enable debugging, hot-reloading, and direct access to the Jest test suite in `server/tests/`.
- **Key Files**: The server entry point is [`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/index.ts), the database schema lives in [`server/src/db/schema.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/db/schema.ts), and real-time functionality is handled by [`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts).

## Frequently Asked Questions

### Do I need Docker to test TREK locally?

No. While Docker provides the fastest containerized setup, you can test the TREK server locally by cloning the repository and running `npm install` followed by `npm run dev --workspace=server`. This development mode is essential for debugging and running the Jest test suite without container overhead.

### How do I access the admin account when testing locally?

If you provide `ADMIN_EMAIL` and `ADMIN_PASSWORD` environment variables when starting the container, use those credentials to log in at `http://localhost:3000`. If you omit them, the server generates a random password on first startup; retrieve it by running `docker logs trek` (or your container name) and look for the generated credentials in the output.

### Where are the database and uploaded files stored during local testing?

In Docker mode, the SQLite database resides in the mounted volume at `./data` (mapped to `/app/data` inside the container), and file uploads persist in `./uploads` (mapped to `/app/uploads`). In local development mode, these paths are relative to the server workspace root, ensuring your data survives container restarts or server reboots.

### Can I run the test suite without Docker?

Yes. The Jest test suite runs directly against the source code using `npm run test --workspace=server`. The integration tests spin up an in-memory SQLite instance and use SuperTest to hit the HTTP endpoints directly, cleaning up the temporary database after completion. This requires no Docker containers and executes against the actual service implementations in `server/src/services/`.