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

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, and registers all API routes in 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 and 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

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 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 file included in the repository root.

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 and allows hot-reloading during development.

Setup and Start Commands

# 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 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/:

# 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:

# 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 by subscribing to trip updates:

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 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, the database schema lives in server/src/db/schema.ts, and real-time functionality is handled by 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/.

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