Quick Start

Get Anubis running in 5 minutes with Docker

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:

Variable	Default	Description
BIND	:8923	Network address to bind HTTP to
TARGET	http://localhost:3923	Backend application URL
DIFFICULTY	4	Challenge difficulty (1-10)
POLICY_FNAME	Built-in	Path to policy YAML file
METRICS_BIND	:9090	Metrics endpoint address
COOKIE_EXPIRATION_TIME	24h	Auth cookie validity period
SLOG_LEVEL	INFO	Logging level (DEBUG, INFO, WARN, ERROR)
USE_REMOTE_ADDRESS	false	Read client IP from network request
XFF_STRIP_PRIVATE	true	Strip 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