If you follow a deployment guide step by step on a newer OS than the one it targets, it will break in places the author never saw. Those breaks are bugs in the guide, and they are worth logging as you go, because each one is a fix you can write down while the symptom is still in front of you. I did this setting up a Laravel app on a VPS.

The setup

The deployment guide targets Ubuntu 26.04. The VPS image came up as Ubuntu 26.10. I started at step 2 of the guide and did the work over SSH.

Each entry in the setup log got one of four labels:

  • DEVIATION: I did something other than the guide said.
  • EXTRA: a step the guide lacks.
  • GUIDE BUG: the guide is wrong as written.
  • TODO: needs me.

The labels matter. A deviation is a choice. A guide bug is a defect someone else may hit.

Bugs the newer OS caused

These came up on the 26.10 image.

The PHP repository does not exist. Step 2.1b builds the sury PHP repository line from lsb_release -sc. On 26.10 that gives a dist name the repository does not have. The repository path for it returns 404, and ppa:ondrej/php has no dist for it either. The step fails as written.

I ruled out one workaround. Sury's 26.04 dist does have PHP 8.4.27. But using it on 26.10 would mean running packages built for another release. I did not want that on a production box. I chose Ubuntu's own PHP 8.5 instead. I moved the CI and deploy workflows to PHP 8.5, and composer why-not php 8.5.9 reported no blockers.

The version check does not fit Ubuntu packages. The guide says "8.4.27 or newer". The Ubuntu package reads 8.5.9, which is below upstream's 8.5.12. The Ubuntu changelog shows the security patches backported, though. On Ubuntu packages, check the changelog, not the version string:

apt-get changelog php8.5-fpm | grep CVE-2026-10961

There is no php8.5-opcache package. The guide's install line names php8.4-opcache, which would fail on 8.5. OPcache is built into PHP 8.5, and php -m lists Zend OPcache.

MariaDB moved its config. The 26.10 MariaDB 11.8.9 package keeps its config in /etc/mariadb/. /etc/mysql does not exist, so the guide's tee /etc/mysql/mariadb.conf.d/99-porch.cnf failed. The same settings went into /etc/mariadb/mariadb.conf.d/.

nginx ships a different server_tokens. The 26.10 nginx.conf ships server_tokens build;, which reveals more than the default. The guide's extra conf.d/hardening.conf then fails nginx -t with "server_tokens" directive is duplicate. I deleted that file and changed the line in nginx.conf to server_tokens off;. The Server header is now just nginx. The cost: nginx.conf is a package conffile, so a later nginx upgrade may ask about it, and unattended-upgrades may hold nginx back.

The OS has a short life. 26.10 is an interim release, supported for about 9 months, to around July 2027. I plan to move to 27.04 or rebuild on 26.04 LTS before then.

Bugs the newer OS did not cause

These are not tied to the release number. I did not test them on the guide's own target, so I cannot say whether they hit there.

SSH password login stayed on. After step 1.6, sshd -T still showed passwordauthentication yes. The cloud image ships /etc/ssh/sshd_config.d/50-cloud-init.conf with PasswordAuthentication yes. sshd uses the first value it reads, and 50- sorts before the guide's 99-hardening.conf. Renaming the guide's file to 01-hardening.conf fixed it. A refused root login had hidden the problem, because PermitRootLogin no was also set. Verify with:

sudo sshd -T | grep -i passwordauth

Step 1 drifted in three places. vm.swappiness was 60 (guide: 10). Release folders were 775 (guide: 755, 755 and 750). The deploy key lacked the restrict prefix. I fixed all three by hand.

DOCUMENT_ROOT was the symlink path. Ubuntu's fastcgi_params sets DOCUMENT_ROOT $document_root. The guide includes it after its own fastcgi_param DOCUMENT_ROOT $realpath_root, and PHP-FPM keeps the last value. So $_SERVER['DOCUMENT_ROOT'] would be the current symlink path. This is an ordering bug. Putting include fastcgi_params; first fixes it.

A 403 has a meaning the guide leaves out. Section 4.3 says to expect a 404 through Cloudflare before the first deploy. It does not say that a 403 there means Authenticated Origin Pulls is off. The temporary debug log showed verify=NONE. After I switched it on, the next request logged verify=SUCCESS and the site returned 404.

The TLS floor was never set. Minimum TLS version was not set on the Cloudflare edge, which still completed TLS 1.0 and 1.1 handshakes. Once set to 1.2, those get alert protocol version. To test old protocols locally, modern OpenSSL needs -cipher 'DEFAULT@SECLEVEL=0'.

ssh-keyscan -H prints too much. The guide says to paste its output for step 6.1. It prints comment lines on stderr plus RSA, ECDSA and ED25519 keys, five lines in all, and the guide only verifies the ed25519 one. Store a single line:

ssh-keyscan -H -t ed25519 <host> 2>/dev/null

Passport keys are missing, and nothing says so. The app's MCP and OAuth endpoints returned 500 (LogicException: Invalid key supplied) until php artisan passport:keys had run. Nothing in the deploy warns about it. The site and /up stay green without the keys, so the health check cannot catch it. After the keys existed, the endpoint returned 401 without a token. Section 6.3 should say so, and the go-live checklist should include "POST without a token returns 401".

A log glob fails under sudo. sudo grep ... storage/logs/*.log fails, because the glob expands as the unprivileged user, who cannot enter the 750 shared/ directory. Use sudo sh -c '...' so the glob expands as root.

A bug in the guide's assumptions

The guide assumes GitHub Required reviewers on the production environment. My repository is private on GitHub Free, and the environment page has no deployment protection rules, so I could not set them. The guide leans on them in 6.1, in its security model paragraph, in section 8 ("deploy waits for your approval") and in a 7.7 checklist item.

The first deploy ran without approval. I chose to keep auto-deploy on every merge to the main branch, with CI required to pass first. The consequence is plain: merging any PR, including a Dependabot major-version bump, deploys to production.

What held up

Two tests passed.

Rollback. The rollback script switched the live release back and forward again, with exit code 0 both times. During each switch, 30 requests to /up returned 200 every time. No downtime.

Restore. I loaded the nightly dump into a scratch database. It held 27 tables and 1 user, the same as live. Then I dropped the scratch database.

How to log guide bugs

Keep a labelled log from the first command. The four labels in the setup section are enough. At the end, the guide-update list held seven numbered problems plus the keyscan note.

Verify with the real command, not by reading the file you just wrote. The SSH bug is the example. The config looked right, and only sshd -T showed the effective value.

Write the fix next to the bug while the symptom is fresh. "Rename to 01-hardening.conf" is an edit someone can apply. "SSH was weird" is not.