vm-cloudflare/DEPLOYMENT_GUIDE.md

DEPLOYMENT_GUIDE.md

OpenCode Cloudflare Infrastructure Deployment Guide

Status: 🟢 Production Ready
Version: 1.0
Updated: December 9, 2025
Governed by: RED-BOOK.md

---

Table of Contents

1. Quick Start
2. Architecture Overview
3. Environment Setup
4. Component Verification
5. Compliance Oracle Usage
6. Workflow Examples
7. Troubleshooting
8. Appendix

---

Quick Start

1. Prerequisites

• macOS/Linux with bash >= 4.0
• Python 3.9+
• Node.js 18+ (for MCP servers)
• Git 2.30+
• OpenCode CLI installed

2. Environment Variables (5 min)

# Essential (required for GitLab + Cloudflare)
export GITHUB_TOKEN="ghp_..."           # GitHub PAT (already set)
export GITLAB_TOKEN="glpat_..."         # GitLab PAT
export GITLAB_URL="https://gitlab.com"  # or your self-hosted GitLab
export CLOUDFLARE_API_TOKEN="..."       # Cloudflare API token
export CLOUDFLARE_ACCOUNT_ID="..."      # Cloudflare account ID

# Save to .env (source before running opencode)
source /Users/sovereign/Desktop/CLOUDFLARE/.env

How to Get Tokens:

• GitLab PAT: https://gitlab.com/-/user_settings/personal_access_tokens

  • Scopes: api, read_user, read_repository, write_repository
  • Expiry: 30 days

• Cloudflare API Token: https://dash.cloudflare.com/profile/api-tokens

  • Create custom token with: DNS:Read, Settings:Read, Firewall Rules:Read, Tunnels:Read
  • Expiry: 1 year

• Cloudflare Account ID: https://dash.cloudflare.com/ (right sidebar under Account)

3. Verify Setup (3 min)

cd /Users/sovereign/Desktop/CLOUDFLARE

# Run quick test
bash TEST_WORKFLOW.sh quick

# Expected output:
# ✓ All environment variables set
# ✓ Terraform files valid
# ✓ All checks passed!

4. Launch OpenCode (1 min)

opencode
/init

# In OpenCode:
/mcp list          # Verify MCPs load
/agent cloudflare-ops
# Now you can query your infrastructure

---

Architecture Overview

MCP Stack (16 MCPs)

┌─────────────────────────────────────────────────┐
│         OpenCode Platform                       │
│  (Claude API + MCP Router)                      │
└─────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────┐
│  Enabled by Default (4 MCPs)                    │
├─────────────────────────────────────────────────┤
│ • filesystem      - Local file operations       │
│ • git             - Git repository management   │
│ • github          - GitHub API queries          │
│ • gh_grep         - GitHub code search          │
└─────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────┐
│  Per-Agent Optional (12 MCPs)                   │
├─────────────────────────────────────────────────┤
│ Core Infrastructure:                            │
│ • gitlab          - GitLab API (CI/CD, repos)   │
│ • cloudflare      - Cloudflare API (DNS, WAF)   │
│ • postgres        - Query audit logs            │
│ • sqlite          - Local analytics             │
│                                                  │
│ Advanced:                                       │
│ • docker          - Container testing          │
│ • aws             - AWS infrastructure          │
│ • slack           - Notifications               │
│ • linear          - Issue tracking              │
│ • memory          - Knowledge base              │
│ • context7        - Doc search                  │
│ • web-scraper     - Web automation              │
│ • googlemaps      - Location services           │
└─────────────────────────────────────────────────┘

Agent Ecosystem (3 Agents)

Agent	Purpose	Tools	Use Case
cloudflare-ops	Infrastructure & GitOps	filesystem, git, github, gitlab, cloudflare, gh_grep	Add DNS, update WAF, manage tunnels, validate infrastructure
security-audit	Compliance & Security	filesystem, git, github, gitlab, cloudflare, gh_grep	Check PCI-DSS, review WAF rules, audit access controls
data-engineer	Database Operations	filesystem, git, gitlab, postgres, sqlite	Query logs, analyze metrics, troubleshoot data pipelines

Compliance Oracle Architecture

Question
   ↓
[oracle_runner.py]
   ├─ Search Documents (framework-aware)
   ├─ Extract Snippets (relevance scoring)
   ├─ Build Context (citations)
   ├─ Validate Answer (typing)
   ├─ Hash Answer (SHA256)
   └─ Emit Receipt (ledger.jsonl)
   ↓
Receipt (json)
   ├─ timestamp
   ├─ oracle_answer (full answer JSON)
   ├─ answer_hash (SHA256)
   └─ version (v0.4.0)

---

Environment Setup

1. Configure opencode.jsonc

The configuration is already set up. Key sections:

