auth-proxy/docs/deploy.md

Deployment Instructions

Prerequisites

• Docker (v19+)
• Docker Compose (v2+)
• NGINX (with auth_request module)

Build

docker build -t yejayekhoob/auth-gate:latest .

Run

docker-compose up -d

NGINX integration

1. Create the auth-gate include file

# /etc/nginx/snippets/auth-gate.conf
#
# This is the shared auth_request configuration. Include it in any
# server block that needs authentication.
#
# Important: we use X-Real-IP (set by NGINX) rather than
# X-Forwarded-For. X-Forwarded-For is client-controlled and can be
# spoofed. If you need a CDN, configure the realip module instead
# of trusting the header.

location = /_auth_gate {
    internal;

    proxy_pass http://auth-gate:8080/auth;

    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Original-Host $host;
    proxy_set_header X-Original-URI $request_uri;
    proxy_set_header Authorization $http_authorization;
}

2. Apply the include to sensitive server blocks

server {
    listen 443 ssl;
    server_name phpmyadmin.yejayekhoob.com;

    include /etc/nginx/snippets/auth-gate.conf;

    location / {
        proxy_pass http://phpmyadmin:80/;
        # ... other proxy settings ...
    }
}

3. Test and reload

nginx -t
nginx -s reload

Environment variables

Variable	Description	Default
AUTH_GATE_PORT	HTTP listen port	8080
AUTH_GATE_API_TOKEN	API bearer token	(none)
AUTH_GATE_BASIC_USER	Basic Auth username	admin
AUTH_GATE_BASIC_PASSWORD	Basic Auth password	changeme
PERMANENT_WHITELIST_FILE	Path to permanent whitelist file	/config/permanent_whitelist.txt
DATA_DIR	Data directory	/data
CLEANUP_INTERVAL	Cleanup interval	60s
WATCH_INTERVAL	Whitelist file watch interval	30s

Permanent whitelist file

# /config/permanent_whitelist.txt
203.0.113.10
198.51.100.0/24

The file is reloaded every 30 seconds (configurable).

Graceful shutdown

docker-compose down

The service waits up to 30 seconds for in-flight requests to complete.

Hardened deployment

For production, use the Dockerfile from this repository. It:

• Builds the binary in a separate stage (smaller image).
• Runs the service as a non-root user.
• Drops all Linux capabilities.
• Sets the no-new-privileges flag.
• Mounts the whitelist file as read-only.
• Mounts /tmp as tmpfs (no persistence).