> ## 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.

# Native Installation

> Install Anubis using native packages or binaries

Anubis can be installed directly on your system using native packages for Debian, Red Hat, or as a standalone binary.

## Downloading Anubis

Download the appropriate package for your system from the [latest GitHub release](https://github.com/TecharoHQ/anubis/releases).

## Installation Methods

<Tabs>
  <Tab title="Debian/Ubuntu (apt)">
    <Steps>
      <Step title="Install the package">
        ```bash theme={null}
        sudo apt install ./anubis-$VERSION-$ARCH.deb
        ```

        This installs:

        * Binary at `/usr/bin/anubis`
        * Systemd service template at `/etc/systemd/system/anubis@.service`
        * Default configuration at `/etc/anubis/default.env`
        * Example policy file at `/usr/share/doc/anubis/botPolicies.yaml`
      </Step>

      <Step title="Create instance configuration">
        Copy the default configuration for your service (e.g., for Gitea):

        ```bash theme={null}
        sudo cp /etc/anubis/default.env /etc/anubis/gitea.env
        ```
      </Step>

      <Step title="Copy the policy file">
        ```bash theme={null}
        sudo cp /usr/share/doc/anubis/botPolicies.yaml /etc/anubis/gitea.botPolicies.yaml
        ```
      </Step>

      <Step title="Configure the instance">
        Edit `/etc/anubis/gitea.env` with your settings:

        ```bash theme={null}
        BIND=[::1]:8239
        BIND_NETWORK=tcp
        DIFFICULTY=4
        METRICS_BIND=[::1]:8240
        METRICS_BIND_NETWORK=tcp
        POLICY_FNAME=/etc/anubis/gitea.botPolicies.yaml
        TARGET=http://localhost:3000
        ```
      </Step>

      <Step title="Enable and start the service">
        ```bash theme={null}
        sudo systemctl enable --now anubis@gitea.service
        ```
      </Step>

      <Step title="Verify it's running">
        ```bash theme={null}
        curl http://[::1]:8240/metrics
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Red Hat/Fedora/CentOS (rpm)">
    <Steps>
      <Step title="Install the package">
        Using `dnf`:

        ```bash theme={null}
        sudo dnf -y install ./anubis-$VERSION.$ARCH.rpm
        ```

        Or using `yum`:

        ```bash theme={null}
        sudo yum -y install ./anubis-$VERSION.$ARCH.rpm
        ```

        Or using `rpm` directly:

        ```bash theme={null}
        sudo rpm -ivh ./anubis-$VERSION.$ARCH.rpm
        ```

        This installs:

        * Binary at `/usr/bin/anubis`
        * Systemd service template at `/etc/systemd/system/anubis@.service`
        * Default configuration at `/etc/anubis/default.env`
        * Example policy file at `/usr/share/doc/anubis/botPolicies.yaml`
      </Step>

      <Step title="Create instance configuration">
        Copy the default configuration for your service (e.g., for Gitea):

        ```bash theme={null}
        sudo cp /etc/anubis/default.env /etc/anubis/gitea.env
        ```
      </Step>

      <Step title="Copy the policy file">
        ```bash theme={null}
        sudo cp /usr/share/doc/anubis/botPolicies.yaml /etc/anubis/gitea.botPolicies.yaml
        ```
      </Step>

      <Step title="Configure the instance">
        Edit `/etc/anubis/gitea.env` with your settings:

        ```bash theme={null}
        BIND=[::1]:8239
        BIND_NETWORK=tcp
        DIFFICULTY=4
        METRICS_BIND=[::1]:8240
        METRICS_BIND_NETWORK=tcp
        POLICY_FNAME=/etc/anubis/gitea.botPolicies.yaml
        TARGET=http://localhost:3000
        ```
      </Step>

      <Step title="Enable and start the service">
        ```bash theme={null}
        sudo systemctl enable --now anubis@gitea.service
        ```
      </Step>

      <Step title="Verify it's running">
        ```bash theme={null}
        curl http://[::1]:8240/metrics
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Tarball (Generic Linux)">
    <Steps>
      <Step title="Extract the tarball">
        ```bash theme={null}
        tar zxf ./anubis-$VERSION-$OS-$ARCH.tar.gz
        cd anubis-$VERSION-$OS-$ARCH
        ```
      </Step>

      <Step title="Install the binary">
        ```bash theme={null}
        sudo install -D ./bin/anubis /usr/local/bin/anubis
        ```
      </Step>

      <Step title="Update the systemd unit path">
        ```bash theme={null}
        perl -pi -e 's$/usr/bin/anubis$/usr/local/bin/anubis$g' ./run/anubis@.service
        ```
      </Step>

      <Step title="Install systemd service">
        ```bash theme={null}
        sudo install -D ./run/anubis@.service /etc/systemd/system/anubis@.service
        ```
      </Step>

      <Step title="Install default configuration">
        ```bash theme={null}
        sudo install -D ./run/default.env /etc/anubis/default.env
        ```
      </Step>

      <Step title="Create instance configuration">
        ```bash theme={null}
        sudo cp /etc/anubis/default.env /etc/anubis/gitea.env
        ```
      </Step>

      <Step title="Copy the policy file">
        ```bash theme={null}
        sudo cp ./doc/botPolicies.yaml /etc/anubis/gitea.botPolicies.yaml
        ```
      </Step>

      <Step title="Configure the instance">
        Edit `/etc/anubis/gitea.env` with your settings:

        ```bash theme={null}
        BIND=[::1]:8239
        BIND_NETWORK=tcp
        DIFFICULTY=4
        METRICS_BIND=[::1]:8240
        METRICS_BIND_NETWORK=tcp
        POLICY_FNAME=/etc/anubis/gitea.botPolicies.yaml
        TARGET=http://localhost:3000
        ```
      </Step>

      <Step title="Reload systemd and start the service">
        ```bash theme={null}
        sudo systemctl daemon-reload
        sudo systemctl enable --now anubis@gitea.service
        ```
      </Step>

      <Step title="Verify it's running">
        ```bash theme={null}
        curl http://[::1]:8240/metrics
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Distribution Package Manager">
    Some Linux distributions include Anubis in their official repositories. Check [Repology](https://repology.org/project/anubis-anti-crawler/versions) for availability.

    The package name varies by distribution:

    * `anubis` (most distributions)
    * `www-apps/anubis` (Gentoo)
    * `www/anubis` (BSD ports)

    <Steps>
      <Step title="Install via package manager">
        Example for distributions with `anubis` in repos:

        ```bash theme={null}
        # Example - check your distribution's documentation
        sudo apt install anubis
        # or
        sudo dnf install anubis
        ```
      </Step>

      <Step title="Follow systemd setup">
        If your distribution uses systemd, follow the configuration steps from the Debian or Red Hat tabs above.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Systemd Service Configuration

### Service Template

Anubis uses a systemd service template (`anubis@.service`) that allows running multiple instances. The instance name (e.g., `gitea`) determines which configuration file to load:

* Service: `anubis@gitea.service`
* Config file: `/etc/anubis/gitea.env`

### Managing Services

<CodeGroup>
  ```bash Start Service theme={null}
  sudo systemctl start anubis@gitea.service
  ```

  ```bash Stop Service theme={null}
  sudo systemctl stop anubis@gitea.service
  ```

  ```bash Restart Service theme={null}
  sudo systemctl restart anubis@gitea.service
  ```

  ```bash View Status theme={null}
  sudo systemctl status anubis@gitea.service
  ```

  ```bash View Logs theme={null}
  sudo journalctl -u anubis@gitea.service -f
  ```

  ```bash Enable on Boot theme={null}
  sudo systemctl enable anubis@gitea.service
  ```
</CodeGroup>

## Configuration Files

### Environment File Format

Configuration files in `/etc/anubis/` use environment variable syntax:

```bash theme={null}
# /etc/anubis/gitea.env
BIND=[::1]:8239
BIND_NETWORK=tcp
DIFFICULTY=4
METRICS_BIND=[::1]:8240
POLICY_FNAME=/etc/anubis/gitea.botPolicies.yaml
TARGET=http://localhost:3000
COOKIE_DOMAIN=example.com
COOKIE_EXPIRATION_TIME=168h
SLOG_LEVEL=INFO
```

See the [Configuration reference](/installation/configuration) for all available options.

### Policy Files

Bot policy files use YAML format:

```yaml theme={null}
# /etc/anubis/gitea.botPolicies.yaml
bots:
  - name: "OpenAI GPTBot"
    rules:
      userAgentContains: "GPTBot"
    action: deny

  - name: "Common crawlers"
    rules:
      userAgentContains: "bot"
    action: challenge
```

For more details, see the [Bot Policies documentation](/admin/policy-configuration).

## Running Multiple Instances

Protect multiple services by creating separate configuration files:

```bash theme={null}
# Protect Gitea on port 8239
sudo cp /etc/anubis/default.env /etc/anubis/gitea.env
sudo systemctl enable --now anubis@gitea.service

# Protect another service on port 8241
sudo cp /etc/anubis/default.env /etc/anubis/myapp.env
sudo systemctl enable --now anubis@myapp.service
```

Each instance runs independently with its own configuration.

## Health Checks

### HTTP Health Endpoint

Check if Anubis is running:

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

Returns `OK` when Anubis is serving traffic.

### Built-in Health Check

Use the `--healthcheck` flag:

```bash theme={null}
anubis --healthcheck
```

Exits with code 0 if healthy, non-zero otherwise.

## Signing Keys

<Warning>
  When using persistent storage backends or running multiple Anubis instances behind the same load balancer, you must configure a signing key.
</Warning>

Generate an ED25519 private key:

```bash theme={null}
openssl rand -hex 32 | sudo tee /etc/anubis/signing.key
sudo chmod 600 /etc/anubis/signing.key
sudo chown root:root /etc/anubis/signing.key
```

Add to your configuration file:

```bash theme={null}
ED25519_PRIVATE_KEY_HEX_FILE=/etc/anubis/signing.key
```

All instances protecting the same domain must use the same signing key.

## Reverse Proxy Integration

After installing Anubis, configure your reverse proxy to route traffic through it:

<CardGroup cols={3}>
  <Card title="Nginx" icon="server" href="/docs/admin/environments/nginx">
    Configure Nginx reverse proxy
  </Card>

  <Card title="Apache" icon="server" href="/docs/admin/environments/apache">
    Configure Apache reverse proxy
  </Card>

  <Card title="Caddy" icon="server" href="/docs/admin/environments/caddy">
    Configure Caddy reverse proxy
  </Card>

  <Card title="HAProxy" icon="server" href="/docs/admin/environments/haproxy">
    Configure HAProxy
  </Card>

  <Card title="Traefik" icon="server" href="/docs/admin/environments/traefik">
    Configure Traefik
  </Card>

  <Card title="Kubernetes" icon="dharmachakra" href="/docs/admin/environments/kubernetes">
    Deploy on Kubernetes
  </Card>
</CardGroup>

## Troubleshooting

### Service won't start

Check the logs:

```bash theme={null}
sudo journalctl -u anubis@gitea.service -n 50
```

Common issues:

* Port already in use (check `BIND` and `METRICS_BIND`)
* Invalid policy file path or syntax
* Missing signing key with persistent storage

### Permission denied errors

Ensure configuration files are readable:

```bash theme={null}
sudo chmod 644 /etc/anubis/gitea.env
sudo chmod 644 /etc/anubis/gitea.botPolicies.yaml
```

### Can't reach target service

Verify the `TARGET` URL is correct and the service is running:

```bash theme={null}
curl http://localhost:3000  # Replace with your TARGET
```

## Next Steps

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

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