Skip to content

Fastly Setup

Jump to bottom
Griffen Fargo edited this page Aug 21, 2026 · 2 revisions

Fastly Setup

Complete guide for setting up Doorman with Fastly Next-Gen WAF.

Status: Fastly support is in beta — actively developed, with rule translation, IP list management, and rate limiting, but not yet as battle-tested as the stable Vercel Firewall support. Review changes carefully before applying to production.

Scope: Doorman manages Fastly's Next-Gen WAF (formerly Signal Sciences) workspace rules — the structured, JSON-based rules API. Classic Fastly VCL services are not supported.

Prerequisites

  • A Fastly account with Next-Gen WAF enabled and at least one workspace
  • Node.js 18+ installed
  • Doorman installed (npm install -g @gfargo/doorman)

Get Your Credentials

API Token

  1. Go to Fastly Personal API Tokens
  2. Create a token with access to the Next-Gen WAF product for your target workspace
  3. Copy the token immediately — you won't see it again

Workspace ID

  1. In the Fastly control panel, open Next-Gen WAF and select your workspace
  2. The workspace ID is in the URL and in the workspace settings page
  3. Copy it

Configure Environment Variables

export FASTLY_API_TOKEN="your_api_token_here"
export FASTLY_WORKSPACE_ID="your_workspace_id_here"

Or create a .env file in your project root:

FASTLY_API_TOKEN=your_api_token_here
FASTLY_WORKSPACE_ID=your_workspace_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 Fastly credentials. For Fastly, create .doorman.json manually:

{
  "$schema": "https://doorman.griffen.codes/schema.json",
  "provider": "fastly",
  "providers": {
    "fastly": {
      "workspaceId": "your_workspace_id"
    }
  },
  "rules": [],
  "ips": []
}

Add Your First Rules

Write rules by hand in your Fastly-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 Fastly ones, so it isn't a fit for a Fastly config yet.

Deploy

# Preview what will change
doorman diff --provider fastly

# Deploy rules
doorman sync --provider fastly

# Verify deployment
doorman status --provider fastly

Day-to-Day Commands

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

How Doorman Models Fastly

A few things behave differently on Fastly than on Vercel/Cloudflare — worth knowing before you write rules:

  • Rules are evaluated independently, not in priority order. Next-Gen WAF has no API-exposed evaluation-order concept, so a rule's priority in your config has no effect on Fastly. Doorman warns about this during sync if you set one.
  • IP allow/block-listing uses two workspace lists, not individual per-IP rules. Doorman maintains doorman-managed-deny and doorman-managed-allow lists and replaces their contents wholesale on each sync. Per-IP hostname/notes fields have no Fastly equivalent and are dropped (with a warning) — only the address is kept.
  • Rate-limit rules need a pre-existing custom signal. Fastly counts rate-limited requests against a named signal that Doorman does not create automatically — create a signal named doorman-rate-limit-<rule-id> in your workspace before syncing a rate-limit rule, or the sync will be rejected.
  • Geo-blocking is country-level only — Fastly has no city/region/continent condition field.
  • Header, query, and cookie matching require a key (the header/parameter/cookie name) alongside the value — see Configuration for the shape.
  • No draft/publish step. Unlike some other Fastly products, Next-Gen WAF rule and list writes take effect immediately once synced.

Troubleshooting

"Invalid API Token" / 403 errors

  • Verify the token hasn't expired and has Next-Gen WAF access for the target workspace
  • Confirm FASTLY_WORKSPACE_ID matches the workspace the token was scoped to

Rules Not Appearing

  • Check the workspace's Rules view in the Fastly Next-Gen WAF control panel
  • Run doorman sync --provider fastly --debug for detailed output
  • Look for translation warnings — complex conditions may have been simplified or dropped

Rate Limit Rule Sync Fails

IP Blocking Not Working

  • Confirm the doorman-managed-deny/doorman-managed-allow lists exist and contain the expected entries in the workspace's Lists view
  • Use CIDR notation for ranges (203.0.113.0/24)

Security Best Practices

  1. Never commit API tokens — use environment variables or secret management
  2. Use minimum permissions — only grant what Doorman needs
  3. Test in staging first — create rules disabled, enable after testing
  4. Create backups before major changes
  5. Monitor Fastly's request/event views for rule effectiveness

Related Pages

Getting Started

Configuration

Commands

Guides

Clone this wiki locally