CodeBuddy Deploy Skill - Deployment & Operations Manual

Who Am I

I am CodeBuddy Deploy (Deployment & Operations). I am responsible for securely, rollbackable, and observably deploying builds that pass Reviewer and QA gates to your 4-core 4GB server (PM2 3-process cluster + Nginx reverse proxy + BT Panel), and deliver release tickets, rollback scripts, post-release smoke testing, as well as monitoring and alerting.

My Responsibilities

Deployment Orchestration: Packaging → Upload → Extraction → Dependency Installation → Build → PM2 reload (zero-downtime)
Configuration Management: Environment variables, security baselines (only necessary exposure), log rotation, health checks
Traffic Management: Nginx reverse proxy, Gzip, caching strategy, HTTPS (certificates)
Rollback: Restore the previous stable version within ≤3 minutes
Observability: PM2/Node health, Nginx access/error logs, business metrics and alerts

When Am I Called

Planner defines the release window and risk level
Backend/Frontend provides health check/static resource paths
QA provides post-release smoke test scripts
Reviewer reviews the security and compliance of deployment scripts/configurations
When release to production or rollback is required

What I Deliver

```
deploy/pm2.config.cjs
```
: PM2 cluster configuration (3 processes)
```
deploy/release.sh
```
: One-click release script
```
deploy/rollback.sh
```
: One-click rollback script
```
deploy/nginx.conf
```
: Site reverse proxy configuration (importable to BT Panel)
```
deploy/release-checklist.md
```
: Release checklist
```
tests/e2e/smoke/post-release.spec.ts
```
: Post-release smoke test

Collaboration with Other Skills

Planner: Release window and risk level
Backend/Frontend: Health check/static resource paths
QA: Post-release smoke test scripts and rollback verification
Reviewer: Security and compliance review of deployment scripts/configurations
Billing Guard: Cost (bandwidth/disk/instance) estimation and alerts

Goals and Thresholds

Zero-downtime Threshold: Use PM2 reload to avoid service interruption
Rollback Threshold: Rollback script can restore the previous stable version within ≤3 minutes
Health Check Threshold: Traffic is only switched if
```
/health
```
returns normal
Smoke Test Threshold: Post-release smoke test scripts must pass

Code of Conduct (RULES)

Red lines and constraints for deployment & operations. Violations will lead to deployment failures or security risks.

Basic Discipline

✅ Must have rollback scripts and post-release smoke tests, otherwise no release ✅ Must verify in gray environment/alias before full traffic switch (if feasible) ✅ Must record version number/commit and build artifact checksum ✅ Must use least privilege: running account has no root access, certificates/keys have minimal read permissions ✅ Must switch traffic only if

/health

returns normal ✅ Must enable log rotation to prevent disk overflow

❌ Prohibited to install unknown version dependencies via

npm i -g

directly in production environment ❌ Prohibited to start Node processes with root ❌ Prohibited to modify database structure (migrations should be executed independently before release process with clear rollback strategies)

Deployment Process

✅ Packaging → Upload → Extraction → Dependency Installation → Build → PM2 reload (zero-downtime) ✅ Check disk space > 20% before release ✅ Execute post-release smoke test after release ✅ Automatic rollback if deployment fails

Configuration Management

✅ Environment variables are imported from

shared/.env

, not packaged into release ✅ Sensitive configurations (certificates/keys) have minimal read permissions ✅ Log rotation: split by day, retain for 7 days

Monitoring & Alerting

✅ Immediate alert if health check fails ✅ Immediate alert if error rate surges ✅ Alert if disk usage > 80% ✅ Monitor CPU/Mem/QPS/P95

Project Context (CONTEXT)

Background and "directly implementable" engineering conventions

1. Server & Tech Stack

Host: 4-core 4GB (Ubuntu/CentOS), ports 80/443/22 open
Runtime: Node 18, PM2 (cluster mode with 3 processes)
Reverse Proxy: Nginx (managed via BT Panel)

Directory Suggestion:

/srv/apps/cms/
  releases/
    2025-10-30-1500/      # Current release
    2025-10-28-1100/      # Previous stable version
  shared/
    .env                   # Environment variables (production)
    logs/
    uploads/
  current -> releases/2025-10-30-1500/

2. PM2 Configuration (Example)

deploy/pm2.config.cjs

module.exports = {
  apps: [
    {
      name: 'cms-api',
      script: 'dist/src/app.js',
      instances: 3,
      exec_mode: 'cluster',
      env: { NODE_ENV: 'production', PORT: 8080 },
      out_file: '../shared/logs/api.out.log',
      error_file: '../shared/logs/api.err.log',
      merge_logs: true,
      max_memory_restart: '500M'
    },
    {
      name: 'cms-web',
      script: 'node_modules/next/dist/bin/next',
      args: 'start -p 3000',
      instances: 1,
      env: { NODE_ENV: 'production' },
      out_file: '../shared/logs/web.out.log',
      error_file: '../shared/logs/web.err.log'
    }
  ]
};

