Decap CMS Integration

Overview

The RCS documentation site includes Decap CMS (formerly Netlify CMS), a Git-based content management system that provides a graphical interface for editing documentation without directly modifying markdown files.

Key Features:

• 🔐 Cloudflare Access magic-link authentication (no passwords)
• 🔑 GitHub OAuth for repository write access
• 📝 GUI editing for all documentation sections
• 🚀 Automatic deployment via Cloudflare Pages
• 📊 Full audit trail through Git commit history

---

Architecture

Authentication Flow

graph LR
    A[Editor] --> B[Cloudflare Access]
    B --> C{Email Approved?}
    C -->|Yes| D[Magic Link]
    D --> E[CMS Interface]
    E --> F[GitHub OAuth]
    F --> G{Repo Access?}
    G -->|Yes| H[Edit Content]
    H --> I[Commit to GitHub]
    I --> J[Cloudflare Pages Deploy]

Two-Layer Security

1. Cloudflare Access (Layer 1)

   • Email-based magic link authentication
   • Only approved emails can access /admin
   • 24-hour session duration
   • No passwords to manage or leak

2. GitHub OAuth (Layer 2)

   • Repository write access required
   • All commits attributed to GitHub user
   • Full audit trail in Git history

---

File Structure

apps/docs/
├── public/
│   └── admin/
│       ├── index.html          # CMS interface shell
│       └── config.yml          # CMS configuration
├── ADMIN_ACCESS.md             # Editor documentation
└── SETUP.md                    # Administrator guide

---

Configuration

Backend

• Type: GitHub
• Repository: adamsdsit/rcsweb_v2
• Branch: main
• Publish Mode: Simple (direct commits, no editorial workflow)

Collections

The CMS provides editing interfaces for all documentation sections:

Collection	Path	Create New
Home	src/content/docs/index.mdx	No
Architecture	src/content/docs/architecture/	Yes
ADRs	src/content/docs/adr/	Yes
Diagrams	src/content/docs/diagrams/	Yes
Marketing	src/content/docs/marketing/	Yes
Platform	src/content/docs/platform/	Yes
Security	src/content/docs/security/	Yes
Operations	src/content/docs/ops/	Yes

Each collection supports:

• title (required)
• description (optional)
• Markdown/MDX body content
• File creation and editing

---

Access Control

Scope Limitations

The CMS can ONLY edit:

• ✅ Markdown/MDX files in src/content/docs
• ✅ Upload images to public/images

The CMS CANNOT access:

• ❌ Site configuration files (astro.config.mjs, package.json)
• ❌ Build scripts or deployment settings
• ❌ The marketing site (apps/site)
• ❌ Repository settings or workflows
• ❌ Other monorepo packages

Audit Trail

Every change is tracked:

• Who: GitHub username in commit author
• What: Full diff of changes
• When: Commit timestamp
• Why: Commit message (auto-generated by CMS)

View the audit trail: GitHub Commits

---

Setup Requirements

1. GitHub OAuth Application

Location: GitHub Settings → Developer settings → OAuth Apps

Required Settings:

• Application name: RCS Docs CMS
• Homepage URL: https://docs.resilientconsultingsolutions.com
• Authorization callback URL: https://api.netlify.com/auth/done

[!NOTE] Decap CMS uses Netlify’s OAuth service even when not hosted on Netlify.

2. Cloudflare Pages Environment Variables

Location: Cloudflare Dashboard → Pages → docs → Settings → Environment variables

Required Variables (Production):

• GITHUB_CLIENT_ID: Your OAuth Client ID
• GITHUB_CLIENT_SECRET: Your OAuth Client Secret

3. Cloudflare Access Policy

Location: Cloudflare Dashboard → Zero Trust → Access → Applications

Application Settings:

• Name: RCS Docs Admin
• Domain: docs.resilientconsultingsolutions.com
• Path: /admin
• Session Duration: 24 hours

Access Policy:

• Policy name: Approved Editors
• Action: Allow
• Include: Approved email addresses
• Authentication: One-time PIN (email magic link)

---

Usage

Accessing the CMS

1. Navigate to: https://docs.resilientconsultingsolutions.com/admin
2. Complete Cloudflare Access magic-link authentication
3. Authorize GitHub OAuth access
4. Edit content through the GUI

Editing Workflow

1. Select a collection (e.g., “Architecture”, “Security”)
2. Choose a document to edit or create a new one
3. Make changes in the editor
4. Click “Save” to commit changes
5. Changes are committed directly to the main branch
6. Cloudflare Pages automatically rebuilds and deploys

Deployment time: Typically 2-5 minutes from save to live.

---

Maintenance

CMS Updates

• Loaded from CDN, updates automatically
• Pinned to major version 3.x for stability
• No manual updates required

Adding Editors

1. Add as GitHub collaborator (write access)
2. Add email to Cloudflare Access policy
3. Access granted immediately

Removing Editors

1. Remove email from Cloudflare Access policy
2. Optionally remove GitHub collaborator
3. Access revoked immediately

Disabling the CMS

• Remove the public/admin directory
• Commit and push the change
• The /admin route will return 404

---

Security Considerations

• No passwords: Authentication is email-based magic link only
• No user database: Cloudflare Access manages authentication
• GitHub as source of truth: All changes are version-controlled
• Audit trail: All commits are attributed to GitHub users
• Scope limitation: CMS can only edit markdown files in src/content/docs
• No configuration access: CMS cannot modify Astro config, build files, or other apps
• Automatic deployment: Changes trigger Cloudflare Pages rebuild automatically

---

References

• Editor Guide: ADMIN_ACCESS.md
• Setup Guide: SETUP.md
• Decap CMS Docs: https://decapcms.org/docs/
• Cloudflare Access Docs: https://developers.cloudflare.com/cloudflare-one/applications/

---

ADR Reference

See ADR 0007: Decap CMS for Docs Editing for the architectural decision rationale.