BackupX/docs-site/docs/deployment/nginx.md

sidebar_position, title, description

sidebar_position	title	description
3	Nginx Reverse Proxy	Expose BackupX behind Nginx with HTTPS and SSE-friendly buffering disabled.

Nginx Reverse Proxy

A minimal production-ready Nginx site for BackupX:

server {
    listen 80;
    server_name backup.example.com;

    # Static UI (served from /opt/backupx/web)
    location / {
        root /opt/backupx/web;
        try_files $uri $uri/ /index.html;
    }

    # API reverse proxy
    location /api/ {
        proxy_pass http://127.0.0.1:8340;
        proxy_http_version 1.1;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
        proxy_set_header X-Forwarded-Port $server_port;
        proxy_set_header Connection "";

        # Large uploads (restore flow)
        client_max_body_size 0;
        proxy_request_buffering off;

        # Live log stream uses SSE — buffering must be off
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }

    # Compatibility route for installers generated by older releases.
    # Current installers use /api/install/ through the API block above.
    location /install/ {
        proxy_pass http://127.0.0.1:8340/install/;
        proxy_http_version 1.1;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $http_host;
        proxy_set_header X-Forwarded-Port $server_port;
    }

    # Keep probes and metrics out of the SPA fallback.
    location = /health { proxy_pass http://127.0.0.1:8340/health; }
    location = /ready  { proxy_pass http://127.0.0.1:8340/ready; }
    location = /metrics { proxy_pass http://127.0.0.1:8340/metrics; }
}

proxy_request_buffering off is required for Master-relay cluster backups. Without it, Nginx writes the complete Agent upload to its temporary storage before BackupX receives it, defeating streaming and potentially filling the proxy disk.

If Nginx runs on another host or in another container, add only that proxy IP or subnet to server.trusted_proxies. Do not use 0.0.0.0/0; BackupX uses the trusted client address for login throttling, install-token throttling, and audit records.

/health, /ready, and /metrics do not require BackupX authentication. Allow probe and Prometheus source networks explicitly, or keep these locations on an internal listener instead of exposing them to the Internet.

HTTPS with certbot

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d backup.example.com

Certbot rewrites the config to listen on 443 with auto-renewal.

:::caution Agent needs a stable URL If Master is behind HTTPS, remote Agent deployments must use the final HTTPS URL for --master; redirects are not followed. For a private CA, pre-provision its PEM certificate and use --ca-cert /path/to/ca.pem. Reserve --insecure-tls for short-lived testing. :::