Skip to content

Cloudflare Setup

Jump to bottom
Griffen Fargo edited this page Aug 24, 2026 · 6 revisions

Cloudflare Setup

Complete guide for setting up Doorman with Cloudflare WAF.

Status: Cloudflare support is in beta — actively developed, with comprehensive error handling, validation, and rule translation, but not yet as battle-tested as the stable Vercel Firewall support. Review changes carefully before applying to production.

Prerequisites

  • Cloudflare account with at least one domain
  • Node.js 18+ installed
  • Doorman installed (npm install -g @gfargo/doorman)

Get Your Credentials

API Token

  1. Go to Cloudflare API Tokens
  2. Click Create Token → Custom token
  3. Set these permissions:
Permission Type Permission Access Level
Zone Zone Settings Read
Zone Zone Read
Zone Firewall Services Edit
Account Account Rulesets Edit (optional)
  1. Under Zone Resources, select your domain (or "All zones from an account" for multiple domains)
  2. Optionally set Client IP Filtering and TTL for extra security
  3. Click Continue to summary → Create Token
  4. Copy the token immediately — you won't see it again

Zone ID

  1. Go to Cloudflare Dashboard and select your domain
  2. On the Overview page, find Zone ID in the right sidebar
  3. Copy it

Account ID (Optional)

The Account ID enables the Cloudflare Lists API for efficient bulk IP management.

  1. On any Cloudflare dashboard page, find Account ID in the right sidebar
  2. Copy it

Without an Account ID, Doorman falls back to individual IP rules instead of Lists.

Configure Environment Variables

export CLOUDFLARE_API_TOKEN="your_api_token_here"
export CLOUDFLARE_ZONE_ID="your_zone_id_here"
export CLOUDFLARE_ACCOUNT_ID="your_account_id_here"  # Optional

Or create a .env file in your project root:

CLOUDFLARE_API_TOKEN=your_api_token_here
CLOUDFLARE_ZONE_ID=your_zone_id_here
CLOUDFLARE_ACCOUNT_ID=your_account_id_here

Important: Add .env to your .gitignore to avoid committing secrets.

Initialize Your Project

doorman init only supports Vercel today — it has no --provider flag and doesn't prompt for Cloudflare credentials. For Cloudflare, create .doorman.json manually:

{
  "$schema": "https://doorman.griffen.codes/schema.json",
  "provider": "cloudflare",
  "providers": {
    "cloudflare": {
      "zoneId": "your_zone_id",
      "accountId": "your_account_id"
    }
  },
  "rules": [],
  "ips": []
}

Add Your First Rules

Write rules by hand in your Cloudflare-provider config (see Configuration for the rule format). doorman template doesn't take a --provider flag or an add subcommand — doorman template <name> (e.g. doorman template bad-bots) only exists today, and it generates Vercel-format rules, not Cloudflare ones, so it isn't a fit for a Cloudflare config yet.

Deploy

# Preview what will change
doorman diff --provider cloudflare

# Deploy rules
doorman sync --provider cloudflare

# Verify deployment
doorman status --provider cloudflare

Day-to-Day Commands

doorman status --provider cloudflare    # Check sync status and health
doorman list --provider cloudflare      # List deployed rules
doorman diff --provider cloudflare      # Preview pending changes
doorman sync --provider cloudflare      # Deploy changes
doorman validate                        # Validate config syntax
doorman backup                          # Create a backup
doorman watch --provider cloudflare     # Auto-sync on file changes

Managed Rule Groups

Deploy a vendor-managed ruleset (Cloudflare Managed Ruleset, OWASP CRS, etc.) alongside your custom rules by adding managedRules to your config:

{
  "managedRules": [
    {
      "ruleset": "efb7b8c949ac4650a09736fc376e9aee",
      "enabled": true,
      "action": "log"
    }
  ]
}

This example deploys Cloudflare's Managed Ruleset (that well-known id) with every rule downgraded to log — a safe way to see what it would block before enforcing anything. Drop the action override once you're ready to enforce, or use overrides to tune individual rules. Full field reference and an overrides example: Configuration#managed-rule-groups.

Managed rule groups deploy in Cloudflare's separate managed-rules phase, evaluated independently of your custom rules — no ordering interaction to think about between the two.

Advanced Configuration

Multiple Zones

Create separate config files per zone by hand (see Initialize Your Project above), e.g. zone1.config.json and zone2.config.json, each with its own providers.cloudflare.zoneId.

Account-Level Rules

With an Account ID, you can create rules that apply across all zones:

{
  "providers": {
    "cloudflare": {
      "accountId": "your_account_id",
      "useAccountRules": true
    }
  }
}

Cloudflare Plan Limits

Plan Custom Rules
Free 5
Pro 20
Business 100
Enterprise Unlimited

Troubleshooting

"Invalid API Token"

  • Verify the token hasn't expired
  • Confirm it has Zone: Firewall Services: Edit permission
  • Test manually: 
    curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

"Zone Not Found"

  • Double-check the Zone ID in the Cloudflare dashboard
  • Ensure the token has access to that zone
  • List accessible zones: 
    curl -X GET "https://api.cloudflare.com/client/v4/zones" \
  -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" | jq '.result[] | {name, id}'

Rules Not Appearing

  • Check Security → WAF → Custom rules in the Cloudflare dashboard
  • Run doorman sync --provider cloudflare --debug for detailed output
  • Look for translation warnings — complex conditions may have been simplified

Rate Limit Errors (429)

Doorman has built-in retry logic, but if you hit persistent rate limits:

  • Avoid running multiple sync operations simultaneously
  • Wait 60 seconds and retry

IP Blocking Not Working

  • Ensure IPs use CIDR notation (192.168.1.1/32 not 192.168.1.1)
  • Provide an Account ID to enable the more efficient Lists API
  • Check rule priority in the Cloudflare dashboard

Security Best Practices

  1. Never commit API tokens — use environment variables or secret management
  2. Use minimum permissions — only grant what Doorman needs
  3. Set token expiration — rotate tokens regularly
  4. Test in staging first — create rules disabled, enable after testing
  5. Create backups before major changes
  6. Monitor Cloudflare Analytics (Security → Events) for rule effectiveness

Related Pages

Getting Started

Configuration

Commands

Guides

Clone this wiki locally