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 .
Installation Methods
Install the package
sudo apt install ./anubis- $VERSION - $ARCH .deb
This installs:
Binary at /usr/bin/anubis
Systemd service template at /etc/systemd/system/[email protected]
Default configuration at /etc/anubis/default.env
Example policy file at /usr/share/doc/anubis/botPolicies.yaml
Create instance configuration
Copy the default configuration for your service (e.g., for Gitea): sudo cp /etc/anubis/default.env /etc/anubis/gitea.env
Copy the policy file
sudo cp /usr/share/doc/anubis/botPolicies.yaml /etc/anubis/gitea.botPolicies.yaml
Configure the instance
Edit /etc/anubis/gitea.env with your settings: 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
Enable and start the service
Verify it's running
curl http://[::1]:8240/metrics
Install the package
Using dnf: sudo dnf -y install ./anubis- $VERSION . $ARCH .rpm
Or using yum: sudo yum -y install ./anubis- $VERSION . $ARCH .rpm
Or using rpm directly: sudo rpm -ivh ./anubis- $VERSION . $ARCH .rpm
This installs:
Binary at /usr/bin/anubis
Systemd service template at /etc/systemd/system/[email protected]
Default configuration at /etc/anubis/default.env
Example policy file at /usr/share/doc/anubis/botPolicies.yaml
Create instance configuration
Copy the default configuration for your service (e.g., for Gitea): sudo cp /etc/anubis/default.env /etc/anubis/gitea.env
Copy the policy file
sudo cp /usr/share/doc/anubis/botPolicies.yaml /etc/anubis/gitea.botPolicies.yaml
Configure the instance
Edit /etc/anubis/gitea.env with your settings: 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
Enable and start the service
Verify it's running
curl http://[::1]:8240/metrics
Extract the tarball
tar zxf ./anubis- $VERSION - $OS - $ARCH .tar.gz cd anubis- $VERSION - $OS - $ARCH
Install the binary
sudo install -D ./bin/anubis /usr/local/bin/anubis
Update the systemd unit path
Install default configuration
sudo install -D ./run/default.env /etc/anubis/default.env
Create instance configuration
sudo cp /etc/anubis/default.env /etc/anubis/gitea.env
Copy the policy file
sudo cp ./doc/botPolicies.yaml /etc/anubis/gitea.botPolicies.yaml
Configure the instance
Edit /etc/anubis/gitea.env with your settings: 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
Reload systemd and start the service
Verify it's running
curl http://[::1]:8240/metrics
Some Linux distributions include Anubis in their official repositories. Check Repology for availability. The package name varies by distribution:
anubis (most distributions)www-apps/anubis (Gentoo)www/anubis (BSD ports)
Install via package manager
Example for distributions with anubis in repos: # Example - check your distribution's documentation sudo apt install anubis # or sudo dnf install anubis
Follow systemd setup
If your distribution uses systemd, follow the configuration steps from the Debian or Red Hat tabs above.
Systemd Service Configuration Service Template Anubis uses a systemd service template ([email protected] gitea) determines which configuration file to load:
Managing Services Start Service
Stop Service
Restart Service
View Status
View Logs
Enable on Boot
Configuration Files Configuration files in /etc/anubis/ use environment variable syntax:
# /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 for all available options.
Policy Files Bot policy files use YAML format:
# /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 .
Running Multiple Instances Protect multiple services by creating separate configuration files:
# Protect Gitea on port 8239 sudo cp /etc/anubis/default.env /etc/anubis/gitea.env sudo systemctl enable --now [email protected] # Protect another service on port 8241 sudo cp /etc/anubis/default.env /etc/anubis/myapp.env sudo systemctl enable --now [email protected]
Each instance runs independently with its own configuration.
Health Checks HTTP Health Endpoint Check if Anubis is running:
curl http://localhost:9090/healthz
Returns OK when Anubis is serving traffic.
Built-in Health Check Use the --healthcheck flag:
Exits with code 0 if healthy, non-zero otherwise.
Signing Keys When using persistent storage backends or running multiple Anubis instances behind the same load balancer, you must configure a signing key.
Generate an ED25519 private key:
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:
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:
Nginx Configure Nginx reverse proxy
Apache Configure Apache reverse proxy
Caddy Configure Caddy reverse proxy
Kubernetes Deploy on Kubernetes
Troubleshooting Service won’t start Check the logs:
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:
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:
curl http://localhost:3000 # Replace with your TARGET
Next Steps
Configuration Explore all configuration options
Bot Policies Configure bot detection rules