# How to Build TREK from Source: Complete Local and Docker Installation Guide

> Learn how to build TREK from source with our easy local and Docker installation guide. Clone the repo, run the build script, and start the server fast.

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

---

**To build TREK from source, clone the repository, run the `./build-from-sources` script to install dependencies and bundle the React client, then start the NestJS server with `npm run dev` in the `server` directory.**

TREK is a full-stack TypeScript application organized into three npm workspaces—`client`, `server`, and `shared`—that requires Node.js 22 or later to compile. According to the `mauriceboe/TREK` source code, the build process bundles a React 19 frontend with Vite and prepares a NestJS 11 backend to serve those static assets. This guide provides the exact commands and file paths needed to compile the project locally or package it for production deployment.

## Prerequisites

Before building TREK from source, ensure your environment meets the following requirements:

- **Node.js** version 22 or higher (as specified in the repository README badge)
- **npm** (comes bundled with Node.js)
- **Git** for cloning the repository
- **Docker** and **Docker Compose** (optional, for containerized deployment)

## Understanding the Workspace Structure

The repository uses **npm workspaces** to manage three distinct packages:

- **`client/`** – A React 19 application bundled with Vite. Configuration resides in [`client/package.json`](https://github.com/mauriceboe/TREK/blob/main/client/package.json).
- **`server/`** – A NestJS 11 backend that serves the API and static files. Configuration resides in [`server/package.json`](https://github.com/mauriceboe/TREK/blob/main/server/package.json).
- **`shared/`** – Common TypeScript type definitions and utilities shared between client and server.

The root [`package.json`](https://github.com/mauriceboe/TREK/blob/main/package.json) defines these workspaces and orchestrates top-level scripts, while the `build-from-sources` script in the repository root automates the cross-workspace compilation.

## Building TREK from Source

### Automated Build with the Helper Script

The fastest way to build TREK from source is using the provided `build-from-sources` script located in the repository root. This executable performs three operations: installs dependencies for both client and server, executes `npm run build` in the `client` directory to generate a production-ready `dist/` folder, and copies those compiled assets into `server/public` so the NestJS application can serve them.

Execute the following commands:

```bash
git clone https://github.com/mauriceboe/TREK.git
cd TREK
./build-from-sources

```

### Manual Build Steps

If you prefer to run each step manually or need to troubleshoot specific workspaces, execute these commands sequentially:

1. **Install root and workspace dependencies:**

   While `npm ci` in the root installs all workspace dependencies automatically, the explicit per-workflow approach matches the script's behavior:

   ```bash
   cd client
   npm ci
   npm run build
   ```

   ```bash
   cd ../server
   npm ci
   ```

2. **Verify the client output:**

   The Vite build process creates a `dist/` directory inside `client/` containing optimized static assets. These files must be manually copied to `server/public` if you are not using the helper script.

## Running the Application

### Development Mode

After building, start the NestJS server in development mode with hot-reload enabled:

```bash
cd server
npm run dev

```

The server listens on **port 3000** by default. You can override this by setting the `PORT` environment variable before running the command.

### Production Deployment with Docker

For production deployments, TREK provides a `Dockerfile` and [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml) that expect the `server/public` directory to be populated with the built client assets from the previous steps.

First, ensure you have run `./build-from-sources` to populate `server/public`, then build the image:

```bash
docker build -t mauriceboe/trek:dev .

```

Run the container with required volumes and environment variables:

```bash
docker run -d -p 3000:3000 \
  -e ENCRYPTION_KEY=$(openssl rand -hex 32) \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/uploads:/app/uploads \
  mauriceboe/trek:dev

```

Alternatively, use Docker Compose for a production-like setup:

```bash
docker compose up -d

```

The [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml) file handles port mapping, volume persistence for `data/` and `uploads/`, and environment configuration.

## Summary

- **TREK** is a TypeScript monorepo with three npm workspaces (`client`, `server`, `shared`) requiring Node.js 22+.
- The **`build-from-sources`** script in the repository root automates dependency installation, client bundling, and asset placement in `server/public`.
- **Client build output** is generated by Vite in `client/dist/` and must be present in `server/public` for the NestJS server to serve the UI.
- **Development** uses `npm run dev` in the `server` directory with hot-reload on port 3000.
- **Production** deployments use the provided `Dockerfile` and [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml) after the build script has populated the static assets.

## Frequently Asked Questions

### What Node.js version is required to build TREK?

TREK requires **Node.js version 22 or higher**, as indicated by the version badge in the repository README. Attempting to build with earlier versions may result in compatibility errors with the React 19 or NestJS 11 dependencies.

### Can I build TREK manually without using the build-from-sources script?

Yes, you can manually install dependencies by running `npm ci` in both the `client` and `server` directories separately, then executing `npm run build` in the `client` directory. You must manually copy the resulting `client/dist/` contents into `server/public` to ensure the NestJS backend can serve the frontend files.

### How do I configure the server port when building from source?

The server listens on **port 3000** by default as implemented in the NestJS configuration. Set the `PORT` environment variable before starting the server (e.g., `PORT=8080 npm run dev`) to override this default when running locally or in Docker containers.

### Where are the compiled client files stored after building?

The Vite bundler places production files in **`client/dist/`**. The `build-from-sources` script automatically copies these files into **`server/public/`**, which is the directory the NestJS server statically serves in production. The `Dockerfile` expects this directory to exist when building the container image.