nginx

package
v1.22.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 27, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EnsureCustomD added in v1.17.0 

func EnsureCustomD() error

EnsureCustomD creates the user-override directory. Lerd never writes here after creation, so user snippets survive `lerd update`.

func EnsureDefaultVhost added in v0.6.0 

func EnsureDefaultVhost() error

EnsureDefaultVhost writes a catch-all default server that shows a branded error page for any HTTP request that doesn't match a registered site. For HTTPS we cannot serve a real catch-all because browsers (Chrome especially) reject TLD-level wildcard certificates like `*.test` with ERR_CERT_COMMON_NAME_INVALID, and we can't issue per-domain certs ahead of time. ssl_reject_handshake produces a clean connection error (ERR_SSL_UNRECOGNIZED_NAME_ALERT) which is the best UX available.

The file is left alone when the user has manually edited it: lerd stores a sentinel hash of what it last wrote, and skips rewriting when the on-disk content no longer matches that hash. Removing the file (or the sentinel) restores lerd's automatic management.

func EnsureForwardedConf added in v1.17.0 

func EnsureForwardedConf() error

EnsureForwardedConf writes the shared _forwarded.conf snippet into conf.d. The "_" prefix makes it load before site vhosts.

func EnsureLerdVhost added in v1.0.2 

func EnsureLerdVhost() error

EnsureLerdVhost generates the nginx vhost for http://lerd.localhost, which reverse-proxies to the lerd-ui process running on the host so the browser's URL bar stays on lerd.localhost (no redirect to localhost:7073).

The upstream differs by platform because container → host connectivity works differently on each:

  • Linux: lerd-nginx runs in a rootless podman bridge. Reaching the host over TCP via host.containers.internal depends on netavark / pasta wiring up the 169.254.1.2 alias, which silently breaks across podman versions and host network changes. We bind-mount lerd-ui's unix socket into the container instead — filesystem access only, no networking, no detection. lerd-ui marks socket-arriving requests as loopback in isLoopbackRequest.

  • macOS: lerd-ui runs as a native macOS process and lerd-nginx runs inside the podman-machine VM. Unix sockets don't traverse the virtio-fs / 9p hypervisor boundary as functional sockets, so binding one on the macOS host doesn't help the VM. We fall back to TCP via host.containers.internal:7073 — gvproxy reliably forwards this on podman-machine, and the request carries an X-Lerd-Trust header that the gate matches against the per-install token (proxy_set_header overwrites any client-supplied value, so a LAN attacker can't inject it).

.localhost is RFC 6761 reserved and always resolves to the visiting device's loopback, so this vhost is unreachable from a LAN browser doing the obvious thing (http://lerd.localhost from a remote machine hits the remote machine's own 127.0.0.1, not the lerd server).

func EnsureNginxConfig 

func EnsureNginxConfig() error

EnsureNginxConfig copies the base nginx.conf to the data dir if it is missing.

func EnsureProfilerVhost added in v1.22.0 

func EnsureProfilerVhost() error

EnsureProfilerVhost writes the profiler.localhost vhost: a dedicated hostname routed to a PHP-FPM container so SPX serves its report UI for the dashboard's global Profiler entry, independent of any site.

func GenerateCustomSSLVhost added in v1.15.0 

func GenerateCustomSSLVhost(site config.Site) error

GenerateCustomSSLVhost renders the SSL vhost template for a custom container site and writes it to conf.d.

func GenerateCustomVhost added in v1.15.0 

func GenerateCustomVhost(site config.Site) error

GenerateCustomVhost renders the HTTP vhost template for a custom container site and writes it to conf.d. Nginx reverse-proxies to the container instead of using fastcgi_pass.

func GenerateFrankenPHPSSLVhost added in v1.18.0 

func GenerateFrankenPHPSSLVhost(site config.Site) error

GenerateFrankenPHPSSLVhost renders the HTTPS vhost template for a FrankenPHP site.

func GenerateFrankenPHPVhost added in v1.18.0 

func GenerateFrankenPHPVhost(site config.Site) error

GenerateFrankenPHPVhost renders the HTTP vhost template for a FrankenPHP site. Nginx reverse-proxies to the per-site lerd-fp-<name>:8000 container using the shared custom-container template.

func GeneratePausedVhost added in v1.0.0 

func GeneratePausedVhost(site config.Site) error

GeneratePausedVhost writes a minimal nginx vhost that serves the static paused landing page for the given site. For secured sites it also adds the HTTPS block so the redirect and TLS still work while the site is paused.

func GeneratePausedWorktreeVhost added in v1.0.1 

func GeneratePausedWorktreeVhost(domain, certDomain, pausedDir string, secured bool) error

GeneratePausedWorktreeVhost writes a paused nginx vhost for a worktree domain. certDomain is the parent site's domain whose cert files back the wildcard.

func GenerateProxyVhost added in v0.1.21 

func GenerateProxyVhost(domain, upstreamHost string, upstreamPort int) error

GenerateProxyVhost renders vhost-proxy.conf.tmpl and writes conf.d/{domain}.conf.

func GenerateSSLVhost 

func GenerateSSLVhost(site config.Site, phpVersion string) error

GenerateSSLVhost renders the SSL vhost template and writes it to conf.d.