{
  "mcp": {
    // Enabled globally
    "filesystem": { "enabled": true },
    "git": { "enabled": true },
    "github": { "enabled": true },
    "gh_grep": { "enabled": true },
    
    // Per-agent (disabled globally, enabled per agent)
    "gitlab": { "enabled": false },    // Enabled in cloudflare-ops, security-audit
    "cloudflare": { "enabled": false } // Enabled in cloudflare-ops, security-audit
  },
  
  "agents": {
    "cloudflare-ops": {
      "tools": {
        "gitlab": true,
        "cloudflare": true,
        // + filesystem, git, github, gh_grep
      }
    }
    // ... other agents
  }
}

2. Environment Variables

Create or update .env:

# Copy from example
cp .env.example .env

# Edit and add your tokens
export GITLAB_TOKEN="glpat_..."
export CLOUDFLARE_API_TOKEN="..."
export CLOUDFLARE_ACCOUNT_ID="..."

# Verify
source .env
echo $GITLAB_TOKEN  # Should not be empty

3. Verify MCP Installation

# Inside opencode
/mcp list

# Expected:
# ✓ filesystem (enabled globally)
# ✓ git (enabled globally)
# ✓ github (enabled globally, requires GITHUB_TOKEN)
# ✓ gh_grep (enabled globally)
# ⚠ gitlab (disabled globally, enabled per-agent, requires GITLAB_TOKEN)
# ⚠ cloudflare (disabled globally, enabled per-agent, requires CLOUDFLARE_API_TOKEN)
# ⚠ postgres (disabled, requires DATABASE_URL)
# ... (other optional MCPs)

---

Component Verification

Test Suite

# Quick test (environment check)
bash TEST_WORKFLOW.sh quick

# Full test (integration tests)
bash TEST_WORKFLOW.sh full

Manual Verification

1. Git Integration

cd /Users/sovereign/Desktop/CLOUDFLARE
git log --oneline -n 3
git status

2. Terraform Validation

cd terraform/
terraform validate
terraform fmt -check .

3. Cloudflare API Test

curl -X GET "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" | jq '.success'
# Should return: true

4. GitLab API Test

curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "$GITLAB_URL/api/v4/user" | jq '.name'
# Should return your GitLab username

---

Compliance Oracle Usage

Quick Usage

# Run oracle for GDPR compliance
python3 oracle_runner.py "Are we GDPR compliant?" --frameworks gdpr

# Run oracle for NIS2 obligations
python3 oracle_runner.py "What are NIS2 requirements?" --frameworks nis2

# Run oracle for AI Act with verbose output
python3 oracle_runner.py "What does AI Act Annex IV require?" --frameworks ai-act -v

Oracle Output

The oracle returns:

1. Answer - Context-aware response with citations
2. Citations - Linked documents with relevance scores
3. Gaps - Identified compliance gaps with remediations
4. Receipt - SHA256-hashed proof stored in COMPLIANCE_LEDGER.jsonl

Example: Golden Answer

See: examples/oracle_answer_ai_act.json and examples/oracle_receipt_ai_act.json

These demonstrate the complete oracle pipeline for a real compliance question.

---

Workflow Examples

Example 1: Add HTTPS Enforcement

Task: Add HTTPS enforcement to all zones

opencode
/agent cloudflare-ops

# Query: Add HTTPS enforcement to all zones, then show me the plan

Behind the scenes:

1. Agent uses cloudflare MCP to query current zones
2. Agent uses filesystem to read terraform/zones.tf
3. Agent uses git to track changes
4. Agent generates terraform plan
5. You review and approve

Example 2: Audit WAF Rules for PCI-DSS

Task: Check if WAF rules meet PCI-DSS requirements

opencode
/agent security-audit

# Query: Review our WAF rules in terraform/waf.tf and check PCI-DSS compliance

Behind the scenes:

1. Agent uses filesystem to read WAF configuration
2. Agent uses gh_grep to find similar PCI-DSS patterns
3. Agent searches documentation for compliance mappings
4. Agent generates audit report with gaps

Example 3: Incident Response

Task: DNS compromise detection and remediation

opencode
/agent cloudflare-ops

# Query: A domain is showing unauthorized DNS records. Query Cloudflare to see current records, check playbooks/, and generate a remediation plan.

Behind the scenes:

1. Agent uses cloudflare MCP to query live DNS records
2. Agent uses filesystem to read playbooks/DNS-COMPROMISE-PLAYBOOK.md
3. Agent uses git to prepare rollback commits
4. Agent generates step-by-step remediation

Example 4: Compliance Report

Task: Generate PCI-DSS compliance report

# Use oracle directly
python3 oracle_runner.py "What are our PCI-DSS compliance gaps?" --frameworks pci-dss

# Then use agent to generate remediation plan
opencode
/agent security-audit

# Query: Based on the gaps, create a 30-day remediation plan

---

Troubleshooting

MCP Won't Load

Symptom: /mcp list shows error for gitlab or cloudflare

Solution:

1. Verify tokens are exported: echo $GITLAB_TOKEN
2. Check token format: glpat_ for GitLab, bearer token for Cloudflare
3. Verify network connectivity: curl https://api.cloudflare.com/client/v4/zones

