wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== GitLab CI/CD Documentation: Cotrav-Platform ======

===== 1. Project Overview =====

The **Cotrav-Platform** is built using a **Microservices Architecture**. This document provides the technical details of our automation pipeline, which handles building, testing, and deploying each service independently.

**Cotrav Platform** is a **monorepo-based system** that manages multiple backend services, shared libraries, and frontend applications in a single repository.

The repository is hosted on **GitLab** and uses **GitLab CI/CD** for automated build and deployment.

Main components of the platform:

  * Backend Microservices
  * Frontend UI
  * Shared Libraries
  * CI/CD Pipeline
  * Docker-based Deployment
  * NGINX Reverse Proxy

<file>
2. Infrastructure & Tools

</file>

We use the following stack to manage our operations:

**Version Control:**  GitLab

**CI/CD Engine:**  GitLab CI/CD (defined in ''.gitlab-ci.yml'')

**Containerization:**  Docker

**Registry:**  GitLab Container Registry

**Target Environment:**  etc

<code>
 Getting Started & Repository Setup

</code>

=== To begin working with the project, follow these steps to link your local code to the GitLab repository: ===

====== 2. Repository Structure (Monorepo) ======

<code>
cotrav-platform
│
├── Cotrav_Services # Backend microservices
│
├── Cotrav_UI # Frontend application
│
├── shared # Shared packages and utilities
│
├── gitlab/templates # CI/CD reusable templates
│
├── .gitlab-ci.yml # CI/CD pipeline configuration
│
├── package-lock.json
│
└── README.md

</code>

  * Step 1: Open your terminal and navigate to your project folder.

  * Step 2: Add the remote origin and push your code using these commands:

