> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/TecharoHq/Anubis/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker Installation

> Deploy Anubis using Docker containers

Anubis is distributed as a Docker image in the GitHub Container Registry at [`ghcr.io/techarohq/anubis`](https://github.com/TecharoHQ/anubis/pkgs/container/anubis).

## Available Tags

| Tag          | Description                                                                                            |
| ------------ | ------------------------------------------------------------------------------------------------------ |
| `latest`     | The latest [tagged release](https://github.com/TecharoHQ/anubis/releases). Recommended for production. |
| `v<version>` | A specific [tagged release](https://github.com/TecharoHQ/anubis/tags). Use for version pinning.        |
| `main`       | The current build from the `main` branch. Use only if you need unreleased features.                    |

## Quick Start

<Steps>
  <Step title="Pull the Docker image">
    ```bash theme={null}
    docker pull ghcr.io/techarohq/anubis:latest
    ```
  </Step>

  <Step title="Create a policy file">
    Create a `botPolicy.yaml` file to configure bot detection rules:

    ```yaml theme={null}
    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](/admin/policy-configuration).
  </Step>

  <Step title="Run the container">
    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Verify the deployment">
    Check that Anubis is running by accessing the health check endpoint:

    ```bash theme={null}
    curl http://localhost:9090/healthz
    ```

    You should receive an `OK` response.
  </Step>
</Steps>

## Docker Compose

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

<CodeGroup>
  ```yaml docker-compose.yml theme={null}
  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
  ```

  ```yaml With Unix Sockets theme={null}
  services:
    anubis:
      image: ghcr.io/techarohq/anubis:latest
      environment:
        BIND: "/run/anubis/anubis.sock"
        BIND_NETWORK: "unix"
        SOCKET_MODE: "0770"
        METRICS_BIND: ":9090"
        TARGET: "http://app:3000"
        POLICY_FNAME: "/config/botPolicy.yaml"
      volumes:
        - "anubis-socket:/run/anubis"
        - "./botPolicy.yaml:/config/botPolicy.yaml:ro"
      restart: unless-stopped

    nginx:
      image: nginx:alpine
      volumes:
        - "anubis-socket:/run/anubis"
        - "./nginx.conf:/etc/nginx/nginx.conf:ro"
      ports:
        - "80:80"
      depends_on:
        - anubis

  volumes:
    anubis-socket:
  ```
</CodeGroup>

## 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](/installation/configuration).

## Volume Mounts

<Warning>
  The Docker image runs as user ID `1000` and group ID `1000`. Ensure mounted volumes are readable by this user.
</Warning>

### Policy File

Mount your bot policy configuration:

```bash theme={null}
-v /path/to/botPolicy.yaml:/config/botPolicy.yaml:ro
```

Set the environment variable:

```bash theme={null}
-e POLICY_FNAME=/config/botPolicy.yaml
```

### Signing Key

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

```bash theme={null}
-v /path/to/anubis.key:/secrets/anubis.key:ro
```

Generate a key:

```bash theme={null}
openssl rand -hex 32 > anubis.key
chmod 600 anubis.key
```

Set the environment variable:

```bash theme={null}
-e ED25519_PRIVATE_KEY_HEX_FILE=/secrets/anubis.key
```

### Unix Sockets

When using Unix domain sockets, create a shared volume:

```yaml theme={null}
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:

```bash theme={null}
curl http://localhost:9090/healthz
```

Returns `OK` when Anubis is serving traffic.

### Docker Health Check

Use the built-in `--healthcheck` flag:

```yaml theme={null}
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

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

## Prometheus Metrics

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

```bash theme={null}
curl http://localhost:9090/metrics
```

Add this to your Prometheus configuration:

```yaml theme={null}
scrape_configs:
  - job_name: 'anubis'
    static_configs:
      - targets: ['anubis:9090']
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/docs/installation/configuration">
    Learn about all configuration options
  </Card>

  <Card title="Bot Policies" icon="shield" href="/docs/admin/policies">
    Configure bot detection rules
  </Card>

  <Card title="Reverse Proxy Setup" icon="server" href="/docs/admin/environments/nginx">
    Integrate with Nginx, Caddy, or other proxies
  </Card>

  <Card title="Environment Examples" icon="books" href="/docs/category/environments">
    Platform-specific deployment guides
  </Card>
</CardGroup>