> ## Documentation Index
> Fetch the complete documentation index at: https://verifyngo.chocolatemoo53.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Put verifyngo behind a reverse proxy: Nginx, Caddy, Traefik

> Set up Nginx, Caddy, or Traefik to send all traffic to verifyngo first, so bot filtering runs before requests reach your upstream app.

verifyngo acts as a proxy itself, so your public-facing reverse proxy should forward traffic to verifyngo, which in turn forwards verified requests to your app. The flow looks like this:

```text theme={null}
visitor → Nginx / Caddy / Traefik → verifyngo :8080 → your upstream app
```

This guide shows minimal config for each of the three most common reverse proxies.

> [!TIP]
>
> Whenever you put a reverse proxy in front of verifyngo, enable `trust_real_ip: true` in verifyngo's config and add the proxy's IP to `trusted_proxies`. Without this, verifyngo sees the proxy's IP as the client IP instead of the real visitor's IP, which breaks IP-based rules and ban tracking.

## Proxy configuration

Pick the reverse proxy you're using and follow the snippet for your stack.

> [tab] Nginx
>
> Add a `proxy_pass` block that points to verifyngo on `127.0.0.1:8080`. Forward the standard headers so verifyngo can read the real client IP and protocol:
>
> ```nginx nginx.conf theme={null}
> server {
>     listen 80;
>     server_name example.com;
>
>     location / {
>         proxy_pass          http://127.0.0.1:8080;
>         proxy_set_header    Host              $host;
>         proxy_set_header    X-Forwarded-For   $proxy_add_x_forwarded_for;
>         proxy_set_header    X-Forwarded-Proto $scheme;
>     }
> }
> ```
>
> After editing, test and reload Nginx:
>
> ```bash theme={null}
> nginx -t && nginx -s reload
> ```

> [tab] Caddy
>
> Caddy's `reverse_proxy` directive is all you need. Caddy automatically appends the client's IP to `X-Forwarded-For`, so no extra header configuration is required:
>
> ```caddy Caddyfile theme={null}
> example.com {
>     reverse_proxy 127.0.0.1:8080
> }
> ```
>
> Reload Caddy after saving:
>
> ```bash theme={null}
> caddy reload
> ```

> [tab] Traefik
>
> If you run verifyngo with Docker Compose alongside a Traefik container, add labels to the `verifyngo` service to register it as a Traefik backend:
>
> ```yaml docker-compose.yml theme={null}
> services:
>   verifyngo:
>     image: ghcr.io/chocolatemoo53/verifyngo:latest
>     labels:
>       - "traefik.enable=true"
>       - "traefik.http.routers.verifyngo.rule=Host(`example.com`)"
>       - "traefik.http.routers.verifyngo.entrypoints=web"
>       - "traefik.http.services.verifyngo.loadbalancer.server.port=8080"
> ```
>
> Traefik forwards `X-Forwarded-For` automatically. Make sure your Traefik instance has `--entryPoints.web.forwardedHeaders.insecure=false` (or equivalent trusted IP config) so the header is not spoofable.

## trust\_real\_ip config

After setting up your reverse proxy, update your `config.json` to tell verifyngo to trust the forwarded IP header:

```json config.json theme={null}
{
  "trust_real_ip": true,
  "trusted_proxies": ["127.0.0.1"]
}
```

| Key | Description |
| - | - |
| `trust_real_ip` | When `true`, verifyngo reads the client IP from `X-Forwarded-For` instead of the TCP connection's remote address. |
| `trusted_proxies` | A list of IPs or CIDR ranges whose `X-Forwarded-For` headers verifyngo will accept. Requests arriving from any other address are treated as untrusted. |

**Automatic trust for private addresses:** if `trusted_proxies` is empty, verifyngo automatically trusts loopback and private-range IPs — specifically any address that is a loopback address or falls within a private IP range. This covers the common case where your reverse proxy and verifyngo run on the same host or inside the same private Docker network.

**Public-IP proxies:** if your proxy connects from a public IP (for example, a cloud load balancer), the automatic trust does not apply. List the proxy's IP explicitly in `trusted_proxies`:

```json config.json theme={null}
{
  "trust_real_ip": true,
  "trusted_proxies": ["203.0.113.42"]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.