# How to Set Up a TREK CI/CD Pipeline: Complete Guide for the Travel-Ready Enterprise Kit

> Learn to set up a TREK CI/CD pipeline automating linting, type-checking, testing, and Docker builds. Deploy easily with docker-compose or Helm charts.

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

---

**To set up a TREK CI/CD pipeline, automate linting, type-checking, Vitest testing, and Docker builds using the npm scripts defined in [`shared/package.json`](https://github.com/mauriceboe/TREK/blob/main/shared/package.json), then deploy the resulting image via the provided [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml) or Helm charts.**

The **mauriceboe/TREK** (Travel-Ready Enterprise Kit) repository is a full-stack TypeScript travel planning application designed to run as a Docker container. Because the codebase includes a multi-stage `Dockerfile`, predefined npm scripts for quality assurance, and deployment configurations for both Docker Compose and Kubernetes, you can set up a TREK CI/CD pipeline using any CI system that supports containerized workflows. This guide demonstrates how to orchestrate linting, testing, building, and deployment while leveraging the repository's existing build infrastructure.

## Prerequisites

Before configuring your pipeline, ensure your environment meets these requirements:

- **Docker** and **Docker Compose** installed on build agents
- **Node.js 20** or later (specified in [`shared/package.json`](https://github.com/mauriceboe/TREK/blob/main/shared/package.json) engines)
- Access to a container registry (Docker Hub, GitHub Container Registry, or private registry)
- For Kubernetes deployments: `kubectl` and Helm configured

## Pipeline Architecture Overview

A production-ready TREK CI/CD pipeline consists of six distinct stages. Each stage leverages specific files from the repository:

1. **Lint & Type-Check**: Enforces code style using `shared/eslint.config.mjs` and validates TypeScript via [`shared/tsconfig.json`](https://github.com/mauriceboe/TREK/blob/main/shared/tsconfig.json)
2. **Test**: Executes unit and integration tests using Vitest configured in [`server/vitest.config.ts`](https://github.com/mauriceboe/TREK/blob/main/server/vitest.config.ts)
3. **Build**: Compiles the client and server into the `dist/` directory using `npm run build`
4. **Containerize**: Creates a lightweight image using the multi-stage `Dockerfile` at the repository root
5. **Publish**: Tags and pushes the image to your registry
6. **Deploy**: Updates the running stack using [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml) or the Helm chart in `charts/`

## Step-by-Step Implementation

### Stage 1: Lint and Type Checking

The quality assurance stage runs static analysis without executing the application. The [`shared/package.json`](https://github.com/mauriceboe/TREK/blob/main/shared/package.json) defines the entry points:

```bash
npm run lint       # Uses shared/eslint.config.mjs

npm run type-check # Uses shared/tsconfig.json

```

These commands validate the entire monorepo, ensuring consistent code style and catching type errors before they reach production.

### Stage 2: Testing with Vitest

TREK uses Vitest for unit and integration testing. The configuration resides in [`server/vitest.config.ts`](https://github.com/mauriceboe/TREK/blob/main/server/vitest.config.ts), supporting server-side logic validation:

```bash
npm test

```

This command executes all test suites, providing coverage reports essential for maintaining code quality during continuous integration.

### Stage 3: Building the Application

The build process compiles TypeScript sources into executable JavaScript. According to [`shared/package.json`](https://github.com/mauriceboe/TREK/blob/main/shared/package.json), the build script bundles both frontend and backend:

```bash
npm run build

```

This executes `npm run build:client && npm run build:server`, outputting artifacts to the `dist/` directory. These compiled files are then copied into the Docker image during the containerization stage.

### Stage 4: Docker Image Creation

The repository includes a multi-stage `Dockerfile` that optimizes the final image size. The build copies the compiled `dist/` folder into a lightweight `node:alpine` runtime:

```bash
docker build -t trekworld/trek:${GITHUB_SHA} .

```

This approach separates the build environment (with full TypeScript compiler) from the runtime environment, resulting in a production image that contains only the necessary compiled code and dependencies.

### Stage 5: Deployment and Health Monitoring

For Docker Compose environments, the pipeline updates the running stack by pulling the new image and restarting services:

```bash
docker compose pull
docker compose up -d

```

The repository includes a [`MCP.md`](https://github.com/mauriceboe/TREK/blob/main/MCP.md) file that documents required environment variables for health monitoring. Configure your pipeline to verify deployment health using these variables:

```bash
curl -f http://localhost:3000/health || exit 1

```

For Kubernetes deployments, use the Helm chart located in `charts/`:

```bash
helm upgrade --install trek ./charts --set image.tag=${GITHUB_SHA}

```

## Complete GitHub Actions Workflow

Below is a reference implementation using GitHub Actions that orchestrates the stages above. This workflow triggers on pushes to `main` and version tags:

```yaml
name: CI/CD

on:
  push:
    branches: [main]
    tags: ['v*']
  pull_request:
    branches: [main]

jobs:
  build-test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Lint
        run: npm run lint

      - name: Type-check
        run: npm run type-check

      - name: Run tests
        run: npm test

      - name: Build
        run: npm run build

      - name: Build Docker image
        run: docker build -t trekworld/trek:${{ github.sha }} .

  publish:
    needs: build-test
    runs-on: ubuntu-latest
    if: github.ref_type == 'tag'
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Log in to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USER }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Tag and push
        run: |
          docker tag trekworld/trek:${{ github.sha }} trekworld/trek:latest
          docker push trekworld/trek:${{ github.sha }}
          docker push trekworld/trek:latest

  deploy:
    needs: publish
    runs-on: self-hosted
    if: github.ref_type == 'tag'
    steps:
      - name: Deploy with Docker Compose
        run: |
          cd /opt/trek
          docker compose pull
          docker compose up -d

      - name: Health check
        run: curl -f http://localhost:3000/health || exit 1

```

## Local Verification

Developers can run the exact same checks locally that the CI executes, ensuring failures are caught before commits reach the pipeline:

```bash

# Install dependencies

npm ci

# Run quality checks

npm run lint
npm run type-check

# Execute test suite

npm test

# Verify build

npm run build

# Test Docker build locally

docker build -t trek:local .

```

## Plugin Validation and Optional Enhancements

Extend the base pipeline with these additional capabilities:

**Security Scanning**
Add vulnerability scanning after dependency installation:

```bash
npm audit --audit-level=high

```

**Plugin Registry Validation**
If extending TREK with plugins, incorporate the repository's validation scripts before deployment:

```bash
node scripts/validate-entry.mjs
node scripts/check-readme.mjs

```

You can also use the TREK plugin CLI for preflight checks:

```bash
trek-plugin validate ./my-plugin
trek-plugin preflight --repo myorg/trek-plugin --tag v1.2.3

```

**Rollback Strategy**
Tag images with both the Git SHA and `latest`, allowing rapid rollback by reverting to the previous stable image tag in your deployment configuration.

## Summary

- **TREK CI/CD pipelines** leverage the npm scripts in [`shared/package.json`](https://github.com/mauriceboe/TREK/blob/main/shared/package.json) (`lint`, `type-check`, `test`, `build`) to ensure consistency between local development and CI environments.
- The **multi-stage `Dockerfile`** creates optimized production images by separating the TypeScript build environment from the Node.js runtime.
- **Deployment flexibility** is provided through both [`docker-compose.yml`](https://github.com/mauriceboe/TREK/blob/main/docker-compose.yml) for single-node deployments and the Helm chart in `charts/` for Kubernetes orchestration.
- **Vitest configuration** in [`server/vitest.config.ts`](https://github.com/mauriceboe/TREK/blob/main/server/vitest.config.ts) enables comprehensive testing of server-side logic as part of the pipeline.
- Reference scripts like `scripts/validate-entry.mjs` and `scripts/check-readme.mjs` support plugin registry validation when extending TREK functionality.
- Environment variables and health check configurations defined in [`MCP.md`](https://github.com/mauriceboe/TREK/blob/main/MCP.md) ensure proper monitoring of deployed instances.

## Frequently Asked Questions

### What CI systems can I use with TREK?

You can use any CI system that supports Docker and Node.js, including GitHub Actions, GitLab CI, Azure Pipelines, Jenkins, and CircleCI. The repository's structure relies on standard npm scripts and Docker commands, making it portable across platforms without vendor-specific configuration.

### How do I run the same checks locally before pushing?

Run `npm ci` followed by `npm run lint`, `npm run type-check`, and `npm test`. These commands use the same configuration files (`shared/eslint.config.mjs`, [`shared/tsconfig.json`](https://github.com/mauriceboe/TREK/blob/main/shared/tsconfig.json), and [`server/vitest.config.ts`](https://github.com/mauriceboe/TREK/blob/main/server/vitest.config.ts)) that the CI pipeline uses, ensuring identical results.

### Can I deploy TREK to Kubernetes instead of Docker Compose?

Yes. The repository includes a Helm chart in the `charts/` directory. Replace the Docker Compose deployment steps in your pipeline with `helm upgrade --install` commands, using the same image tag generated during the build stage.

### How do I validate TREK plugins in the CI pipeline?

Use the repository's validation scripts located in `scripts/validate-entry.mjs` and `scripts/check-readme.mjs`. These scripts verify plugin metadata and documentation requirements, ensuring third-party extensions meet the registry standards before deployment.