I asked Claude for specific recommendations for updating Ghost instead of applying the band-aid. Here’s Claude’s suggestion:
nginx fails to start on an unresolvable ap.ghost.org upstream → ghost doctor reports it as “Missing package(s): nginx”
Environment
- Ghost 6.44.1 · Ghost-CLI 1.29.3 · Node v22.22.3 · MySQL
- Ubuntu 24.04.4 LTS · self-hosted,
production · installed via Ghost-CLI
Summary
After an unattended nginx security upgrade restarted the service, nginx failed to start because it couldn’t resolve the ap.ghost.org ActivityPub upstream at that moment. Since nginx resolves literal proxy_pass hostnames once at startup and aborts if the lookup fails, the entire site went down — not just the Fediverse path. ghost doctor then reported this as Missing package(s): nginx, even though the nginx package was installed the whole time. The message points toward reinstalling nginx, when the actual fix was a single systemctl start nginx once DNS recovered.
Reproduction
- Standard Ghost-CLI
production install. Ghost-CLI writes an ap.ghost.org upstream into <site>-ssl.conf (added in Ghost-CLI #1963).
- Restart nginx while
ap.ghost.org is momentarily unresolvable — e.g. the auto-triggered restart of an unattended-upgrades nginx update landing on a brief DNS gap (more likely on home/rural connections).
- nginx aborts startup; the site is fully down.
ghost doctor → Checking system compatibility … Missing package(s): nginx, despite dpkg -l nginx showing ii.
Evidence
Package is present and the binary works:
$ dpkg -l nginx | grep nginx
ii nginx 1.24.0-2ubuntu7.11 amd64 ...
$ nginx -v
nginx version: nginx/1.24.0 (Ubuntu)
Service is failed — note the config test (ExecStartPre → nginx -t) passes; only the real start fails:
ExecStartPre=/usr/sbin/nginx -t ... (code=exited, status=0/SUCCESS)
ExecStart=/usr/sbin/nginx ... (code=exited, status=1/FAILURE)
Active: failed (Result: exit-code)
The actual cause, from journalctl -u nginx:
[emerg] host not found in upstream "ap.ghost.org" in /etc/nginx/sites-enabled/<site>-ssl.conf:24
The split is the tell: nginx -t validates config and loads certs but does not resolve proxy_pass upstreams, so only the real start hits the DNS failure.
Root cause
- Config — a literal upstream hostname makes a momentary DNS failure fatal to the whole web server, and ties a self-hosted install’s availability to a Ghost-operated hostname being resolvable at the exact moment nginx restarts.
- Diagnostics —
ghost doctor collapses “package not installed”, “installed but not running”, and “installed but failed to start” into one misleading Missing package(s) message, and hides the journal line that actually explains the failure.
Recommendations (prioritized)
Ghost-CLI config generation
- Generate the ActivityPub upstream for request-time resolution — a
resolver directive plus a variable in proxy_pass (set $ap ``ap.ghost.org``; proxy_pass ``https://$ap``;) instead of the literal hostname. Highest-impact change: a DNS blip then degrades only the ActivityPub path (502 on those requests) instead of preventing nginx from starting. Converts a site outage into a contained feature degradation.
- Gate the upstream on the ActivityPub feature being enabled (or otherwise fail soft), so installs not using the Fediverse don’t carry a hard startup dependency for zero benefit.
ghost doctor
- Separate the checks — package presence (
dpkg/binary) vs service active (systemctl is-active) vs failed-to-start — and report the true state instead of Missing package(s).
- Surface the underlying error — echo the last
journalctl -u nginx line so the real cause (host not found in upstream …) is visible immediately.
- Add a targeted hint for the known
host not found in upstream "ap.ghost.org" signature: suggest checking DNS / restarting nginx before any reinstall.
- Re-word the message/severity so “installed but failed to start” isn’t presented as a missing package — that framing is what pushes users toward reinstalling nginx (which risks clobbering the generated vhost config).
Underlying principle
Self-hosted installs shouldn’t fail hard on resolution of a Ghost-operated hostname. External dependencies added to generated configs should fail soft — degrade the dependent feature rather than block the whole server.
Local workaround for others hitting this
First, just restart — the site is usually one command from recovery:
sudo systemctl start nginx
To auto-recover from future transient blips, add a systemd drop-in (sudo systemctl edit nginx):
[Service]
Restart=on-failure
RestartSec=15
Caveats worth knowing: this is a coarser mitigation than the config fix above — it shortens but doesn’t eliminate downtime during a blip (nginx-won’t-start is all-or-nothing), and it can make a genuine persistent failure quieter by looping instead of resting in failed, so monitor the live site rather than just systemctl is-active. The 15-second spacing is deliberate: it sits above systemd’s default limit of 5 starts per 10 seconds, so the retry loop won’t trip the rate limiter and park in a failed state.
Happy to open a PR for the request-time-resolution config change and/or the ghost doctor reporting split if a maintainer can point me at the right spots.