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

> Get started with TREK server code. Learn to set up this NestJS 11 TypeScript app locally with npm or easily with Docker. Requires an ENCRYPTION_KEY.

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

---

**The TREK server is a NestJS 11 TypeScript application that boots from [`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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](https://github.com/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`](https://github.com/mauriceboe/TREK/blob/main/package.json) declares workspaces for `client`, `server`, and `shared`, ensuring shared libraries compile before the server starts.

1. Clone the repository and install dependencies:

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

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

```bash
npm run dev --workspace=server

```

This command executes the sequence defined in the root [`package.json`](https://github.com/mauriceboe/TREK/blob/main/package.json): it compiles the shared library, then runs the NestJS development server. The entry point at [`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/index.ts) creates required upload directories, builds the Nest application via `buildApp` imported from [`server/src/bootstrap.ts`](https://github.com/mauriceboe/TREK/blob/main/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.

```bash
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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/server/src/index.ts) dynamically imports [`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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:

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

```typescript
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`](https://github.com/mauriceboe/TREK/blob/main/server/src/mcp/tools/trips.ts), which internally calls the `tripService` layer shared with the REST API.

## Summary

- **Entry point**: [`server/src/index.ts`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/server/src/bootstrap.ts) builds the app, [`server/src/websocket.ts`](https://github.com/mauriceboe/TREK/blob/main/server/src/websocket.ts) handles real-time connections, and [`server/src/mcp/index.ts`](https://github.com/mauriceboe/TREK/blob/main/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`](https://github.com/mauriceboe/TREK/blob/main/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.