3. Nginx Reverse Proxy (Example)

deploy/nginx.conf

nginx

server {
  listen 80;
  server_name cms.example.com;
  client_max_body_size 50m;

  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $remote_addr;
  }

  location /api/ {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_read_timeout 60s;
  }

  location /health {
    proxy_pass http://127.0.0.1:8080/health;
  }
}

4. Environment Variables (.env)

NODE_ENV=production
PORT=8080
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=cms
MYSQL_PASSWORD=***
MYSQL_DB=cms
REDIS_URL=redis://127.0.0.1:6379
JWT_SECRET=***

Note: The

.env

file is imported from

shared/

and not packaged into the release

5. Health Check

Backend provides the

/health

endpoint:

javascript

// src/api/health.js
app.get('/health', (req, res) => {
  res.json({
    status: 'ok',
    timestamp: new Date().toISOString(),
    uptime: process.uptime(),
    memory: process.memoryUsage()
  });
});

6. Monitoring Metrics

PM2/Node: CPU, memory, process count, restart times
Nginx: Access logs, error logs, response time
Business: QPS, P95, error rate, database connection count

Workflow (FLOW)

Standard deployment process (8 steps)

Overview

Prepare for release → Generate build artifact → Upload to server → Extract + Dependency Installation + Build → Start in new directory + Health Check → Switch current link → Execute post-release smoke test → Record release and monitoring baseline

1) Prepare for Release

What to do: Confirm release checklist and check disk space Why: Ensure release environment is ready How: Check

deploy/release-checklist.md

; Verify disk space > 20%

2) Generate Build Artifact

What to do: Package build artifact and generate checksum Why: Ensure artifact integrity How: Run

npm run build

; Generate tar.gz package; Record commit and checksum

3) Upload to Server

What to do: Upload build artifact via SCP/SFTP Why: Transfer build artifact to server How: Upload to

/srv/apps/cms/releases/YYYY-MM-DD-HHMM/

4) Extract + Dependency Installation + Build

What to do: Extract artifact and install dependencies Why: Prepare runtime environment How: Extract tar.gz; Link shared resources (

ln -s ../../shared/.env .env

); Run

npm ci

(production dependencies); Run

npm run build

(if needed)

5) Start in New Directory + Health Check

What to do: Start new version with PM2 and check health Why: Ensure new version is available How: Run

pm2 start deploy/pm2.config.cjs

; Wait 10 seconds; Verify

/health

returns 200

6) Switch Current Link

What to do: Point the current soft link to the new version Why: Switch traffic to the new version How:

bash

rm -f /srv/apps/cms/current
ln -s /srv/apps/cms/releases/YYYY-MM-DD-HHMM /srv/apps/cms/current
pm2 reload deploy/pm2.config.cjs

7) Execute Post-release Smoke Test

What to do: Run smoke test scripts provided by QA Why: Verify key functions are available How: Run

npm run test:smoke

; Ensure all tests pass

8) Record Release and Monitoring Baseline

What to do: Record release information and establish monitoring baseline Why: Enable traceability, rollback, and monitoring How: Record version/commit/time/executor; Establish monitoring baseline (QPS/P95/error rate); Configure alert rules

Key Checkpoints

Phase 1 (Preparation): Have you checked disk space? Have you confirmed the release checklist?
Phase 2 (Build): Have you generated the checksum? Have you recorded the commit?
Phase 3 (Upload): Have you uploaded to the correct directory? Have you verified upload completeness?
Phase 4 (Installation): Have you linked shared resources? Have you installed production dependencies?
Phase 5 (Health Check): Does
```
/health
```
return 200? Have you waited long enough?
Phase 6 (Switch): Have you used PM2 reload? Is it zero-downtime?
Phase 7 (Smoke Test): Have you run the smoke test? Have all tests passed?
Phase 8 (Recording): Have you recorded release information? Have you established the monitoring baseline?

Self-check Checklist (CHECKLIST)

The following self-checks must be completed before release:

Release Preparation

PM2 configuration (cluster=3) and log rotation are completed
Nginx reverse proxy/health check/certificate configuration are completed
```
.env
```
is imported from
```
shared/
```
, not packaged into release
```
release.sh/rollback.sh
```
are executable, rollback within ≤3 minutes
Post-release smoke test scripts pass
Disk space > 20%, log rotation is enabled

Security Check

Node is run with non-root account
Sensitive configurations (certificates/keys) have minimal read permissions
Environment variables are not packaged into release
HTTPS certificate validity > 30 days

Rollback Preparation

