Nginx Overrides

Lerd generates one nginx config per site under ~/.local/share/lerd/nginx/conf.d/{domain}.conf. These files are fully managed: lerd link, lerd secure, lerd site rebuild, and every lerd install (including the one that runs at the end of lerd update) regenerate them from the built-in templates. Any edits made directly to those files are overwritten.

To add per-site directives that survive every regeneration, drop a snippet in ~/.local/share/lerd/nginx/custom.d/.

How it works

Every generated site vhost ends with:

include /etc/nginx/custom.d/{your-domain}.conf*;

The trailing * makes the include a glob, so nginx treats a missing override file as empty (no 500). The directory is bind-mounted read-only into the lerd-nginx container and is never touched by lerd after creation.

Example: raise the upload limit for one site

Create ~/.local/share/lerd/nginx/custom.d/bigapp.test.conf:

client_max_body_size 200m;

Then reload nginx so the include picks it up:

lerd restart bigapp.test

That's it. The snippet is merged into the generated server block for bigapp.test and nothing lerd does afterwards (including a version upgrade) will touch it.

Scope

Lines you put in custom.d/{domain}.conf land inside the site's server { ... } block, so you can use anything nginx allows at server level: client_max_body_size, add_header, extra location blocks, proxy_pass overrides, rewrite, and so on.

If you need directives at http {} level (like a new map), add them to ~/.local/share/lerd/nginx/conf.d/ with a filename that starts with an underscore (e.g. _myorg.conf). Files in conf.d/ that lerd does not know about are left alone during regeneration.

Forwarded headers and tunneling

The generated vhosts already set the X-Forwarded-* family for you so tools like lerd share, ngrok, and cloudflared work out of the box:

Forwarded source	Where it comes from
HTTP_HOST, SERVER_NAME, HTTP_X_FORWARDED_HOST	$http_x_forwarded_host, falling back to $host
HTTP_X_FORWARDED_PROTO	$http_x_forwarded_proto, falling back to $scheme
HTTP_X_FORWARDED_PORT	$server_port
HTTP_X_REAL_IP, HTTP_X_FORWARDED_FOR	$remote_addr

The fallbacks are declared once in conf.d/_forwarded.conf (generated by lerd at install time) via two map blocks that produce $real_forwarded_host and $real_forwarded_proto. Direct browser requests without X-Forwarded-* headers keep seeing the real host and scheme; tunneled requests see the public hostname the tunnel received. PHP apps that call url() or read $_SERVER['HTTP_HOST'] get correct absolute URLs in both paths without any app-side changes.