Skip to main content
nginx is a high-performance HTTP server and reverse proxy. This guide shows how to deploy Anubis behind nginx.

​
Deployment Architecture

Two common patterns:

​
Pattern 1: Reverse Proxy Mode

nginx forwards all traffic to Anubis, which validates and forwards to the backend:

​
Pattern 2: External Auth Mode

nginx uses Anubis as an authentication service:

​
Reverse Proxy Configuration

​
Upstream Definition

Define Anubis as an upstream in /etc/nginx/conf.d/upstream-anubis.conf: 
upstream anubis {
  zone anubis_zone 64k;
  
  # TCP connection
  server anubis:3000 resolve;
  
  # OR Unix socket (if Anubis is on the same host)
  # server unix:/run/anubis/anubis.sock;
  
  # Optional: fallback to direct backend on Anubis failure
  # WARNING: This bypasses protection!
  # server unix:/run/backend.sock backup;
}

​
Server Configuration

Create a reusable include file /etc/nginx/conf-anubis.inc: 
# Forward all requests to Anubis
location / {
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_pass http://anubis;
}
Then include it in your server block: 
server {
  listen 443 ssl;
  listen [::]:443 ssl;
  http2 on;
  
  server_name example.com;
  
  ssl_certificate /path/to/cert.pem;
  ssl_certificate_key /path/to/key.pem;
  
  # Forward to Anubis
  include conf-anubis.inc;
}

​
Complete Example

Here’s a complete working configuration: docker-compose.yml 
services:
  nginx:
    image: nginx:alpine
    ports:
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./conf.d:/etc/nginx/conf.d:ro
      - ./certs:/etc/nginx/certs:ro
    depends_on:
      - anubis

  anubis:
    image: ghcr.io/techarohq/anubis:main
    environment:
      BIND: ":3000"
      TARGET: "http://backend:8080"
      POLICY_FNAME: "/etc/techaro/anubis/policy.yaml"
    volumes:
      - ./anubis-config:/etc/techaro/anubis

  backend:
    image: your-app:latest
    expose:
      - "8080"

​
External Auth Configuration

For nginx’s auth_request module, configure Anubis without a target: Anubis configuration: 
anubis --bind :8923 --target " " --redirect-domains example.com
nginx configuration: 
server {
  listen 80;
  server_name example.com;
  
  # Set headers for Anubis
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  
  # Anubis endpoints (bypass auth_request)
  location /.within.website/ {
    proxy_pass http://localhost:8923;
    auth_request off;
  }
  
  # Redirect handler
  location @redirectToAnubis {
    return 307 /.within.website/?redir=$scheme://$host$request_uri;
    auth_request off;
  }
  
  # Protected content
  location / {
    auth_request /.within.website/x/cmd/anubis/api/check;
    error_page 401 = @redirectToAnubis;
    
    # Your backend
    proxy_pass http://backend:8080;
    proxy_set_header Host $host;
  }
}

​
Unix Socket Configuration

For maximum performance when nginx and Anubis are on the same server: Anubis: 
anubis --bind unix:///run/anubis/anubis.sock \
       --socket-mode 0770 \
       --target http://backend:8080
nginx upstream: 
upstream anubis {
  server unix:/run/anubis/anubis.sock;
}
Ensure nginx has permission to access the socket (nginx user must be in the anubis group).

​
Multi-Site Configuration

You can protect multiple sites with one Anubis instance: 
# Shared upstream
upstream anubis {
  server anubis:3000;
}

server {
  listen 443 ssl;
  server_name site1.example.com;
  
  ssl_certificate /certs/site1.pem;
  ssl_certificate_key /certs/site1-key.pem;
  
  include conf-anubis.inc;
}

server {
  listen 443 ssl;
  server_name site2.example.com;
  
  ssl_certificate /certs/site2.pem;
  ssl_certificate_key /certs/site2-key.pem;
  
  include conf-anubis.inc;
}
Configure Anubis with cookie domain: 
anubis --cookie-domain example.com --bind :3000
This allows the Anubis cookie to work across all *.example.com subdomains.

​
TLS Considerations

When nginx terminates TLS and forwards HTTP to Anubis, some applications (like WordPress) may not detect HTTPS correctly. Configure your application to trust the X-Forwarded-Proto header. For WordPress, add to wp-config.php: 
if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https') {
    $_SERVER['HTTPS'] = 'on';
    $_SERVER['SERVER_PORT'] = 443;
}

​
Testing

Verify headers are being forwarded correctly: 
# Check Anubis receives correct headers
curl -H "X-Forwarded-For: 1.2.3.4" http://anubis:3000/
Check nginx logs to ensure traffic flows correctly: 
tail -f /var/log/nginx/access.log

​
Performance Tuning

​
Connection Keepalive

upstream anubis {
  server anubis:3000;
  keepalive 32;
}

location / {
  proxy_http_version 1.1;
  proxy_set_header Connection "";
  proxy_pass http://anubis;
}

​
Buffering

location / {
  proxy_buffering on;
  proxy_buffer_size 4k;
  proxy_buffers 8 4k;
  proxy_pass http://anubis;
}

​
Troubleshooting

​
Anubis sees nginx’s IP instead of client IP

Make sure you’re not using --use-remote-address when behind nginx. Anubis should read from X-Real-IP or X-Forwarded-For headers.

​
502 Bad Gateway

Check that:
  1. Anubis is running and listening on the correct address
  2. nginx can reach Anubis (check network connectivity)
  3. If using Unix socket, verify permissions

​
Redirect loops

Ensure:
  1. REDIRECT_DOMAINS includes your domain
  2. Cookie domain is set correctly
  3. HTTPS is properly detected (check X-Forwarded-Proto)

Build docs developers (and LLMs) love

Get started for freeTalk to us