Skip to main content

Nginx

Use Nginx when it is already your TLS edge or you need explicit control over buffering and timeouts. This example assumes Nginx and Jiandu share a private network, where jiandu:8077 resolves to the application and Jiandu observes Nginx at 172.30.0.2.

1. Configure Jiandu​

/etc/jiandu/jiandu.json
{
  "schema_version": 1,
  "server": {
    "bind": "0.0.0.0:8077",
    "request_timeout_seconds": 30,
    "ingress": {
      "mode": "https_reverse_proxy",
      "public_origin": "https://documents.example.net",
      "trusted_proxy_cidrs": ["172.30.0.2/32"]
    }
  }
}

If Nginx and Jiandu run directly on one host, bind Jiandu to 127.0.0.1:8077, proxy to that address, and trust 127.0.0.1/32 instead.

2. Install the HTTPS virtual host​

/etc/nginx/conf.d/jiandu.conf
server {
    listen 80;
    listen [::]:80;
    server_name documents.example.net;
    return 308 https://$host$request_uri;
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name documents.example.net;

    ssl_certificate /etc/nginx/tls/fullchain.pem;
    ssl_certificate_key /etc/nginx/tls/privkey.pem;
    add_header Strict-Transport-Security "max-age=31536000" always;

    client_max_body_size 17m;

    location / {
        proxy_http_version 1.1;
        proxy_pass http://jiandu:8077;

        proxy_hide_header Strict-Transport-Security;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $remote_addr;

        proxy_set_header X-Jiandu-Proxy-Secret "";
        proxy_set_header X-Auth-Subject "";
        proxy_set_header X-Auth-Name "";
        proxy_set_header X-Auth-Groups "";

        proxy_request_buffering off;
        proxy_buffering off;
        proxy_read_timeout 1h;
        proxy_send_timeout 1h;
    }
}

Issue the certificate with your existing ACME client or internal PKI, then place its full chain and private key at the configured paths. The HTTPS server should not start with a placeholder or self-signed certificate that clients do not trust.

Why each directive is present​

DirectivePurpose and caveat
HTTP return 308Moves accidental plaintext requests to the canonical HTTPS endpoint without changing the method. You may omit port 80 after certificate issuance if clients never need redirects.
server_nameRoutes only the configured hostname. It must match Jiandu's public_origin. Do not make the Jiandu block the default catch-all server.
ssl_certificate*Terminates TLS at Nginx. Use the full chain so browsers can build trust correctly.
add_header ... alwaysAdds HSTS even to error responses. Nginx hides Jiandu's duplicate header below, leaving one edge-owned policy.
client_max_body_size 17mCaps one HTTP request, not the complete document. It leaves room above Jiandu's 8 MiB resumable-upload chunk ceiling and rejects unexpectedly large single requests at the edge.
proxy_http_version 1.1Keeps upstream streaming and persistent connections predictable.
proxy_passNames the private upstream. Do not configure this as a public address that loops back through Nginx.
Host $http_hostPreserves the external authority, including a custom port, for Jiandu's exact host check. $host alone can lose that port.
X-Forwarded-Proto httpsOverwrites a client header with the scheme Nginx actually terminated.
X-Forwarded-For $remote_addrStarts a new trusted value from the connected client. Do not use $proxy_add_x_forwarded_for on an Internet-facing Nginx unless a separately configured upstream proxy is trusted and validated.
empty X-Jiandu-*/X-Auth-*Removes browser-supplied authentication authority. Add every assertion header named in a trusted-proxy provider.
buffering offStreams large request and response bodies rather than writing the whole transfer to Nginx temporary storage.
one-hour timeoutsPermit slow transfers. Set them to an intentional limit based on the largest document and slowest supported client.

The exact semantics of proxy_set_header, buffering, and timeouts are documented by the Nginx proxy module.

If another load balancer or CDN sits before Nginx, $remote_addr is that peer—not the browser. Keep the configuration above unless you have explicitly configured Nginx's real-IP module with the load balancer's narrow source networks. Never trust forwarding headers from arbitrary sources.

3. Check and reload safely​

nginx -t
nginx -s reload
curl --fail --silent https://documents.example.net/api/v1/health/ready
curl --silent --show-error --head https://documents.example.net/ | grep -i strict-transport-security

Test an upload larger than a single chunk as well as a download from a realistically slow client. A 413 Request Entity Too Large is Nginx's body limit. A 504 Gateway Timeout during a transfer usually means one of the proxy timeouts is too short. A Jiandu 421 ingress_not_allowed means the direct Nginx address or forwarded host does not match Jiandu's configured boundary.

Last updated on