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

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

```mermaid theme={null}
flowchart LR
    user[User]
    nginx[nginx :443]
    anubis[Anubis :3000]
    backend[Backend]
    
    user -->|HTTPS| nginx
    nginx -->|HTTP| anubis
    anubis -->|Validated| backend
```

### Pattern 2: External Auth Mode

nginx uses Anubis as an authentication service:

```mermaid theme={null}
flowchart LR
    user[User]
    nginx[nginx :443]
    anubis[Anubis :8923]
    backend[Backend]
    
    user -->|HTTPS| nginx
    nginx -.->|auth_request| anubis
    anubis -.->|200/401| nginx
    nginx -->|Validated| backend
```

## Reverse Proxy Configuration

### Upstream Definition

Define Anubis as an upstream in `/etc/nginx/conf.d/upstream-anubis.conf`:

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

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

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

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

```bash theme={null}
anubis --bind :8923 --target " " --redirect-domains example.com
```

**nginx configuration:**

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

```bash theme={null}
anubis --bind unix:///run/anubis/anubis.sock \
       --socket-mode 0770 \
       --target http://backend:8080
```

**nginx upstream:**

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

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

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

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

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

```bash theme={null}
tail -f /var/log/nginx/access.log
```

## Performance Tuning

### Connection Keepalive

```nginx theme={null}
upstream anubis {
  server anubis:3000;
  keepalive 32;
}

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

### Buffering

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