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

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.
• server/ – A NestJS 11 backend that serves the API and static files. Configuration resides in server/package.json.
• shared/ – Common TypeScript type definitions and utilities shared between client and server.

The root 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:

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:

   cd client
   npm ci
   npm run build

   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:

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

docker build -t mauriceboe/trek:dev .

Run the container with required volumes and environment variables:

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:

docker compose up -d

The 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 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.

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