Skip to main content
Get Anubis protecting your web application in minutes using Docker. This guide walks you through a basic deployment with bot blocking and challenge verification.

​
Prerequisites

  • Docker installed
  • A web application to protect (or use the example below)

​
Quick Start

1

Create a policy file

Create policy.yaml to define which bots to block:
policy.yaml
bots:
  # Block aggressive scrapers
  - name: pathological-bots
    user_agent_regex: (?i:bot|crawler|scraper)
    action: DENY

  # Challenge AI bots
  - name: ai-bots
    user_agent_regex: (?i:gptbot|claude|anthropic|openai)
    action: CHALLENGE

# HTTP status codes for responses
status_codes:
  CHALLENGE: 200
  DENY: 200

# Storage backend (in-memory for quick start)
store:
  backend: memory

# Logging configuration
logging:
  sink: stdio
  level: INFO
2

Run Anubis with Docker

Start Anubis as a reverse proxy in front of your application:
docker run -d \
  --name anubis \
  -p 8923:8923 \
  -p 9090:9090 \
  -e BIND=":8923" \
  -e TARGET="http://localhost:3000" \
  -e DIFFICULTY="4" \
  -e POLICY_FNAME="/config/policy.yaml" \
  -v $(pwd)/policy.yaml:/config/policy.yaml:ro \
  ghcr.io/techarohq/anubis:latest
Configuration explained:
  • BIND: Network address to listen on (default: :8923)
  • TARGET: Your application’s URL to protect
  • DIFFICULTY: Challenge difficulty level (1-10, default: 4)
  • POLICY_FNAME: Path to policy configuration file
  • Port 8923: Main HTTP service
  • Port 9090: Metrics and health checks
3

Verify health status

Check that Anubis is running correctly:
curl http://localhost:9090/healthz
Expected response:
OK
4

Test bot blocking

Test that bot requests are blocked:
# This should be blocked (bot user-agent)
curl -H "User-Agent: GPTBot/1.0" http://localhost:8923

# This should work (normal browser)
curl -H "User-Agent: Mozilla/5.0" http://localhost:8923

​
Docker Compose Example

For production deployments, use Docker Compose:
docker-compose.yml
services:
  anubis:
    image: ghcr.io/techarohq/anubis:latest
    ports:
      - "8923:8923"
      - "9090:9090"
    environment:
      BIND: ":8923"
      TARGET: "http://app:3000"
      DIFFICULTY: "4"
      POLICY_FNAME: "/config/policy.yaml"
      METRICS_BIND: ":9090"
      SLOG_LEVEL: "INFO"
    volumes:
      - ./policy.yaml:/config/policy.yaml:ro
    restart: unless-stopped

  app:
    image: your-app:latest
    expose:
      - "3000"
Start the stack: 
docker-compose up -d

​
Common Configuration Options

Key environment variables from cmd/anubis/main.go:
VariableDefaultDescription
BIND:8923Network address to bind HTTP to
TARGEThttp://localhost:3923Backend application URL
DIFFICULTY4Challenge difficulty (1-10)
POLICY_FNAMEBuilt-inPath to policy YAML file
METRICS_BIND:9090Metrics endpoint address
COOKIE_EXPIRATION_TIME24hAuth cookie validity period
SLOG_LEVELINFOLogging level (DEBUG, INFO, WARN, ERROR)
USE_REMOTE_ADDRESSfalseRead client IP from network request
XFF_STRIP_PRIVATEtrueStrip private IPs from X-Forwarded-For

​
Production Policy Example

For production use, import curated bot policies:
policy.yaml
bots:
  # Block pathological scrapers
  - import: (data)/bots/_deny-pathological.yaml
  - import: (data)/bots/aggressive-brazilian-scrapers.yaml

  # Block AI/LLM bots
  - import: (data)/meta/ai-block-aggressive.yaml

  # Allow legitimate search engines
  - import: (data)/crawlers/_allow-good.yaml

  # Allow well-known routes
  - import: (data)/common/keep-internet-working.yaml

# Use persistent storage for production
store:
  backend: bbolt
  parameters:
    path: /data/anubis.bdb

# Response configuration
status_codes:
  CHALLENGE: 200
  DENY: 200

logging:
  sink: stdio
  level: INFO

​
Next Steps

Configuration Reference

Explore all configuration options

Policy Configuration

Learn about bot detection rules

Docker Deployment

Production Docker setup

Integration Guides

Integrate with reverse proxies

​
Troubleshooting

​
Health check fails

Ensure both ports are exposed and Anubis has started: 
docker logs anubis

​
Policy file not loading

Verify the volume mount and file permissions: 
docker exec anubis cat /config/policy.yaml

​
Backend connection errors

Check that TARGET points to a reachable URL from within the container: 
docker exec anubis curl -v $TARGET

Build docs developers (and LLMs) love

Get started for freeTalk to us