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

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, then deploy the resulting image via the provided 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 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
2. Test: Executes unit and integration tests using Vitest configured in 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 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 defines the entry points:

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, supporting server-side logic validation:

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, the build script bundles both frontend and backend:

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:

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:

docker compose pull
docker compose up -d

The repository includes a MCP.md file that documents required environment variables for health monitoring. Configure your pipeline to verify deployment health using these variables:

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

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

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:

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:

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

npm audit --audit-level=high

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

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

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

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 (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 for single-node deployments and the Helm chart in charts/ for Kubernetes orchestration.
• Vitest configuration in 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 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, and 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.

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