Docker Installation

Deploy Anubis using Docker containers

Anubis is distributed as a Docker image in the GitHub Container Registry at ghcr.io/techarohq/anubis.

Available Tags

Tag	Description
latest	The latest tagged release. Recommended for production.
v<version>	A specific tagged release. Use for version pinning.
main	The current build from the main branch. Use only if you need unreleased features.

Quick Start

1. Pull the Docker image

   docker pull ghcr.io/techarohq/anubis:latest
   
2. Create a policy file

   Create a botPolicy.yaml file to configure bot detection rules:

   bots:
     - name: "OpenAI GPTBot"
       rules:
         userAgentContains: "GPTBot"
       action: deny
   
     - name: "Anthropic ClaudeBot"
       rules:
         userAgentContains: "Claude-Web"
       action: deny
   

   For more details, see the Bot Policies documentation.

3. Run the container

   docker run -d \
     --name anubis \
     -p 8923:8923 \
     -p 9090:9090 \
     -e TARGET=http://localhost:3000 \
     -e DIFFICULTY=4 \
     -e POLICY_FNAME=/config/botPolicy.yaml \
     -v $(pwd)/botPolicy.yaml:/config/botPolicy.yaml:ro \
     ghcr.io/techarohq/anubis:latest
   
4. Verify the deployment

   Check that Anubis is running by accessing the health check endpoint:

   curl http://localhost:9090/healthz
   

   You should receive an OK response.

Docker Compose

For production deployments, use Docker Compose to manage Anubis alongside your application:

docker-compose.yml

services:
  anubis:
    image: ghcr.io/techarohq/anubis:latest
    environment:
      BIND: ":8923"
      DIFFICULTY: "4"
      METRICS_BIND: ":9090"
      TARGET: "http://app:3000"
      POLICY_FNAME: "/config/botPolicy.yaml"
      ED25519_PRIVATE_KEY_HEX_FILE: "/secrets/anubis.key"
      COOKIE_DOMAIN: "example.com"
      SLOG_LEVEL: "INFO"
    healthcheck:
      test: ["CMD", "anubis", "--healthcheck"]
      interval: 5s
      timeout: 30s
      retries: 5
      start_period: 500ms
    ports:
      - "8923:8923"
      - "9090:9090"
    volumes:
      - "./botPolicy.yaml:/config/botPolicy.yaml:ro"
      - "./anubis.key:/secrets/anubis.key:ro"
    restart: unless-stopped

  app:
    image: your-app:latest
    # Your application configuration

Environment Variables

Configure Anubis using environment variables. The most commonly used options:

Variable	Default	Description
BIND	:8923	Network address for Anubis to listen on
BIND_NETWORK	tcp	Network family (tcp or unix)
TARGET	http://localhost:3923	URL of the service to protect
DIFFICULTY	4	Challenge difficulty (number of leading zeroes)
POLICY_FNAME	Built-in	Path to bot policy YAML file
METRICS_BIND	:9090	Address for Prometheus metrics and health checks
COOKIE_DOMAIN	unset	Domain for Anubis cookies (e.g., example.com)
COOKIE_EXPIRATION_TIME	168h	How long challenge passes remain valid
SLOG_LEVEL	INFO	Log level (DEBUG, INFO, WARN, ERROR)
ED25519_PRIVATE_KEY_HEX_FILE	unset	Path to signing key file (required for persistent storage)

For a complete list, see the Configuration reference.

Volume Mounts

The Docker image runs as user ID 1000 and group ID 1000. Ensure mounted volumes are readable by this user.

Policy File

Mount your bot policy configuration:

-v /path/to/botPolicy.yaml:/config/botPolicy.yaml:ro

Set the environment variable:

-e POLICY_FNAME=/config/botPolicy.yaml

Signing Key

For persistent storage backends or multi-instance deployments, mount a signing key:

-v /path/to/anubis.key:/secrets/anubis.key:ro

Generate a key:

openssl rand -hex 32 > anubis.key
chmod 600 anubis.key

Set the environment variable:

-e ED25519_PRIVATE_KEY_HEX_FILE=/secrets/anubis.key

Unix Sockets

When using Unix domain sockets, create a shared volume:

volumes:
  anubis-socket:

services:
  anubis:
    volumes:
      - "anubis-socket:/run/anubis"
    environment:
      BIND: "/run/anubis/anubis.sock"
      BIND_NETWORK: "unix"

Health Checks

Anubis provides two health check mechanisms:

HTTP Health Endpoint

Access the health check at the metrics port:

curl http://localhost:9090/healthz

Returns OK when Anubis is serving traffic.

Docker Health Check

Use the built-in --healthcheck flag:

healthcheck:
  test: ["CMD", "anubis", "--healthcheck"]
  interval: 5s
  timeout: 30s
  retries: 5
  start_period: 500ms

System Requirements

Anubis has minimal resource requirements:

• Memory: 128Mi is typically sufficient for most deployments
• CPU: Minimal CPU usage for typical workloads

Anubis may not be suitable for applications with long-lived WebSocket connections, as these maintain open connections that consume resources.

Prometheus Metrics

Anubis exposes Prometheus metrics on the metrics port (default :9090):

curl http://localhost:9090/metrics

Add this to your Prometheus configuration:

scrape_configs:
  - job_name: 'anubis'
    static_configs:
      - targets: ['anubis:9090']

Next Steps

Configuration

Learn about all configuration options

Bot Policies

Configure bot detection rules

Reverse Proxy Setup

Integrate with Nginx, Caddy, or other proxies

Environment Examples

Platform-specific deployment guides