func GenerateVhost 

func GenerateVhost(site config.Site, phpVersion string) error

GenerateVhost renders the HTTP vhost template and writes it to conf.d.

func GenerateWorktreeSSLVhost added in v0.6.0 

func GenerateWorktreeSSLVhost(domain, path, phpVersion, parentDomain, siteName, branch string) error

GenerateWorktreeSSLVhost renders the SSL vhost template for a worktree checkout, reusing the parent site's wildcard certificate (*.parentDomain).

func GenerateWorktreeVhost added in v0.6.0 

func GenerateWorktreeVhost(domain, path, phpVersion, siteName, branch string) error

GenerateWorktreeVhost renders the HTTP vhost template for a worktree checkout and writes it to conf.d/<domain>.conf.

func GenerateWorktreeVhostFor added in v1.20.0 

func GenerateWorktreeVhostFor(domain, path, phpVersion, parentDomain, siteName, branch string, secured bool) error

GenerateWorktreeVhostFor picks GenerateWorktreeSSLVhost or GenerateWorktreeVhost based on the secured flag, so callers (scanWorktrees, syncWorktree, migrateWorktreeVhosts) don't repeat the if/else around the two underlying generators. parentDomain is consulted only on the SSL path. siteName + branch are forwarded so the worktree's PHP requests get tagged with LERD_SITE / LERD_BRANCH for dump grouping.

func GetTemplate 

func GetTemplate(name string) ([]byte, error)

GetTemplate returns the content of a named nginx template/config file. name can be "nginx.conf", "vhost.conf.tmpl", or "vhost-ssl.conf.tmpl".

func LoadOrGenerateTrustToken added in v1.8.0 

func LoadOrGenerateTrustToken() (string, error)

LoadOrGenerateTrustToken returns the per-install nginx → lerd-ui trust token, generating a fresh 32-byte hex value on first call and persisting it to ~/.local/share/lerd/nginx-trust-token (mode 0600). Subsequent calls return the cached value so the file is read at most once per process.

Idempotent across processes: if two lerd processes race on first generation, the second one's write loses but both end up with a valid token because the read-after-write resolves the race.

func Reload 

func Reload() error

Reload signals nginx to reload its configuration.

func ReloadOrWarn added in v1.20.0 

func ReloadOrWarn(indent string)

ReloadOrWarn reloads nginx and, on failure, prints a single warning line to stdout. Pass indent="" for top-level output, or a leading-space prefix when the warning sits under an indented status line in CLI output.

func RemoveVhost 

func RemoveVhost(domain string) error

RemoveVhost deletes the vhost config files for the given domain.

func TrustTokenPath added in v1.8.0 

func TrustTokenPath() string

TrustTokenPath returns the absolute filesystem path of the trust token file.

Types

type VhostData 

type VhostData struct {
	Domain          string // primary domain (used for config file naming)
	ServerNames     string // space-separated list of all domains for server_name directive
	Path            string
	PHPVersion      string
	PHPVersionShort string
	CertDomain      string // domain whose cert files to use (defaults to Domain)
	PublicDir       string // document root subdirectory, e.g. "public", "web", "."
	Proxy           bool   // true when the site has a worker with WebSocket/HTTP proxy config
	ProxyPath       string // URL path for the proxy (e.g. "/app")
	ProxyPort       int    // port the worker listens on inside the PHP-FPM container
	CustomContainer string // container name for custom container sites (e.g. "lerd-custom-nestapp")
	CustomPort      int    // port the app listens on inside the custom container
	BackendSSL      bool   // proxy to the container via HTTPS (app serves TLS on its own port)
	// LerdSite / LerdBranch surface the parent site name and (for worktrees)
	// the branch to PHP via fastcgi_param so the dump bridge can tag events
	// with stable identifiers instead of guessing from DOCUMENT_ROOT.
	LerdSite   string
	LerdBranch string
	// Profiling arms the SPX profiler for the site: when true the .php
	// location injects SPX_ENABLED=1 into HTTP_COOKIE so every request is
	// profiled. SPX_KEY is injected regardless (gated by the $spx_key map)
	// so the profiler UI is reachable.
	Profiling bool
	// RequestTimeout is the nginx request timeout in seconds rendered into the
	// fastcgi_*_timeout / proxy_*_timeout directives. Resolved per site by
	// resolveRequestTimeout (project .lerd.yaml, then global config, then 60s).
	RequestTimeout int
}

VhostData is the data passed to vhost templates.

type VhostRepair added in v1.5.1 

type VhostRepair struct {
	Domain string
	Reason string // "missing-cert" or "orphan-ssl"
}

VhostRepair describes a single vhost that was repaired during pre-flight.

func RepairVhosts added in v1.5.1 

func RepairVhosts() []VhostRepair

RepairVhosts performs pre-flight validation of nginx vhost configs before start. It fixes SSL vhosts that reference cert files that don't exist on the host:

  • If the domain belongs to a registered site, the vhost is regenerated as plain HTTP and the site registry is updated (Secured = false).
  • If no matching site exists (orphan SSL vhost), the config is removed.

Plain HTTP vhosts are left untouched even if they don't match any site — they are harmless and may belong to worktrees, parked sites, or ignored sites.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.