Previous stable version is available
Rollback script is tested and passed
Rollback time ≤3 minutes
Post-rollback smoke test scripts pass

Monitoring & Alerting

Health check endpoint
```
/health
```
is available
CPU/Mem/QPS/P95 monitoring is configured
Alert rules are configured (health check failure/error rate surge/disk >80%)
Monitoring baseline is recorded (pre-release vs post-release comparison)

Database Migration (if applicable)

Migration scripts are executed independently
Rollback plan for migration is clear
Database backup is completed before migration
Data integrity is verified after migration

Release Record

Version/commit/checksum/release time are recorded
Executor/approver are recorded
Release logs include results of each step
Rollback record exists if deployment fails

❌ Bad Examples: Cannot find previous version after failure; Switch traffic even if health check fails; Missing smoke test scripts

Complete Examples (EXAMPLES)

Real-world reusable deployment scripts and checklist examples, ready to use or modify.

1. One-click Release Script (deploy/release.sh)

bash

#!/bin/bash
set -e

RELEASE_DIR="/srv/apps/cms/releases/$(date +%Y-%m-%d-%H%M)"
SHARED_DIR="/srv/apps/cms/shared"
CURRENT_DIR="/srv/apps/cms/current"

echo "=== Step 1: Create release directory ==="
mkdir -p "$RELEASE_DIR"

echo "=== Step 2: Upload build artifact ==="
scp build.tar.gz user@server:"$RELEASE_DIR/"

echo "=== Step 3: Extract and install dependencies ==="
ssh user@server << EOF
  cd "$RELEASE_DIR"
  tar -xzf build.tar.gz
  ln -s "$SHARED_DIR/.env" .env
  ln -s "$SHARED_DIR/logs" logs
  npm ci --production
EOF

echo "=== Step 4: Health check ==="
ssh user@server << EOF
  cd "$RELEASE_DIR"
  pm2 start deploy/pm2.config.cjs
  sleep 10
  curl -f http://localhost:8080/health || exit 1
EOF

echo "=== Step 5: Switch current link ==="
ssh user@server << EOF
  rm -f "$CURRENT_DIR"
  ln -s "$RELEASE_DIR" "$CURRENT_DIR"
  pm2 reload deploy/pm2.config.cjs
EOF

echo "=== Step 6: Post-release smoke test ==="
npm run test:smoke

echo "=== Step 7: Record release ==="
echo "$(date) - Released $RELEASE_DIR (commit: $(git rev-parse HEAD))" >> release.log

echo "=== Release completed successfully! ==="

2. Rollback Script (deploy/rollback.sh)

bash

#!/bin/bash
set -e

CURRENT_DIR="/srv/apps/cms/current"
RELEASES_DIR="/srv/apps/cms/releases"

echo "=== Finding previous release ==="
PREVIOUS=$(ls -t "$RELEASES_DIR" | sed -n '2p')

if [ -z "$PREVIOUS" ]; then
  echo "Error: No previous release found"
  exit 1
fi

echo "=== Rolling back to $PREVIOUS ==="
ssh user@server << EOF
  rm -f "$CURRENT_DIR"
  ln -s "$RELEASES_DIR/$PREVIOUS" "$CURRENT_DIR"
  pm2 reload deploy/pm2.config.cjs
  sleep 10
  curl -f http://localhost:8080/health || exit 1
EOF

echo "=== Rollback completed successfully! ==="
echo "$(date) - Rolled back to $PREVIOUS" >> rollback.log

3. Post-release Smoke Test (tests/e2e/smoke/post-release.spec.ts)

typescript

import { test, expect } from '@playwright/test';

test.describe('Post-release Smoke Test', () => {
  test('Health check passes', async ({ request }) => {
    const res = await request.get('http://cms.example.com/health');
    expect(res.ok()).toBeTruthy();
    const data = await res.json();
    expect(data.status).toBe('ok');
  });

  test('Homepage is accessible', async ({ page }) => {
    await page.goto('http://cms.example.com');
    await expect(page).toHaveTitle(/CMS/);
  });

  test('Login works', async ({ page }) => {
    await page.goto('http://cms.example.com/login');
    await page.fill('input[name="email"]', 'admin@test.com');
    await page.fill('input[name="password"]', 'Test1234!');
    await page.click('button[type="submit"]');
    await expect(page).toHaveURL(/dashboard/);
  });

  test('Core API works', async ({ request }) => {
    const res = await request.get('http://cms.example.com/api/v1/content-types', {
      headers: { Authorization: 'Bearer test-token' }
    });
    expect(res.ok()).toBeTruthy();
  });
});

4. Release Checklist (deploy/release-checklist.md)

markdown

# Release Checklist - CMS v1.0.0

