DevOps & CI/CD

Document Purpose

This document describes the DevOps, CI/CD, and deployment strategy for Tripinger. It explains how code moves from local development through CI pipelines into development, staging, and production environments, and how infrastructure such as Docker, databases, caches, search, and external providers are coordinated.

Tripinger is a multi-surface platform (web, API, admin, partner portal) built on a TypeScript-centric stack with PostgreSQL, Redis, search, AI, and payment integrations. DevOps practices must support safe evolution of this system while protecting bookings, payments, and partner operations.

DevOps Overview

Tripinger’s architecture and environment documents define the basic shape:

• Applications:

• apps/web: public traveler-facing web app.

• apps/api: backend API (NestJS, Prisma, PostgreSQL).

• apps/admin: internal admin dashboard.

• apps/partner: partner portal.

• Infrastructure:

• PostgreSQL as primary database.

• Redis for caching and coordination.

• Elasticsearch/OpenSearch for search (planned).

• Object storage + media delivery (S3/Cloudinary).

• PayHere and Stripe for payments.

• Email, SMS/WhatsApp, OpenAI, Mapbox, and other external providers.

• Environments (from ENVIRONMENTS.md): local, development, staging, production, each with distinct URLs and integration modes.

DevOps connects these pieces via Git, GitHub Actions (or similar CI), Docker, environment configuration, and deployment hosts (AWS/Vercel/other).

Environment Model

ENVIRONMENTS.md defines the core environment matrix. DevOps must respect the following:

• Local: developer laptops; Docker for PostgreSQL/Redis/search, local API and frontends.
• Development: shared dev environment for integrating branches and verifying features.
• Staging: production-like environment for pre-release validation and beta users.
• Production: live customer environment with stricter monitoring, backups, and security.

Each environment has:

• Frontend URLs (e.g., dev, staging, production domains).
• API base URLs (e.g., https://dev-api..., https://staging-api..., production API).
• Separate database, cache, search, and provider credentials, managed via environment variables and platform dashboards.

DevOps workflows must ensure that:

• CI runs against test/CI databases, not production.
• Deployments target the correct environment hosts and secrets.
• Sensitive data is never copied casually between environments (for example, production DB into dev).

Repository and Branch Strategy

Tripinger uses a monorepo with dedicated app folders and shared docs.

Branches

A typical branch strategy for CI/CD:

• main: production-bound, protected branch.
• dev: integration branch for development environment deployments.
• feature/*: short-lived feature branches.

Flow

• Developers branch from dev, implement changes, and open PRs targeting dev.
• CI validates PRs (lint, tests, migration checks).
• Approved PRs merge into dev, triggering dev environment deploys.
• When ready for staging/production, changes are merged into main or tagged for release.

This structure supports separate deployment pipelines for dev, staging, and production while keeping a clean Git history.

CI/CD Pipeline Overview

GitHub Actions is the primary CI/CD system referenced by the documentation.

CI responsibilities

For every PR and branch push:

• Install dependencies and run linting.
• Run unit and integration tests for API and apps.
• Validate database migrations (for example, using Prisma migrate diff/deploy).
• Build apps (web/admin/partner/api) to catch compilation errors early.

CD responsibilities

On merges into dev or main (or on release tags):

• Build Docker images or frontend bundles.
• Apply database migrations to target environment (development, staging, production).
• Deploy API and worker services to the chosen host (AWS ECS, Railway, Supabase, etc.).
• Deploy frontends to Vercel (or equivalent) with environment-specific configuration.
• Run post-deploy smoke tests/health checks.

Example CI Workflow (Conceptual)

A simplified GitHub Actions CI job for the API might look like:

name: API CI

on:
  pull_request:
    paths:
      - "apps/api/**"
      - "docs/**"
      - ".github/workflows/**"
  push:
    branches: ["dev", "main"]
    paths:
      - "apps/api/**"

jobs:
  api-tests:
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:16
        ports: ["5432:5432"]
        env:
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
          POSTGRES_DB: tripinger_ci
      redis:
        image: redis:7
        ports: ["6379:6379"]

    env:
      DATABASE_URL: postgres://postgres:postgres@localhost:5432/tripinger_ci
      REDIS_URL: redis://localhost:6379
      NODE_ENV: test

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: pnpm install

      # Validate migrations
      - run: npx prisma migrate diff --from-empty --to-schema-file apps/api/prisma/schema.prisma --exit-code

      # Apply migrations to CI DB
      - run: npx prisma migrate deploy

      # Run tests
      - run: pnpm --filter api test

This pattern:

• Brings up PostgreSQL and Redis as services.
• Validates schema changes through migrate diff.
• Applies migrations to a clean CI DB.
• Runs tests in a reproducible environment.

Example CD Workflows (Dev, Staging, Prod)

Development environment deploy

name: Dev Deploy

on:
  push:
    branches: ["dev"]

jobs:
  deploy-dev-api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: pnpm install

      # Build API image or bundle
      - run: pnpm --filter api build

      # Apply migrations to dev DB
      - name: Apply DB migrations
        run: npx prisma migrate deploy
        env:
          DATABASE_URL: ${{ secrets.DEV_DATABASE_URL }}

      # Deploy API (placeholder step)
      - name: Deploy API to dev
        run: ./scripts/deploy-api-dev.sh
        env:
          DEV_API_HOST: ${{ secrets.DEV_API_HOST }}

  deploy-dev-web:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: pnpm install
      - run: pnpm --filter web build

      # Deploy to Vercel or similar
      - run: ./scripts/deploy-web-dev.sh
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}

Staging environment deploy

Staging deploys should be more controlled and may be tag-based:

name: Staging Deploy

on:
  push:
    tags:
      - "staging-*"

jobs:
  deploy-staging-api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: pnpm install
      - run: pnpm --filter api build

      - name: Apply DB migrations
        run: npx prisma migrate deploy
        env:
          DATABASE_URL: ${{ secrets.STAGING_DATABASE_URL }}

      - name: Deploy API to staging
        run: ./scripts/deploy-api-staging.sh
        env:
          STAGING_API_HOST: ${{ secrets.STAGING_API_HOST }}

      - name: Run post-deploy smoke tests
        run: pnpm --filter api test:e2e:staging

Production environment deploy

Production deploys should be gated (manual approval, limited schedule):

name: Production Deploy

on:
  workflow_dispatch:

jobs:
  deploy-prod-api:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: pnpm install
      - run: pnpm --filter api build

      - name: Apply DB migrations
        run: npx prisma migrate deploy
        env:
          DATABASE_URL: ${{ secrets.PROD_DATABASE_URL }}

      - name: Deploy API to production
        run: ./scripts/deploy-api-prod.sh
        env:
          PROD_API_HOST: ${{ secrets.PROD_API_HOST }}

      - name: Run post-deploy health checks
        run: pnpm --filter api test:e2e:prod

These workflows connect CI, migrations, and environment-specific deployment steps as described in architecture and database docs.

Docker and Local DevOps

DOCKER.md defines how local Docker and Compose should be used. DevOps must ensure local and CI workflows remain consistent.

Local services

Recommended local Docker services:

• PostgreSQL (required).
• Redis (required).
• Elasticsearch/OpenSearch (optional early, expected later).
• Optional API container, plus web/admin/partner containers if the team prefers.

Typical local commands

# Start core infrastructure
docker compose up -d postgres redis search

# Start full stack for local dev
docker compose up -d

# View services
docker compose ps

# Tail API logs
docker compose logs -f api

# Stop and remove volumes
docker compose down -v

Local workflows should align with environment docs (ports, URLs, env vars) so that dev, staging, and production behave predictably.

Database Migrations in DevOps

DATABASE-4.md and docs/database/MIGRATIONS.md define the database and migration strategy. DevOps must enforce those rules via CI and deployment.

Key requirements:

• Every schema change must have a migration file (Prisma-based).
• CI should run prisma migrate diff to detect untracked changes.
• CI or deploy jobs must run prisma migrate deploy against test/staging/prod DBs with proper backups/restore options.
• Destructive changes require staged rollout and extra validation.

DevOps scripts should:

• Fail builds when migrations cannot be applied or when diff shows uncommitted schema changes.
• Keep production migrations gated (manual approval or special workflows).

Secrets and Configuration Management

ENVIRONMENTS.md, DATABASE-4.md, and security sections emphasize strict handling of secrets.

Principles:

• All sensitive configuration (DB URLs, provider keys, JWT secrets) must be in environment variables or managed platform settings—not committed to Git.
• Separate env var sets per environment (local, dev, staging, prod).
• Rotate keys according to provider best practices and internal policies.
• Limit access to production secrets to a small set of trusted maintainers.

Examples (from API and environment docs):

• DATABASE_URL, REDIS_URL, ELASTICSEARCH_NODE.
• PAYHERE_MERCHANT_ID, PAYHERE_SECRET.
• STRIPE_SECRET_KEY.
• SENDGRID_API_KEY, TWILIO_ACCOUNT_SID.
• OPENAI_API_KEY, MAPBOX_ACCESS_TOKEN.
• JWT_ACCESS_SECRET, JWT_REFRESH_SECRET.

DevOps tooling (GitHub Actions, hosting platform) must be configured to inject these variables at runtime, with values stored in provider-side secret managers.

Observability and Operations

ARCHITECTURE.md highlights the need for operational visibility across bookings, payments, notifications, and search.

DevOps responsibilities include:

• Health endpoints (/health, /health/live, /health/ready) for API and services.
• Structured logging (request IDs, correlation IDs, JSON logs).
• Error tracking (for example, Sentry or similar) with safe context.
• Metrics for:
• Booking creation/failure rates.
• Payment success/failure/refund events.
• Notification delivery success/failure.
• Search indexing lag.
• Partner onboarding status.

In early phases, logging and basic health checks may be enough; as traffic grows, DevOps should add more detailed monitoring and alerting, especially for production.

Rollback and Recovery

DATABASE-4.md and environment docs emphasize backup and recovery direction.

DevOps must plan for:

• Automated backups (or point-in-time recovery) for production PostgreSQL.
• Clear procedures for restoring from backup (documented in Phase 3 ops docs later).
• Rollback strategies for deployments:
• Revert to previous application image/build on failure.
• Avoid database changes that are hard to roll back without restore.

For high-risk changes (schema, payments, booking logic):

• Prefer blue–green or canary deployments when possible.
• Monitor metrics closely after deploy; be ready to revert quickly.

Testing Alignment with DevOps

API and app READMEs define testing expectations; DevOps must integrate them into CI.

Priority flows to test in CI:

• Auth (registration, login, session flows).
• Hotel search and booking.
• Vehicle listing and booking.
• Payment intent and webhook handling.
• Partner onboarding and listing management.
• Admin verification and moderation actions.
• Planner creation and itinerary flows.

DevOps pipelines should run appropriate test suites (unit, integration, e2e) and fail fast on regressions.

DevOps Responsibilities Summary

To keep Tripinger reliable and safe, DevOps practices must ensure that:

• Environments are clearly separated and documented.
• CI validates code quality, migrations, and tests consistently.
• CD deploys changes predictably to dev, staging, and production with proper checks.
• Secrets are handled securely and environment-specific.
• Observability and rollback mechanisms are in place before serious production traffic.

This docs/DEVOPS.md is the Phase 1 foundation for those practices and will be refined as hosting choices, exact CI workflows, and operational tooling are finalized.