Operations & Runbooks¶

Operational playbooks for CloudXM's platform. Start here when something breaks. All services follow the same deploy and incident flow unless a product page says otherwise.

Environments¶

Deployment¶

flowchart LR
    MR[Merge Request] -->|review + pipeline preview| MAIN[merge to main]
    MAIN --> GL[GitLab CI]
    GL -->|static sites| PAGES[wrangler pages deploy]
    GL -->|services| SSH[ssh deploy@prd1]
    PAGES --> CF[Cloudflare Pages]
    SSH --> DOCKER[docker compose / rsync + artisan]

Deploying a static site (Pages)¶

• Pushes to main deploy to production automatically (GitLab CI → wrangler pages deploy --branch main).
• Merge requests get preview deployments (<hash>.cloudxm-wiki.pages.dev), protected by Cloudflare Access.
• Never run wrangler deploy (no --branch) as a preview command — it overwrites production.

Deploying a service (VPS)¶

1. The app repo's CI connects as the deploy user (group-level PROD_SSH_KEY).
2. rsync code / build image → docker compose -p <project> up -d (or rsync + artisan for PHP-FPM apps).
3. Healthcheck must fail the pipeline if the service is down after deploy.

Backups¶

Incident response¶

1. Detect — monitoring/healthchecks, client report, or manual check.
2. Triage — is it an edge (Cloudflare) or origin (VPS) problem? curl -sI https://<domain>/ and check DNS/SSL first.
3. Communicate — post in the team channel; keep a timeline.
4. Mitigate — rollback is faster than forward-fixing for deploys (redeploy previous release / revert MR).
5. Recover — restore from backup if data is involved (test in staging first).
6. Review — add the root cause to the runbooks; update this wiki.

Quick triage commands¶

# Edge vs origin
curl -sI https://convert.cloudxm.com.br/health | head -5

# VPS reachability
for port in 22 80 443; do
  timeout 3 bash -c "echo > /dev/tcp/2.24.212.12/$port" 2>&1 && echo "$port OPEN" || echo "$port CLOSED"
done

# Service health (on VPS)
docker ps --format "table {{.Names}}\t{{.Status}}"
systemctl status nginx php8.2-fpm postgresql 2>&1 | head -20

Access management¶

Maintenance windows¶

• Prefer low-traffic hours (BR evenings) for breaking changes.
• Announce maintenance in the team channel at least 24h ahead.

Runbook index¶