tilbudgivern/docs/deployment/DEPLOYMENT-PIPELINE.md

Tilbudgivern CI/CD Pipeline

Automated build, test, and deployment pipeline for the Tilbudgivern application using GitHub Actions.

Pipeline Overview

                    ┌─────────────────────────────────────────┐
                    │           GitHub Repository              │
                    └─────────────────────────────────────────┘
                                      │
          ┌───────────────────────────┼───────────────────────────┐
          │                           │                           │
          ▼                           ▼                           ▼
    ┌───────────┐             ┌───────────┐             ┌───────────┐
    │  Feature  │             │  Develop  │             │   Main    │
    │  Branch   │             │  Branch   │             │  Branch   │
    └───────────┘             └───────────┘             └───────────┘
          │                           │                           │
          ▼                           ▼                           ▼
    ┌───────────┐             ┌───────────┐             ┌───────────┐
    │    CI     │             │    CI     │             │    CI     │
    │  (Tests)  │             │  (Tests)  │             │  (Tests)  │
    └───────────┘             └───────────┘             └───────────┘
                                      │                           │
                                      ▼                           ▼
                              ┌───────────┐             ┌───────────┐
                              │  Deploy   │             │  Deploy   │
                              │   Test    │             │   Prod    │
                              └───────────┘             └───────────┘

Workflows

1. CI Workflow (ci.yml)

Triggers:

• Push to main, develop, feature/**, claude/** branches
• Pull requests to main or develop

Jobs:

Job	Description	Duration
lint	ESLint check for frontend and backend	~2 min
backend-tests	Jest unit tests with MariaDB service	~3 min
frontend-build	React production build	~3 min
e2e-tests	Playwright E2E tests (PRs only)	~5 min
security-scan	npm audit for vulnerabilities	~2 min

2. Test Deployment (deploy-test.yml)

Triggers:

• Push to develop branch
• Manual workflow dispatch

Jobs:

Job	Description
build	Build application package
deploy	Deploy to test server via SSH
verify	Health checks and API smoke tests
e2e-tests	Full E2E test suite on test environment

3. Production Deployment (deploy-prod.yml)

Triggers:

• Push to main branch
• Version tags (v*)
• Manual workflow dispatch

Jobs:

Job	Description
pre-deploy-checks	Version determination and validation
build	Production build with optimizations
deploy	Deploy with backup and atomic symlink
verify	Comprehensive health and API checks
smoke-tests	Critical path E2E tests
rollback	Automatic rollback on verification failure

Required Secrets

Test Environment

TEST_SERVER_HOST       # Test server hostname/IP
TEST_SERVER_USER       # SSH username
TEST_SERVER_PATH       # Deployment path (e.g., /var/www/tilbudgivern-test)
TEST_SSH_PRIVATE_KEY   # SSH private key for deployment
TEST_APP_URL           # Test environment URL

Production Environment

PROD_SERVER_HOST       # Production server hostname/IP
PROD_SERVER_USER       # SSH username
PROD_SERVER_PATH       # Deployment path (e.g., /var/www/tilbudgivern)
PROD_SSH_PRIVATE_KEY   # SSH private key for deployment
PROD_APP_URL           # Production URL (e.g., https://tilbudsgiveren.alw.dk)

Server Directory Structure

/var/www/tilbudgivern/
├── current/              # Symlink to active release
├── releases/             # Release versions
│   ├── prod-20260125-120000-abc1234/
│   ├── prod-20260124-150000-def5678/
│   └── ...
├── shared/               # Shared files across releases
│   └── .env              # Environment configuration
└── backups/              # Database and version backups
    ├── 20260125-120000/
    └── ...

Deployment Process

Test Environment

1. Build → 2. Upload → 3. Install deps → 4. Update symlink → 5. Restart PM2 → 6. Verify

Production Environment

1. Pre-checks → 2. Build → 3. Backup → 4. Upload → 5. Install deps → 6. Atomic symlink → 7. Graceful reload → 8. Verify → 9. Smoke tests

Manual Commands

Trigger Test Deployment

gh workflow run deploy-test.yml --ref develop

Trigger Production Deployment

# Deploy from main
gh workflow run deploy-prod.yml --ref main

# Deploy specific version
gh workflow run deploy-prod.yml -f version=v1.2.3

# Emergency deploy (skip E2E tests)
gh workflow run deploy-prod.yml -f skip_tests=true

Create Release Tag

git tag -a v1.2.3 -m "Release v1.2.3: Description"
git push origin v1.2.3

Rollback

Automatic Rollback

Production deployments automatically rollback if verification fails.

Manual Rollback

# SSH to server
ssh user@server

# List available releases
ls -la /var/www/tilbudgivern/releases/

# Rollback to specific version
ln -sfn /var/www/tilbudgivern/releases/prod-20260124-150000-def5678 /var/www/tilbudgivern/current
pm2 reload ecosystem.config.js

Environment Configuration

Test Environment (/var/www/tilbudgivern-test/shared/.env)

NODE_ENV=test
PORT=4032
DB_HOST=127.0.0.1
DB_USER=tilbuduser_test
DB_PASSWORD=xxx
DB_NAME=tilbudgivern_test
OPENAI_API_KEY=sk-xxx

Production Environment (/var/www/tilbudgivern/shared/.env)

NODE_ENV=production
PORT=4032
DB_HOST=127.0.0.1
DB_USER=tilbuduser
DB_PASSWORD=xxx
DB_NAME=tilbudgivern
OPENAI_API_KEY=sk-xxx
ORDRESTYRING_API_TOKEN=xxx

Monitoring

Health Check Endpoints

# Health check
curl https://tilbudsgiveren.alw.dk/api/health

# Full status
curl https://tilbudsgiveren.alw.dk/api/health | jq

PM2 Status

pm2 status tilbudgivern-unified
pm2 logs tilbudgivern-unified --lines 100
pm2 monit

View Deployment Logs

# GitHub Actions logs
gh run list --workflow=deploy-prod.yml
gh run view <run-id> --log

# Server logs
tail -f /var/www/tilbudgivern/current/.pm2/logs/tilbudgivern-unified-out.log

Troubleshooting

Build Failures

1. Check Node.js version compatibility (requires 18+)
2. Clear npm cache: npm cache clean --force
3. Delete node_modules and reinstall

Deployment Failures

1. Verify SSH connectivity: ssh user@server "echo connected"
2. Check disk space: df -h
3. Verify PM2 status: pm2 status
4. Check server logs: pm2 logs

Health Check Failures

1. Wait longer for server startup (increase sleep time)
2. Check database connectivity
3. Verify environment variables in shared/.env
4. Check PM2 error logs

Rollback Issues

1. Ensure previous release directory exists
2. Verify node_modules in previous release
3. Check shared .env file is accessible

Best Practices

1. Always deploy to test first before production
2. Use version tags for production releases
3. Monitor deployment via GitHub Actions UI
4. Check logs after deployment
5. Keep releases (last 10 production, 5 test)
6. Backup database before major changes
7. Use feature branches for development
8. Run full E2E suite on test environment

CI/CD Status Badges

Add to README.md:

![CI](https://github.com/alexpolo1/tilbudgivern/actions/workflows/ci.yml/badge.svg)
![Deploy Test](https://github.com/alexpolo1/tilbudgivern/actions/workflows/deploy-test.yml/badge.svg)
![Deploy Prod](https://github.com/alexpolo1/tilbudgivern/actions/workflows/deploy-prod.yml/badge.svg)