Skip to content

Vercel Setup

Jump to bottom
Griffen Fargo edited this page Aug 21, 2026 · 1 revision

Vercel Setup

Complete guide for setting up Doorman with Vercel Firewall.

Status: Vercel Firewall is Doorman's original, stable provider — the default when no provider is specified, and the only one doorman init scaffolds a config for directly.

Prerequisites

  • A Vercel account with a deployed project
  • Node.js 18+ installed
  • Doorman installed (npm install -g @gfargo/doorman)

Get Your Credentials

API Token

  1. Go to Vercel Account Tokens
  2. Create a token (name it something like "Doorman Firewall Management")
  3. Copy the token immediately — you won't see it again

More detail: how to create and use a Vercel API access token.

Project ID

  1. Go to your Vercel Dashboard and open the project
  2. Find the Project ID under Settings → General

More detail: finding your Project ID.

Team ID

  1. From your dashboard, select your team, then open Team Settings → General
  2. Find the Team ID there

More detail: finding your Team ID.

Required in practice, even though some parts of the CLI's own help text and README describe it as optional for personal accounts. Today, sync/status/diff/list/download/watch/backup/export all fail outside of an interactive session if a team ID isn't resolved from config, environment, or a prompt. If you hit "Vercel team ID is required" and don't think you have one, check your dashboard for a personal team ID rather than assuming you can skip it.

Configure Environment Variables

export VERCEL_TOKEN="your_api_token_here"
export VERCEL_PROJECT_ID="your_project_id_here"
export VERCEL_TEAM_ID="your_team_id_here"

Or create a .env file in your project root:

VERCEL_TOKEN=your_api_token_here
VERCEL_PROJECT_ID=your_project_id_here
VERCEL_TEAM_ID=your_team_id_here

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

Initialize Your Project

Unlike Cloudflare and Fastly, doorman init scaffolds Vercel configs directly:

doorman init --interactive

This walks you through Project ID and Team ID and writes a .doorman.json with them at the top level (the legacy, provider-implicit shape Vercel has always used):

{
  "$schema": "https://doorman.griffen.codes/schema.json",
  "firewallEnabled": true,
  "projectId": "prj_xxx",
  "teamId": "team_xxx",
  "rules": [],
  "ips": []
}

You can also run doorman setup for an interactive walkthrough that prints the dashboard links above and checks your environment.

Add Your First Rules

# Guided, interactive rule creation
doorman add --interactive

# One-liner for scripting
doorman add --name "Block Admin" --field path --op pre --value "/admin" --action deny

# IP blocking
doorman add ip --ip 203.0.113.100/32 --notes "Blocked for abuse"

# Pre-built templates
doorman template wordpress
doorman template ai-bots

Templates and add generate Vercel-format rules by default — no translation step needed, unlike Cloudflare or Fastly.

Deploy

# Preview what will change
doorman diff

# Deploy rules
doorman sync

# Verify deployment
doorman status

--provider vercel is accepted explicitly on these and other provider-aware commands, but it's also the default — you only need it if a config's provider field points elsewhere and you want to target Vercel anyway.

Day-to-Day Commands

doorman status      # Check sync status and health
doorman list         # List deployed rules
doorman diff         # Preview pending changes
doorman sync         # Deploy changes
doorman validate     # Validate config syntax (auto-detects provider from the config)
doorman backup       # Snapshot the live remote config to ./backups
doorman watch        # Auto-sync on local file changes

How Doorman Models Vercel

  • Vercel assigns rule IDs on create. Doorman can't pre-assign an ID for a new rule, so after sync creates rules, their real Vercel-assigned IDs are remapped back into your local config automatically.
  • Ordering is best-effort. Rules are written to Vercel individually, so Doorman can't reposition an already-existing remote rule to match a new local order. If you set priority on rules that already exist remotely, sync warns that reordering won't take effect.
  • First sync against a project with no firewall config yet prompts to create one — expected on a brand-new project, not an error.
  • Supported actions: log, deny, challenge, bypass, rate_limit, redirect. Managed rule sets (Vercel's CRS) are Enterprise-only and not something Doorman manages.

Troubleshooting

"Project not found"

  • Double-check VERCEL_PROJECT_ID against Settings → General on the project
  • Confirm the token has access to that project (or its team)

"Unauthorized"

  • Verify the token hasn't been revoked or expired
  • Confirm the token was created with access to the right team/project

"Firewall not available"

  • Vercel Firewall requires a Pro plan or higher — check your plan under account billing

Rules Not Appearing

  • Check the Firewall tab in the Vercel project dashboard
  • Run doorman sync --debug for detailed output

Security Best Practices

  1. Never commit API tokens — use environment variables or secret management
  2. Use minimum permissions — scope tokens to the project/team Doorman needs
  3. Test in staging first — create rules disabled, enable after testing
  4. Create backups before major changes (doorman backup)

Related Pages

Getting Started

Configuration

Commands

Guides

Clone this wiki locally