How to Get Started with the TREK Server Code: A Complete Setup Guide

The TREK server is a NestJS 11 TypeScript application that boots from server/src/index.ts, requires an ENCRYPTION_KEY environment variable, and can be started locally via npm workspaces or instantly via Docker.

To get started with the TREK server code, you need to understand its monorepo structure, environment configuration, and NestJS 11 bootstrap sequence. The backend application resides in the server workspace, booting from server/src/index.ts to create required directories, build the Nest application, and initialize both HTTP and WebSocket servers for real-time collaboration. This guide covers the exact commands, file paths, and architectural patterns used in the mauriceboe/TREK repository.

Prerequisites and Repository Structure

The TREK project uses npm workspaces to manage dependencies across three packages. According to the source code, the root package.json declares workspaces for client, server, and shared, ensuring shared libraries compile before the server starts.

1. Clone the repository and install dependencies:

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

This installs all dependencies across the monorepo, including the shared libraries that the server imports at runtime.

Environment Configuration

Before booting the application, you must set several environment variables. The server reads these at runtime via server/src/config.ts, with critical variables affecting encryption, authentication, and external integrations.

Required variables include:

• ENCRYPTION_KEY: A 32-byte hexadecimal string for at-rest encryption of secrets
• APP_URL: Public base URL required for OIDC callbacks and email links
• ADMIN_EMAIL / ADMIN_PASSWORD: Initial admin credentials created on first boot

Optional variables include PORT (defaults to 3000), DEMO_MODE for hourly data resets, and OIDC_* settings for SSO providers.

Generate an encryption key locally:

export ENCRYPTION_KEY=$(openssl rand -hex 32)

Running the Server Locally

Development Mode with Hot Reload

The recommended way to get started with the TREK server code during development uses the root-level npm scripts with concurrently. The dev script builds the shared workspace first, then launches the server with hot-reload enabled.

npm run dev --workspace=server

This command executes the sequence defined in the root package.json: it compiles the shared library, then runs the NestJS development server. The entry point at server/src/index.ts creates required upload directories, builds the Nest application via buildApp imported from server/src/bootstrap.ts, and starts listening on the configured port.

Docker Quick Start

For immediate testing without installing Node.js dependencies, use the pre-built image. The container automatically creates the initial admin user and prints credentials to logs on first boot.

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

Access the application at http://localhost:3000 and check container logs for the generated admin password.

Core Architecture and Entry Points

Understanding the boot sequence helps when extending the server code. The application follows a modular NestJS pattern with clear separation between HTTP setup, WebSocket attachment, and MCP initialization.

Bootstrap and Application Build

The server/src/bootstrap.ts module exports the buildApp function, which constructs the INestApplication. This file registers global pipes, imports feature modules (auth, trips, services, MCP), and configures middleware. When server/src/index.ts calls buildApp, it receives a fully configured Nest instance ready for HTTP traffic.

Real-Time WebSocket Layer

Collaboration features rely on WebSocket connections at the /ws endpoint. After the HTTP server starts listening, server/src/index.ts dynamically imports server/src/websocket.ts and invokes setupWebSocket(server) to attach the WS handler. This forwards incoming messages to the Nest-based WebSocketGateway for real-time trip synchronization.

MCP (Machine-Client-Protocol) Endpoints

The MCP interface exposes over 150 AI-usable tools under /mcp. The entry point at server/src/mcp/index.ts initializes the OAuth 2.1 server and registers tool endpoints. This layer reuses the same service logic as the REST API, ensuring consistency between human and machine clients.

Connecting to Server Features

Once running, interact with the server's real-time and programmatic interfaces using standard WebSocket and HTTP clients.

Authenticating via WebSocket

Connect to the collaborative layer using any WebSocket client:

import WebSocket from 'ws';

const ws = new WebSocket('ws://localhost:3000/ws');

ws.on('open', () => {
  console.log('WebSocket connected');
  ws.send(JSON.stringify({ type: 'ping' }));
});

ws.on('message', data => console.log('←', data.toString()));

The handler in server/src/websocket.ts manages these connections and routes messages through the Nest gateway system.

Calling MCP Tools

Access the AI toolset via authenticated HTTP requests:

import fetch from 'node-fetch';

const token = 'YOUR_MCP_ACCESS_TOKEN';
const resp = await fetch('http://localhost:3000/mcp/tools/trips', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ action: 'listTrips' })
});
const result = await resp.json();
console.log(result);

This endpoint hits server/src/mcp/tools/trips.ts, which internally calls the tripService layer shared with the REST API.

Summary

• Entry point: server/src/index.ts bootstraps the HTTP server, creates directories, and attaches WebSocket handlers
• Environment: Requires ENCRYPTION_KEY, APP_URL, and admin credentials set via environment variables
• Development: Use npm run dev --workspace=server from the monorepo root to build shared code and start with hot-reload
• Docker: Single-command deployment with mauriceboe/trek image, mounting volumes for data persistence
• Architecture: NestJS 11 application with modular structure; server/src/bootstrap.ts builds the app, server/src/websocket.ts handles real-time connections, and server/src/mcp/index.ts exposes AI tools

Frequently Asked Questions

What Node.js version does TREK require?

The TREK server is built on NestJS 11 and TypeScript. While the repository doesn't specify a minimum Node.js version in the provided snippets, NestJS 11 typically requires Node.js 18 or higher. Check the engines field in server/package.json for exact version constraints.

How do I generate a secure ENCRYPTION_KEY?

Run openssl rand -hex 32 in your terminal to generate a 64-character hexadecimal string representing 32 bytes. This value encrypts sensitive data at rest. Store it securely in your .env file or Docker environment variables; losing this key makes encrypted data unrecoverable.

Why does the server need the APP_URL environment variable?

The APP_URL variable defines the public base URL (e.g., https://trek.example.com). The server uses this to generate correct callback URLs for OIDC authentication flows and to construct links in outgoing emails. Without it, SSO logins and password reset emails will redirect to incorrect addresses.

Can I run the server without the MCP features enabled?

Yes. The MCP layer is part of the core application but exposed via separate endpoints under /mcp. If you don't need the AI tool interface, you can simply not call those endpoints. The server functions fully as a travel planning API without ever initializing MCP client connections, though the endpoints remain available.

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