nginx Deployment

Deploy Anubis behind nginx reverse proxy

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)