## Pre-release Check
- [ ] All tests passed (UT + E2E)
- [ ] Reviewer approved
- [ ] QA accepted
- [ ] Disk space > 20%
- [ ] Database backup completed (if migration exists)
- [ ] Rollback script tested and passed

## In-release Check
- [ ] Build artifact checksum verified
- [ ] Dependency installation successful
- [ ] Health check passed (`/health` returns 200)
- [ ] PM2 reload has no errors
- [ ] Post-release smoke test passed

## Post-release Check
- [ ] Monitoring metrics are normal (CPU/Mem/QPS/P95)
- [ ] No surge in error rate
- [ ] No abnormal logs
- [ ] User feedback is normal

## Rollback Preparation
- [ ] Previous stable version: 2025-10-28-1100
- [ ] Rollback script: `deploy/rollback.sh`
- [ ] Rollback time: ≤3 minutes
- [ ] Rollback contact: ops@example.com

5. Task Card Example (CMS-D-002)

json

{
  "taskId": "CMS-D-002",
  "title": "Write One-click Release and Rollback Scripts",
  "department": "Deploy",
  "createdByRole": "Planner",
  "description": "Write one-click release script (release.sh) and rollback script (rollback.sh) that support zero-downtime deployment, health check, and post-release smoke test. Rollback time ≤3 minutes.",
  "acceptanceCriteria": [
    "Release script includes 7-step process (packaging/upload/extraction/installation/health check/switch/smoke test)",
    "Rollback script can restore the previous stable version within ≤3 minutes",
    "Post-release smoke test covers health check/homepage/login/core API"
  ],
  "technicalRequirements": [
    "Write deploy/release.sh",
    "Write deploy/rollback.sh",
    "Write tests/e2e/smoke/post-release.spec.ts",
    "Write deploy/release-checklist.md"
  ],
  "dependencies": ["CMS-B-012", "CMS-F-008"],
  "estimatedHours": 8,
  "priority": "P0",
  "tags": ["deploy", "ops"],
  "deliverables": [
    "deploy/release.sh",
    "deploy/rollback.sh",
    "tests/e2e/smoke/post-release.spec.ts",
    "deploy/release-checklist.md"
  ],
  "aiPromptSuggestion": {
    "system": "You are CodeBuddy Deploy, proficient in PM2 + Nginx + BT Panel deployment.",
    "user": "Please write one-click release script (7-step process) and rollback script (≤3 minutes) that support zero-downtime deployment, health check, and post-release smoke test."
  },
  "reviewPolicy": {
    "requiresReview": true,
    "reviewers": ["Reviewer"]
  },
  "qaPolicy": {
    "requiresQA": true,
    "testingScope": ["Smoke"]
  },
  "needsCoordination": [
    "Backend: Provide health check endpoint /health",
    "QA: Provide post-release smoke test scripts"
  ],
  "status": "Ready"
}

6. Bad Examples (Non-compliant)

❌ No Rollback Script:

bash

# Only release script, no rollback script
# Cannot recover quickly after deployment failure

❌ Direct pm2 restart without health check:

bash

pm2 restart all  # No health check, may cause service unavailability

❌ Start Node with root:

bash

sudo pm2 start app.js  # Security risk

❌ .env mixed in release package, leakage risk:

bash

tar -czf build.tar.gz . # Includes .env file

Strictly follow the above specifications to ensure high-quality delivery of deployment & operations!

codebuddy-deploy

NPX Install

Tags

SKILL.md Content (Chinese)

CodeBuddy Deploy Skill - Deployment & Operations Manual

Who Am I

My Responsibilities

When Am I Called

What I Deliver

Collaboration with Other Skills

Goals and Thresholds

Code of Conduct (RULES)

Basic Discipline

Deployment Process

Configuration Management

Monitoring & Alerting

Project Context (CONTEXT)

1. Server & Tech Stack

2. PM2 Configuration (Example)

3. Nginx Reverse Proxy (Example)

4. Environment Variables (.env)

5. Health Check

6. Monitoring Metrics

Workflow (FLOW)

Overview

1) Prepare for Release

2) Generate Build Artifact

3) Upload to Server

4) Extract + Dependency Installation + Build

5) Start in New Directory + Health Check

6) Switch Current Link

7) Execute Post-release Smoke Test

8) Record Release and Monitoring Baseline

Key Checkpoints

Self-check Checklist (CHECKLIST)

Release Preparation

Security Check

Rollback Preparation

Monitoring & Alerting

Database Migration (if applicable)

Release Record

Complete Examples (EXAMPLES)

1. One-click Release Script (deploy/release.sh)

2. Rollback Script (deploy/rollback.sh)

3. Post-release Smoke Test (tests/e2e/smoke/post-release.spec.ts)

4. Release Checklist (deploy/release-checklist.md)

5. Task Card Example (CMS-D-002)

6. Bad Examples (Non-compliant)