===== Add your files =====

  * [[https://docs.gitlab.com/user/project/repository/web_editor/#create-a-file|Create]] or [[https://docs.gitlab.com/user/project/repository/web_editor/#upload-a-file|upload]] files
  * [[https://docs.gitlab.com/topics/git/add_files/#add-files-to-a-git-repository|Add files using the command line]] or push an existing Git repository with the following command:
<code>

cd existing_repo
git remote add origin https://gitlab.com/cotrav-tech/cotrav-platform.git
git branch -M main
git push -uf origin main''

</code>

The pipeline configuration is defined in the ''.gitlab-ci.yml''  file located in the root of the repository.

This pipeline is optimized for a **monorepo architecture**, where multiple services exist in a single repository. The pipeline automatically detects which services have changed and triggers CI/CD only for those services.

The pipeline runs using **GitLab Runner**  with the runner tag:

<code>
Root - ''gitlab-ci.yml ''

</code>

GitLab runner— docker-runner01

<code>
Pipeline Stages

</code>

The pipeline consists of three main stages:

detect trigger post-deploy-cleanup

Each stage has a specific responsibility.

<code>
Stage 1 — Detect Changes

</code>

Job Name:

detect_changes

Purpose:

Detect which services or components have changed in the repository.

The pipeline compares the current commit with the previous commit using:

<code>
git diff

</code>

It then determines:

  * Which backend services have changed
  * Whether the frontend has changed
  * Whether shared packages changed

If shared packages change, all services are triggered.

==== Example Logic ====

<code>
FILES_CHANGED=$(git diff –name-only $BEFORE_SHA $CI_COMMIT_SHA)

</code>

The script then checks changes inside:

<code>
Cotrav_Services/services/
Cotrav_Services/environments/

</code>

If changes are detected, the pipeline dynamically generates a file:

<code>
trigger-pipeline.yml

</code>

This file contains the list of services whose pipelines should be triggered.

<code>
Artifact Generated

</code>

trigger-pipeline.yml

This artifact is passed to the next stage.

----

======   ======

Job Name:

<code>
Stage 2 — Trigger Service Pipelines

</code>

trigger_services

Purpose:

Trigger CI/CD pipelines for the services that changed.

This stage reads the generated file:

<code>
trigger-pipeline.yml

</code>

and dynamically includes service-specific pipeline configurations.

Example trigger:

<code>
trigger:
include:
- local: Cotrav_Services/services/auth-service/.gitlab-ci.yml  exmple ... flight , Hotel etc.

</code>

Each service maintains its own CI/CD configuration.

This allows:

  * Independent builds
  * Faster pipelines
  * Microservice-level deployment

----

======   ======

<code>
Stage 3 — Post Deploy Cleanup

</code>

cleanup-merged-branches

Purpose:

Automatically delete remote branches that have already been merged.

The script checks merged branches using:

<code>
git branch -r –merged origin/main –merged origin/production

</code>

Branches that are already merged into ''main''  or ''production''  are deleted automatically.

Protected branches are excluded:

<code>
main
production
test
dev

</code>

Example deletion command:

git push origin –delete branch-name

This keeps the repository clean by removing obsolete branches.

----

======   ======

<code>
Branch Rules

</code>

The pipeline runs only for specific branches.

For detection and service triggers:

dev production test

For branch cleanup:

main production

<file>
CI/CD Templates Documentation

</file>

===== Overview =====

The ''gitlab/templates''  directory contains reusable CI/CD pipeline templates used by different microservices in the **cotrav-platform**  monorepo.

These templates standardize the build, test, validation, and deployment processes across all services.

The pipelines are executed using **GitLab Runner**  and orchestrated through **GitLab CI/CD**.

Using templates ensures:

  * Consistent pipeline configuration
  * Reduced duplication
  * Easier maintenance
  * Scalable CI/CD architecture for microservices

======   ======

<file>
Template Directory Structure

gitlab/templates
│
├── build-service.yml
├── test-service.yml
├── validate-service.yml
├── deploy-service.yml
└── service-pipeline.yml

Each file represents a stage or workflow used by service pipelines.

</file>

----

<file>
1. build-service.yml

</file>

Purpose: Builds the service and prepares it for deployment.

Typical tasks include:

  * Installing dependencies
  * Compiling TypeScript
  * Building application artifacts
  * Creating Docker images

Example responsibilities:

Install dependencies Build application Prepare build artifacts

This template ensures every microservice follows the same build process.

----

<file>
2. test-service.yml

</file>

Purpose: Runs automated tests for the service.

Typical tasks:

  * Unit tests
  * Integration tests
  * Code quality checks

Example flow:

<code>
Install dependencies
Run test suite
Generate test reports

</code>

Testing ensures code stability before deployment.

----

<file>
3. validate-service.yml

</file>

Purpose: Validates the service configuration and code structure.

Validation checks may include:

  * Linting
  * Configuration validation
  * Dependency checks
  * Code formatting

Example:

<code>


</code>

Run linter Validate environment configuration Check dependencies

This stage prevents invalid code from progressing through the pipeline.

----

<file>
4. deploy-service.yml

</file>

Purpose: Deploys the service to the target environment.

Deployment tasks may include:

  * Building Docker containers using **Docker**
  * Pushing images to container registry
  * Running containers on the server
  * Restarting services
  * Updating **NGINX**  routing if required

Example deployment flow:

<code>
Build Docker image
Push image to registry
Run container on server
Verify deployment

</code>

----

<file>
5. service-pipeline.yml

</file>

Purpose: Defines the full pipeline for a microservice by combining the templates.

This file typically includes:

<code>
test
validate
build
deploy

</code>

Example pipeline order:

<code>
 test → build -> validate -> deploy

</code>

Each microservice includes this template to run its CI/CD pipeline.

----

======   ======

<code>
How Services Use Templates

</code>

Each microservice pipeline includes these templates using GitLab include syntax.

Example:

include: - local: gitlab/templates/service-pipeline.yml

This allows all services to share the same CI/CD logic.

<file>
CI/CD Template Architecture

</file>

<code>
Monorepo Pipeline
│
▼
Detect Changed Services
│
▼
Trigger Service Pipeline
│
▼
Service Pipeline
│
├── Validate Service
├── Build Service
├── Test Service
└── Deploy Service

</code>

----

====== Benefits of Template-Based Pipelines ======

==== Standardized CI/CD ====

All services follow the same pipeline structure.

==== Easier Maintenance ====

Updating one template updates pipelines for all services.

==== Faster Development ====

Developers don't need to write new CI/CD pipelines.

==== Scalable Architecture ====

New microservices can be added easily without creating new pipelin

<file>


</file>

====== Shared Module Documentation ======

===== Overview =====

The ''shared/''  directory contains reusable code, utilities, and deployment scripts that are used across multiple services in the **cotrav-platform**  monorepo.

This directory helps maintain consistency across services and avoids duplication of common functionality.

Shared modules are used by backend services located in:

<code>
Cotrav_Services/services/

</code>

This structure supports a scalable monorepo architecture integrated with **GitLab CI/CD**  pipelines.

----

====== Directory Structure ======

<file>
shared
│
├── common
│
└── scripts
└── deploy.sh

</file>

----

====== 1. common Directory ======

Purpose: Contains reusable modules or utilities shared across multiple services.

Typical contents may include:

  * Common helper functions
  * Shared configuration utilities
  * Logging utilities
  * Error handling modules
  * Middleware helpers

Example usage inside services:

<code>
import { logger } from "../../shared/common/logger"

</code>

Benefits:

  * Reduces duplicated code
  * Ensures consistent functionality across services
  * Makes maintenance easier

----

====== 2. scripts Directory ======

Purpose: Contains automation scripts used during deployment or CI/CD execution.

Example:

<code>
shared/scripts/deploy.sh

</code>

This script is typically executed by **GitLab Runner**  during the deployment stage of **GitLab CI/CD**  pipelines.

----

====== deploy.sh Script ======

Purpose: Automates deployment of services to the server.

Typical tasks performed:

  * Pull latest code or image
  * Stop existing containers
  * Build or pull new container images using **Docker**
  * Start new containers
  * Reload **NGINX**  if required

Example deployment flow:

<code>
Pull latest code
↓
Build Docker Image
↓
Stop old container
↓
Start new container
↓
Verify deployment

</code>

----

====== How Shared Modules Are Used ======

Services import utilities from the shared directory.

Example:

<code>
Cotrav_Services/services/auth-service
Cotrav_Services/services/user-service
Cotrav_Services/services/booking-service

</code>

Each service can reuse modules from:

<code>
shared/common

</code>

----

====== Architecture Diagram ======

Shared modules sit between services and utilities.

<code>
shared/common
│
│
┌────────────┼────────────┐
│ │ │
auth-service user-service booking-service
│ │ │
└────────────┴────────────┘

</code>

----

====== Benefits of Shared Modules ======

==== Code Reusability ====

Common logic is written once and reused everywhere.

==== Consistency ====

All services follow the same logging, error handling, and configuration standards.

==== Easier Maintenance ====

Updating shared modules automatically improves all services.

==== Faster Development ====

Developers can reuse existing utilities instead of rewriting code.

<file>


</file>

====== Deployment Script Documentation ======

===== Overview =====

''deploy.sh''  is the core deployment automation script used in the **cotrav-platform**  CI/CD pipeline.

The script is executed by **GitLab CI/CD**  runners to deploy backend services using **Docker**  and **Docker Compose**.

It supports:

  * Automated container deployment
  * Blue-Green production deployments
  * Automatic rollback on failure
  * Environment configuration loading
  * Nginx traffic switching
  * Health checks before switching traffic

This script enables **zero-downtime deployments**.

----

====== Deployment Flow ======

<file>
GitLab Pipeline │ │ ▼ deploy-service.yml │ │ ▼ deploy.sh │ ├── Load Environment ├── Pull Docker Image ├── Deploy Container ├── Health Check ├── Blue/Green Switch └── Nginx Reload

</file>

----

====== Script Arguments ======

The script accepts the following parameters:

<code>
deploy.sh <service_name> <environment> <docker_image> <docker_tag> <port> [env_file] [internal_port] [compose_file]

</code>

==== Example ====

<file>
./deploy.sh auth-service prod cotrav/auth-service v1.2.3 6001

</file>

----

====== Supported Environments ======

The deployment script supports three environments:

^Environment^Description|
|dev|Development environment|
|test|QA / testing environment|
|prod|Production environment with Blue-Green deployment|

----

====== Directory Structure Used ======

The script automatically manages directories inside:
<code>

/opt/cotrav/CICD_Pipeline

Structure:

CICD_Pipeline │ ├── services │ └── auth-service │ └── docker-compose.yml │ ├── environments │ └── auth-service │ └── prod │ └── .env │ └── logs └── auth-service └── prod

</code>

<code>


</code>

These directories store:

  * service configuration
  * environment variables
  * container logs

----

====== Blue-Green Deployment ======

Production deployments use a **Blue-Green strategy**.

Two containers run on different ports:

^Color^Port|
|Blue|6001|
|Green|6002|

Deployment process:
<file>


Current live → BLUE

New deployment
│
▼
Deploy GREEN container
│
▼
Run health checks
│
▼
Switch Nginx traffic
│
▼
GREEN becomes active

</file>

This ensures **zero downtime**.

----

====== Environment Variable Loading ======

Environment variables are loaded from:

<file>
/opt/cotrav/CICD_Pipeline/environments/<service>/<env>/.env

The script uses a **safe loader**  function:

safe_source()

</file>

Features:

  * ignores comments
  * ignores invalid keys
  * prevents arbitrary bash execution
  * supports quoted values

----

====== Docker Deployment Process ======

Deployment steps:

1️⃣ Pull Docker image

<code>
docker pull image:tag

</code>

2️⃣ Deploy container

<code>
docker compose up -d

</code>

3️⃣ Force recreate container

<code>
–force-recreate

</code>

4️⃣ Remove unused containers

<code>
–remove-orphans

</code>

----

====== Health Check System ======

Before traffic switching, the script performs **three layers of health checks**.

==== Layer 1 – Container State ====

Checks if container is running.

<code>
docker inspect

</code>

----

==== Layer 2 – Port Listening ====

Checks if service port is open.

<code>
ss -tln

</code>

----

==== Layer 3 – HTTP Health Endpoint ====

If available, checks:

<code>
/health

</code>

Example:

<code>
http://localhost:6001/health

</code>

Deployment proceeds only if all checks pass.

----

====== Automatic Rollback ======

If deployment fails, the script automatically rolls back.

Rollback logic:

<code>
Deployment fails
│
▼
Previous image detected
│
▼
Restart container using previous image

</code>

Example:

<code>
docker compose up -d –force-recreate

</code>

If no previous image exists:

<code>
docker compose down

</code>

----

====== Nginx Traffic Switching ======

After a successful deployment in production, the script switches traffic using **NGINX**.

Example configuration:

<code>
upstream auth-service {
server localhost:6001;
# server localhost:6002;
}

</code>

After deployment:

<file>
upstream auth-service {
# server localhost:6001;
server localhost:6002;
}

</file>

Then Nginx reloads:

<code>
nginx -s reload

</code>

----

====== Logging System ======

The script automatically creates structured logs:

<code>
logs/auth-service/prod
│
├── info
├── error
└── combined

</code>

Permissions are configured automatically during deployment.

----

====== Resource Limits ======

The script automatically configures container resource limits.

==== Production ====

<code>
MEM_LIMIT = 2G
CPU_LIMIT = 1.0
RESTART_POLICY = always

</code>

==== Dev / Test ====

<code>
MEM_LIMIT = 512M CPU_LIMIT = 0.5 RESTART_POLICY = on-failure

</code>

----

====== Network Configuration ======

All containers run in a shared Docker network:

<code>
cotrav-network

</code>

This allows services to communicate internally.

----

====== Deployment Success Output ======

If deployment succeeds:

<code>
DEPLOYMENT SUCCESSFUL
Service : auth-service
Env : prod
Image : cotrav/auth-service:v1.2.3
Port : 6002
Color : green

</code>

----

====== Key Benefits ======

==== Zero Downtime Deployments ====

Blue-Green deployment prevents service interruption.

==== Automatic Rollback ====

System recovers automatically if deployment fails.

==== Environment Isolation ====

Separate configuration for dev, test, and production.

==== Secure Environment Loading ====

Prevents execution of unsafe shell commands.

==== Automated Infrastructure ====

Deployment, logging, networking, and Nginx switching are fully automated.

====== Cotrav_Services Documentation ======

===== Overview =====

''Cotrav_Services''  is the backend monorepo that contains all microservices, shared packages, and deployment scripts for the Cotrav platform.

The repository is structured using a **monorepo architecture**  powered by **pnpm**  workspaces and **Turborepo**.

This setup allows multiple services and packages to share code efficiently while maintaining independent deployments.

----

====== Directory Structure ======

<file>
Cotrav_Services │ ├── packages │ ├── logger │ ├── errors │ ├── middlewares │ └── common │ ├── services │ ├── auth-service │ ├── user-service │ ├── booking-service │ └── other microservices │ ├── scripts │ └── deploy.sh │ ├── pnpm-workspace.yaml ├── turbo.json ├── tsconfig.json ├── package.json └── LICENSE

</file>

----

====== 1. packages Directory ======

===== Purpose =====

The ''packages''  folder contains **shared libraries**  used across all backend services.

These packages ensure:

  * Code reusability
  * Consistent architecture
  * Reduced duplication

==== Example Packages ====

^Package^Purpose|
|logger|Centralized logging system|
|errors|Custom error handling|
|middlewares|Express middleware utilities|
|common|Shared helper functions|

Example usage inside services:
<code>

import logger from "@cotrav/logger"

</code>

Benefits:

  * All services use the same logging system
  * Consistent error handling across APIs
  * Shared middleware architecture

----

====== 2. services Directory ======

===== Purpose =====

The ''services''  folder contains individual **microservices**.

Each service is:

  * independently deployable
  * containerized using **Docker**
  * deployed through **GitLab CI/CD**

Example services:

<code>
services
├── auth-service
├── user-service
├── booking-service
└── gateway-service

</code>

Each service typically contains:

<code>
auth-service
│
├── src
├── Dockerfile
├── package.json
├── tsconfig.json
└── .gitlab-ci.yml

</code>

Responsibilities of services:

  * handle business logic
  * expose REST APIs
  * communicate with databases
  * integrate with other services

----

====== 3. scripts Directory ======

===== Purpose =====

The ''scripts''  directory contains deployment automation tools.

Example:

<file>
scripts
└── deploy.sh

</file>

The ''deploy.sh''  script is used in production deployments.

It performs:

  * Docker container deployment
  * Blue-Green deployment
  * Health checks
  * Rollback on failure
  * Traffic switching via **NGINX**

----

====== 4. pnpm-workspace.yaml ======

This file defines the **monorepo workspace configuration**.

Example:

<file>
packages:
- "packages/*"
- "services/*"

This allows all services and packages to share dependencies using **pnpm**.

</file>

Benefits:

  * Faster installations
  * Disk space optimization
  * Dependency deduplication

----

====== 5. turbo.json ======

''turbo.json''  configures **build pipelines**  using **Turborepo**.

Example pipeline tasks:

<file>
build
lint
test
dev

</file>

Turborepo provides:

  * parallel builds
  * caching
  * dependency graph optimization

----

====== 6. TypeScript Configuration ======

The project uses shared TypeScript configuration.

Files:

<code>
tsconfig.base.json
tsconfig.json

</code>

Purpose:

  * shared compiler settings
  * consistent TypeScript rules
  * simplified service setup

----

====== Monorepo Architecture Diagram ======

<code>
Cotrav Platform Monorepo
│
│
Cotrav_Services
│
┌─────────────────┴─────────────────┐
│ │
packages services
│ │
logger / errors / middlewares auth-service
common utilities booking-service
user-service
gateway

</code>

----

====== Backend Infrastructure ======

<code>
Internet
│
▼
Nginx Gateway
│
▼
Microservices (Docker Containers)
│
├── auth-service
├── Hotel-service
└── flight-service

</code>

----

====== Advantages of This Architecture ======

==== Scalable Microservices ====

Services can be deployed independently.

==== Code Reusability ====

Shared packages prevent code duplication.

==== Faster Builds ====

Caching and parallel builds using **Turborepo**.

==== Efficient Dependency Management ====

Handled by **pnpm**.

==== Production-Ready Deployment ====

Automated CI/CD pipeline with **GitLab CI/CD**.

=====   =====

===== Impliments to exmaple CICD ROOT SERVICES CICD =====


====== Auth Service Documentation Exmaple.. ======


===== Overview =====

''auth-service''  is a microservice responsible for authentication and authorization within the Cotrav platform.

It is built using **Node.js**  and containerized using **Docker**.  The service is deployed through **GitLab CI/CD**  pipelines.

Responsibilities of this service include:

  * User authentication
  * Token generation
  * Authorization middleware
  * Secure API access

----

====== Service Folder Structure ======

<code>


</code>

<code>

auth-service │ ├── src │ ├── controllers │ ├── routes │ ├── services │ ├── middlewares │ └── index.ts │ ├── Dockerfile ├── docker-compose.yml ├── nginx.conf ├── .gitlab-ci.yml ├── package.json ├── pnpm-lock.yaml └── tsconfig.json

</code>

----


====== Source Code (src) ======

<file>
The ''src''  directory contains the core application logic.

Typical structure:

src │ ├── controllers # API request handlers ├── routes # Express route definitions ├── services # Business logic layer ├── middlewares # Authentication & validation └── index.ts # Application entry point

</file>


==== Responsibilities ====

^Component^Description|
|Controllers|Handle incoming HTTP requests|
|Routes|Define API endpoints|
|Services|Business logic implementation|
|Middlewares|Authentication and request validation|

----

====== Dockerfile ======

The ''Dockerfile'' defines how the service container is built using **Docker**.

Responsibilities:

  * Install dependencies
  * Build TypeScript code
  * Start the Node.js application

Example workflow:

<code>
Build Image ↓ Install Dependencies ↓ Compile TypeScript ↓ Run Service

</code>

----


====== docker-compose.yml ======

<file>
''docker-compose.yml''  is used for **local development and testing**.

It allows developers to quickly run the service with required dependencies.

Example usage:

docker-compose up -d

</file>

Benefits:

Container orchestration for development

Easy local setup

Environment configuration

----


====== nginx.conf ======

The ''nginx.conf'' file configures **NGINX** to route traffic to the service container.

Responsibilities:

  * Reverse proxy configuration
  * Load balancing
  * Port routing
  * Security headers

Traffic flow:

<code>
Client Request │ ▼ Nginx Reverse Proxy │ ▼ Auth Service Container

</code>

----


====== .gitlab-ci.yml ======

The ''.gitlab-ci.yml'' file defines the **CI/CD pipeline** for the auth-service using **GitLab CI/CD**.

Pipeline stages may include:

  - Validate service
  - Run tests
  - Build Docker image
  - Push image to registry
  - Deploy service

Example pipeline flow:

<code>
Code Push │ ▼ GitLab Pipeline │ ├── Install Dependencies ├── Run Tests ├── Build Docker Image ├── Push Image ▼ Deployment

</code>
==== Project: Cotrav Services – Auth Service ====

===== 1. Overview =====

This project implements a **CI/CD pipeline using GitLab CI**  to automate the process of:

  * Testing
  * Building
  * Validating
  * Deploying
  * Cleaning Docker images

The pipeline is designed for a **Monorepo Microservices Architecture**  where multiple services exist inside a single repository. The pipeline specifically handles deployment for the **Auth Service**.

----

====== 2. Pipeline Architecture ======

The CI/CD pipeline contains the following stages:

<code>Developer Push Code
│
▼
GitLab Repository
│
▼
GitLab Runner (docker-runner01)
│
▼
TEST → BUILD → VALIDATE → DEPLOY → CLEANUP
│
▼
Docker Image Build
│
▼
Push to GitLab Container Registry
│
▼
SSH Deployment to Server

</code>

----

====== 3. Pipeline Stages ======

===== Stage 1 — Test =====

<code>
test-auth

</code>

This stage runs automated tests before building the service.

Purpose:

  * Verify code functionality
  * Prevent broken builds
  * Ensure stability before deployment

The job extends a reusable template:

<code>
extends: .base_test_job

</code>

The runner used:

<code>
tags:
- docker-runner01

</code>

----


====== 4. Stage 2 — Build ======

<code>build-auth

</code>

Purpose:

  * Build the Auth service
  * Create Docker image
  * Push image to GitLab Container Registry

Dependency:

<code>needs: ["test-auth"]

</code>

Build only runs after **tests pass**.

Docker image naming format:

<code>auth-service-${branch}-V02-${commit}

</code>

Example:

<code>auth-service-dev-V02-a23f9c

</code>

----

====== 5. Stage 3 — Validate ======

<code>validate-auth

</code>

Purpose:

  * Validate Docker image
  * Ensure artifacts are correct
  * Check build integrity

Dependency:

<code>needs:
- build-auth

</code>

Artifacts from build are used for validation.

----

====== 6. Deployment Strategy ======

Deployment is automated using **SSH + Docker**.

Pipeline supports **3 environments**:

^Environment^Branch^Port|
|Dev|dev|4001|
|Test|test|4002|
|Production|production|4003|

----

====== 7. Dev Deployment ======

Job:
<code>
deploy-dev

</code>

Runs automatically when:

<code>branch == dev

</code>

Configuration:

<code>PORT=4001
INTERNAL_PORT=3000

</code>

This deploys the container to the development environment.

----

====== 8. Test Deployment ======

Job:

<code>deploy-test

</code>

Runs when:

<code>branch == test

</code>

Deployment is **manual approval based**:

<code>when: manual

</code>

Configuration:

<code>PORT=4002

</code>

This allows QA or testing before production release.

----

====== 9. Production Deployment ======

Job:

<code>deploy-prod

</code>

Production deployment uses **Blue-Green Deployment Strategy**.

Configuration:

<code>ex - BLUE_PORT=4003
GREEN_PORT=4004

</code>

Benefits:

  * Zero downtime deployment
  * Safe rollback
  * High availability

Deployment is also **manual approval based**.

----

====== 10. Pipeline Rules ======

Pipeline runs only if **relevant files change**.

<code>changes:
- Cotrav_Services/packages/**/*
- Cotrav_Services/services/auth-service/**/*
- Cotrav_Services/pnpm-lock.yaml
- Cotrav_Services/package.json

</code>

Benefits:

  * Faster pipeline
  * Avoid unnecessary builds

----

====== 11. Caching Strategy ======

Pipeline uses **PNPM caching**  to speed up builds.

<code>cache:
key: pnpm-cache-$CI_COMMIT_REF_SLUG

</code>

Cached directories:

<code>Cotrav_Services/.pnpm-store
Cotrav_Services/node_modules
node_modules

</code>

Benefits:

  * Faster dependency installation
  * Reduced CI runtime

----

====== 12. Docker Build Optimization ======

<code>DOCKER_BUILDKIT: "1"

</code>

BuildKit improves:

  * Docker build performance
  * Layer caching
  * Parallel builds

----

====== 13. Environment Variables ======

Important pipeline variables:

^Variable^Purpose|
|RUNNER_TAG|Runner to execute jobs|
|SERVICE_PATH|Path to service|
|DOCKER_IMAGE|Docker registry image|
|DOCKER_TAG|Unique build tag|
|REMOTE_BASE_PATH|Deployment directory|
|ENV_CONTENT|Encoded environment file|

Environment file is stored securely in GitLab CI variables:
<code>
AUTH_SERVICE_ENV_BASE64  /   this add cicd varible

</code>

----

====== 14. Cleanup Stage ======

<code>cleanup-registry

</code>

Purpose:

Remove old Docker images from the registry.

Command used:

<code>glab registry delete

</code>

Configuration:

<code>--keep-n 5

</code>

Meaning:

Only **latest 5 images are kept**.

Benefits:

  * Saves registry storage
  * Maintains clean image history

----

====== 15. GitLab Templates ======

Pipeline uses reusable templates:

<file>

gitlab/templates/test-service.yml
gitlab/templates/build-service.yml
gitlab/templates/validate-service.yml
gitlab/templates/deploy-service.yml

</file>

Advantages:

  * Reusable CI logic
  * Cleaner ''.gitlab-ci.yml''
  * Easy to scale for multiple services

----

====== 16. Monorepo Structure ======

Example project structure:

<file>
Cotrav_Services
│
├── packages
│ ├── logger
│ ├── errors
│ └── middlewares
│
├── services
│ └── auth-service
│
├── scripts
│
├── pnpm-workspace.yaml
├── turbo.json
└── package.json

Tools used:
PNPM TurboRepo TypeScript

</file>

<file>
include:
  - local: gitlab/templates/test-service.yml
  - local: gitlab/templates/build-service.yml
  - local: gitlab/templates/validate-service.yml
  - local: gitlab/templates/deploy-service.yml

variables:
  RUNNER_TAG: "docker-runner01"
  DOCKER_BUILDKIT: "1"
  MONOREPO_ROOT: "Cotrav_Services"
  SERVICE_PATH: "Cotrav_Services/services/auth-service"
  BASE_SERVICE_NAME: "auth-service"
  VERSION_NUMBER: "V02"
  DOCKER_IMAGE: "$CI_REGISTRY_IMAGE/auth-service"
  DOCKER_TAG: "auth-service-${CI_COMMIT_REF_SLUG}-V02-${CI_COMMIT_SHORT_SHA}"
  REMOTE_BASE_PATH: "/opt/cotrav/CICD_Pipeline"
  ENV_CONTENT: "$AUTH_SERVICE_ENV_BASE64"

stages:
  - test
  - build
  - validate
  - deploy
  - cleanup

cache:
  key: "pnpm-cache-$CI_COMMIT_REF_SLUG"
  paths:
    - "Cotrav_Services/.pnpm-store"
    - "Cotrav_Services/node_modules"
    - "node_modules"
  policy: pull-push

.auth-service_rules: &auth_rules
  rules:
    - if: '$CI_COMMIT_BRANCH == "dev" || $CI_COMMIT_BRANCH == "test" || $CI_COMMIT_BRANCH == "production"'
      changes:
        - "Cotrav_Services/packages/**/*"
        - "Cotrav_Services/services/auth-service/**/*"
        - "Cotrav_Services/pnpm-lock.yaml"
        - "Cotrav_Services/package.json"
# ...

# ─── TEST ────────────────────────────────────────────────
test-auth:
  extends: .base_test_job
  tags:
    - "$RUNNER_TAG"
  <<: *auth_rules

# ─── BUILD ───────────────────────────────────────────────
build-auth:
  extends: .base_build_job
  needs: ["test-auth"]
  tags:
    - "$RUNNER_TAG"
  <<: *auth_rules

# ─── VALIDATE ────────────────────────────────────────────
validate-auth:
  extends: .base_validate_job
  stage: validate
  needs:
    - job: build-auth
      artifacts: true
  tags:
    - "$RUNNER_TAG"
  <<: *auth_rules

# ─── DEPLOY DEV ──────────────────────────────────────────
deploy-dev:
  extends: .base_deploy_job
  needs:
    - job: build-auth
      artifacts: true
    - job: validate-auth
      artifacts: true
  variables:
    SERVICE_NAME: "auth-service"
    TARGET_ENV: "dev"
    DEPLOY_SERVER_IP: "$DEV_IP"
    SSH_USER: "root"
    PORT: "4001"
    INTERNAL_PORT: "3000"
  environment:
    name: dev/auth-service
  rules:
    - if: '$CI_COMMIT_BRANCH == "dev"'

# ─── DEPLOY TEST ─────────────────────────────────────────
deploy-test:
  extends: .base_deploy_job
  needs:
    - job: build-auth
      artifacts: true
    - job: validate-auth
      artifacts: true
  variables:
    SERVICE_NAME: "auth-service"
    TARGET_ENV: "test"
    DEPLOY_SERVER_IP: "$DEV_IP"
    SSH_USER: "root"
    PORT: "4002"
    INTERNAL_PORT: "3000"
  environment:
    name: test/auth-service
  rules:
    - if: '$CI_COMMIT_BRANCH == "test"'
      when: manual

# ─── DEPLOY PROD ─────────────────────────────────────────
deploy-prod:
  extends: .base_deploy_job
  needs:
    - job: build-auth
      artifacts: true
    - job: validate-auth
      artifacts: true
  variables:
    SERVICE_NAME: "auth-service"
    TARGET_ENV: "prod"
    DEPLOY_SERVER_IP: "$DEV_IP"
    SSH_USER: "root"
    BLUE_PORT: "4003"
    GREEN_PORT: "4004"
    PORT: "4003"
    INTERNAL_PORT: "3000"
  environment:
    name: prod/auth-service
  rules:
    - if: '$CI_COMMIT_BRANCH == "production"'
      when: manual

# ─── CLEANUP ─────────────────────────────────────
cleanup-registry:
  stage: cleanup
  image: registry.gitlab.com/gitlab-org/cli:latest
  script:
    - echo "Cleaning up old images for $BASE_SERVICE_NAME"
    - glab registry delete "$CI_PROJECT_PATH" --name "$BASE_SERVICE_NAME" --keep-n 5 --yes || true
  rules:
    - if: '$CI_COMMIT_BRANCH == "production"'
      when: on_success
  allow_failure: true

</file>

----


====== 17. Deployment Server ======

Deployment server path:

<code>/opt/cotrav/CICD_Pipeline

</code>

Deployment method:

<code>GitLab Runner → SSH → Docker Container

</code>

----

====== 18. Advantages of This Pipeline ======

  * Automated testing
  * Automated Docker build
  * Monorepo support
  * Environment based deployment
  * Blue-Green production deployment
  * Docker registry cleanup
  * Faster builds using caching

----

====== 19. Technologies Used ======

^Technology^Purpose|
|GitLab CI/CD|Pipeline automation|
|Docker|Containerization|
|PNPM|Dependency management|
|TurboRepo|Monorepo build system|
|TypeScript|Backend development|
|Nginx|Reverse proxy|
|SSH|Remote deployment|

----


====== Deployment Architecture ======

The service runs inside Docker containers and is exposed through **NGINX**.
<file>
Internet │ ▼ Nginx Gateway │ ▼ Auth Service Container

</file>

----


====== Configuration Files ======

^File^Purpose|
|package.json|Node.js project configuration|
|pnpm-lock.yaml|Dependency lock file|
|tsconfig.json|TypeScript compiler configuration|

Dependencies are managed using **pnpm**.

----

====== Integration with Monorepo ======

''auth-service'' is part of the backend monorepo managed by **Turborepo**.

Shared packages from the monorepo can be used inside the service:

Example:

<code>
import logger from "@cotrav/logger"

</code>

----


====== Advantages of This Setup ======

  * Microservice architecture
  * Containerized deployment
  * Automated CI/CD pipeline
  * Scalable infrastructure
  * Shared code through monorepo packages