Terraform Validate Fails

Symptom: terraform validate returns errors

Solution:

1. Run terraform init first
2. Check terraform.tfvars exists and is valid
3. Verify Cloudflare provider version in .terraform.lock.hcl

Oracle Returns "Insufficient Context"

Symptom: Oracle answer shows insufficient_context: true

Solution:

1. Ensure documentation files exist in project root
2. Check file names match in oracle_runner.py line 97
3. Add more detailed documentation files
4. Test with verbose mode: python3 oracle_runner.py ... -v

Token Expired

Symptom: API calls return 401 Unauthorized

Solution:

1. GitLab: Renew PAT at https://gitlab.com/-/user_settings/personal_access_tokens
2. Cloudflare: Renew token at https://dash.cloudflare.com/profile/api-tokens
3. Update .env and re-source: source .env

---

Appendix

A. File Structure

/Users/sovereign/Desktop/CLOUDFLARE/
├── opencode.jsonc           # 16 MCPs configured (DO NOT edit unless expert)
├── .env                      # Your environment variables (DO NOT commit)
├── .env.example              # Template for .env (safe to commit)
├── TEST_WORKFLOW.sh          # Integration test suite
├── oracle_runner.py          # Compliance oracle v0.4.0
├── AGENTS.md                 # Agent documentation
├── MCP_GUIDE.md              # Complete MCP reference
├── GITLAB_CLOUDFLARE_AUTH.md # Token setup guide
├── DEPLOYMENT_GUIDE.md       # This file
│
├── terraform/                # Infrastructure code
│   ├── main.tf
│   ├── zones.tf
│   ├── dns.tf
│   ├── waf.tf
│   ├── tunnels.tf
│   ├── access.tf
│   └── ...
│
├── gitops/                   # CI/CD agents
│   ├── plan_summarizer.py
│   ├── ci_plan_comment.py
│   ├── drift_pr_bot.py
│   └── webhook_receiver.py
│
├── playbooks/                # Incident response
│   ├── DNS-COMPROMISE-PLAYBOOK.md
│   ├── TUNNEL-ROTATION-PROTOCOL.md
│   └── waf_incident_playbook.md
│
├── scripts/                  # Automation utilities
│   ├── state-reconciler.py
│   ├── drift_guardian_py.py
│   ├── autonomous_remediator_py.py
│   └── invariant_checker_py.py
│
├── observatory/              # Monitoring & observability
│   ├── metrics-exporter.py
│   ├── prometheus.yml
│   ├── alertmanager/
│   └── dashboards/
│
├── examples/                 # Golden examples
│   ├── oracle_answer_ai_act.json
│   └── oracle_receipt_ai_act.json
│
└── COMPLIANCE_LEDGER.jsonl   # Created by oracle_runner.py

B. Supported Frameworks

Framework	Key Doc	Focus
PCI-DSS	cloudflare_waf_baseline.md	Network security, access controls
GDPR	zero_trust_architecture.md	Data protection, access logging
NIS2	TUNNEL-HARDENING.md	Network resilience, monitoring
AI Act	WEB-INFRA-SECURITY-PATTERNS.md	Governance, explainability
SOC2	WEB-INFRA-SECURITY-PATTERNS.md	Security controls, audit logs
ISO27001	zero_trust_architecture.md	Information security management

C. Quick Reference

Task	Command
Start OpenCode	opencode
Initialize	/init
List MCPs	/mcp list
Start agent	/agent cloudflare-ops
Run oracle	python3 oracle_runner.py "question"
Validate terraform	cd terraform && terraform validate
Test setup	bash TEST_WORKFLOW.sh quick
View git log	git log --oneline -n 10
Query Cloudflare	OpenCode (with cloudflare-ops agent)
Query GitLab	OpenCode (with cloudflare-ops agent)

D. Common Queries

For cloudflare-ops agent:

• "What DNS records do we have for example.com?"
• "Show me our WAF rules and check if they block SQL injection"
• "List all tunnel configurations"
• "Create a terraform plan to add HTTPS enforcement"
• "Show recent changes in GitLab that affect infrastructure"

For security-audit agent:

• "Are we compliant with PCI-DSS?"
• "Review WAF rules for OWASP compliance"
• "Check if access controls meet GDPR standards"
• "Audit DNS configurations for security risks"

For oracle_runner.py:

• "python3 oracle_runner.py 'What are NIS2 incident reporting requirements?'"
• "python3 oracle_runner.py 'Summarize our AI Act obligations' --frameworks ai-act"
• "python3 oracle_runner.py 'Check GDPR data retention requirements' -v"

---

Support & Feedback

OpenCode Issues: https://github.com/sst/opencode/issues

Project Issues: Create issue in your project repo

Documentation: See AGENTS.md, MCP_GUIDE.md, GITLAB_CLOUDFLARE_AUTH.md

---

Last Updated: December 8, 2025
Status: 🟢 Production Ready
Next Review: December 15, 2025