Getting Started

Getting Started

Get up and running with Doorman in just a few minutes.

Installation

Install Doorman using your preferred package manager:

# npm
npm install @gfargo/doorman

# yarn
yarn add @gfargo/doorman

# pnpm
pnpm add @gfargo/doorman

# bun
bun add @gfargo/doorman

Tip: Doorman supports Vercel Firewall (stable), Cloudflare WAF (beta), and Fastly Next-Gen WAF (beta). Use --provider cloudflare or --provider fastly to target them.

Existing Projects

If you have an existing Vercel project with firewall rules, start by using the download command to set up your local configuration:

npx @gfargo/doorman download

This generates a .doorman.json file with your existing configuration. To pull your Cloudflare WAF or Fastly Next-Gen WAF configuration into the same project, run npx @gfargo/doorman download --provider cloudflare or --provider fastly.

Note: If you have an existing vercel-firewall.config.json, Doorman will still find and use it automatically. The new default filename is .doorman.json but both are supported.

Basic Usage

1. Create a Configuration File

Ensure you have a .doorman.json file in your project root:

{
  "projectId": "prj_",
  "teamId": "team_",
  "rules": [],
  "ips": []
}

Replace prj_ and team_ with your actual projectId and teamId from Vercel.

2. Add Firewall Rules

You can add rules in several ways:

Using the add Command (Recommended)

The fastest way to add rules from the command line:

# Interactive mode — guided prompts walk you through it
npx @gfargo/doorman add --interactive

# Inline mode — one-liner for scripting
npx @gfargo/doorman add --name "Block Admin" --field path --op pre --value "/admin" --action deny

# Add an IP blocking rule
npx @gfargo/doorman add ip --ip 192.168.1.100/32 --notes "Blocked for abuse"

Using Templates

Use the template command to add predefined rules:

# List available templates
npx @gfargo/doorman template

# Add WordPress protection
npx @gfargo/doorman template wordpress

# Block AI bots
npx @gfargo/doorman template ai-bots

Manual Configuration

Add rules directly to your config file:

{
  "name": "Block API Access",
  "description": "Block access to API endpoints",
  "conditionGroup": [
    {
      "conditions": [
        {
          "type": "path",
          "op": "pre",
          "value": "/api"
        }
      ]
    }
  ],
  "action": {
    "mitigate": {
      "action": "deny",
      "rateLimit": {
        "requests": 100,
        "window": "1m"
      },
      "actionDuration": "1h"
    }
  },
  "active": true
}

Rule Components

• Condition Groups — Define when rules trigger (AND within groups, OR between groups)
• Conditions — Match criteria using type, op, and value
• Actions — Define response (log, deny, challenge, bypass, rate_limit, redirect)
• Metadata — Rule information (name, description, active)

For more examples and templates, visit the examples folder on GitHub.

3. Sync Your Rules

npx @gfargo/doorman sync --token YOUR_VERCEL_API_TOKEN

This applies your firewall rules to your Vercel project. Learn how to create and use a Vercel API token.

4. Add Script Aliases (Optional)

Add convenience scripts to your package.json:

{
  "scripts": {
    "firewall:list": "doorman list",
    "firewall:download": "doorman download",
    "firewall:sync": "doorman sync",
    "firewall:validate": "doorman validate"
  }
}

Now you can run npm run firewall:sync to apply your firewall rules.

Environment Variables

Variables can be provided through a .env file, shell exports, or CI/CD environment settings:

VERCEL_TOKEN=your_vercel_api_token
VERCEL_PROJECT_ID=your_project_id
VERCEL_TEAM_ID=your_team_id

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

Next Steps

• Configuration — Deep dive into the configuration format
• Commands Overview — Full reference for all CLI commands
• Examples — Real-world configuration examples
• Templates — Pre-built rule templates