Skip to content

Source: docs/releases/README.md. Edit it there; this page is generated at build time.

Release runbook ​

What a person has to do by hand around a release. The Deploy workflow does everything else: it gates the tag, dumps the database, migrates, flips the symlink, restarts the worker and curls /up (ADR 0010). This file covers what it can't do: root commands on the box, settings, and checks only a person can make.

Read Next release before every tag. Anything listed there has to be done, at the point it says, or the release goes out broken.

How a release flows ​

Work collects on release/v1, and main only ever holds what has been released or is about to be.

  1. Feature PRs target release/v1, and are squash-merged into it. CI runs on them the same as on PRs to main.
  2. A PR that needs a manual step adds it to Next release in the same PR. That means a root command on the box, a setting in the admin or an external dashboard, or a check to run after the deploy. The PR template asks for this. If a step isn't written here, the person tagging won't know about it.
  3. To release, open a PR from release/v1 into main. Rename the Next release heading below to the tag you're about to push and today's date, and start a fresh, empty Next release above it. That way main records what each tag needed.
  4. Do the "before the tag" steps.
  5. Merge the release PR with a merge commit, not a squash:gh pr merge <n> --merge. A squash gives main a commit that release/v1 doesn't have, and the next release PR would show this release's changes all over again.
  6. Tag the merge commit on main, as the README describes (browser or git tag). A tag on release/v1 itself is refused, because the deploy gate only accepts a commit that is on main. The gate also waits for main's CI run on that commit, so tagging straight after the merge is fine.
  7. Do the "after the deploy" steps, and the standing checks.

Rolling back is still Actions → Deploy → Run workflow at a tag, with rollback ticked. Rolling back restores code, never schema, and never anything done by hand. If a release below has a manual step, its entry says whether that step is safe under the previous release.

Every release ​

These apply to every tag, on top of anything in Next release.

After the deploy:

  • Actions → Deploy shows the run green. Its last step already curls /up.
  • curl -sI https://thegoodbuyer.com/ | head -1 gives a 200.
  • Cloudflare caches .txt files (robots.txt) for up to 4 hours, so a change to one shows on the box before it shows on the site. Compare curl -s -H "Host: thegoodbuyer.com" http://127.0.0.1/robots.txt on the box with the public URL. To see it straight away, purge that URL in Cloudflare (Caching → Configuration → Custom Purge). The sitemap and feed aren't cached.
  • Open a review page and /admin/login in a browser. /up only proves Laravel boots, not that a page renders (#63).

Next release ​

Nothing yet. Add the manual steps a PR needs here, in that PR.

Released ​

v1.4.1 (2026-10-02) ​

Domain cutover to thegoodbuyer.com ​

APP_URL now points at https://thegoodbuyer.com instead of the staging subdomain, and the nginx vhost's server_name moved with it. The nginx side was already installed by hand on the box on 2026-10-02 (ahead of this release, to fix routing immediately) — if redone on another box, or if the install step is ever missed, re-run it:

sh
install -m 644 deploy/nginx/blog-filament.conf /etc/nginx/sites-available/blog-filament
nginx -t && systemctl reload nginx

After the deploy, confirm generated URLs (product images, sitemap, robots.txt) resolve under thegoodbuyer.com, not the old subdomain — artisan:optimize rebuilding the config cache is what actually flips them, so they won't move until this tag deploys. Safe under the previous release: rolling back just points URLs at the old domain again, nothing is lost.

v1.4.0 (2026-09-24) ​

Tagged from main on 2026-09-24. PRs #89, #90 and #91.

From #86. The header and footer now show social icons, but only for links saved in Site → Settings → Social links, and production has none yet. Add one row per account (label = the network's name, URL = the profile), save, and check the icons appear in the header and in the footer's Follow row.

The footer's Quick links column comes from the footer menu. Production's is empty, so the column shows the section links (All reviews, Best picks…) until someone adds items under Site → Menus. That is safe to leave. Production's header menu was also empty on 2026-09-23, so the live site has no primary navigation at all until it gets items.

Safe under the previous release: rolling back loses the icons, and the social links go back to being listed as text in the footer. Nothing saved in the admin is lost.

After the deploy: give editors the comment permissions, and post a test comment ​

From #88. Every published article (guides and blog posts) now has a comment form. Comments wait in Content → Comments until someone approves them. Each new one is emailed through the queue to the contact notify address, so it needs the worker running.

  1. Anyone other than super_admin who should moderate comments needs the Comment permissions on their role (Roles → Resources → Comment: at least View Any, View, Update and Delete). The deploy seeds them for super_admin only.
  2. Post a comment on any article in a private window. Check the page says it is awaiting approval and does not show it, that it appears in Content → Comments, and that the email arrives at the address in Site → Settings → Send contact form messages to.
  3. Approve it and check it shows on the article with Comments (1). Then delete it.

After the deploy: add comments to the Privacy Policy page (in the admin) ​

The Privacy Policy is a Page, edited in Site → Pages, not in code. Add a paragraph like this, and have whoever owns the policy check the wording:

Comments. When you comment on an article, we collect your name, email address and comment, and a one-way scrambled code made from your IP address. We use your name and comment to show it on the site once approved; your email address is never shown, and we use it only to contact you about your comment. We use the scrambled code only to spot spam, and never store the IP address itself. Approved comments are kept while they are published; comments we reject are deleted 30 days after we reject them. To have a comment removed, use the contact form.

Safe under the previous release: it never reads the new comments table. After a rollback, the form disappears from articles and comments stay in the table until the next release.

v1.3.1 (2026-09-23) ​

Tagged from main on 2026-09-23. PR #84.

Fixes v1.3.0, which answered 500 on every public page, robots.txt and the feed: site settings were cached as a model the cache would not unserialize. No manual steps. After the deploy, run the checks under Every release, then the v1.3.0 steps below, which could not be done while the site was down.

v1.3.0 (2026-09-23) ​

Tagged from main on 2026-09-23. PRs #78, #79, #80, #81 and #82.

After the deploy: check the site settings (in the admin) ​

From #51. The brand, footer and SEO defaults moved from code into Site → Settings. Nothing is saved there on deploy, so the site keeps showing what the code used to: APP_NAME as the site name and the old footer sentence. The one visible change is that the footer's "Demo content for development only." line is gone.

  1. Open / and check the footer ends © <year> <site name>. with no "Demo content" line.
  2. Open Site → Settings as super_admin, check the values and press Save settings once, so the row exists and later edits have something to change.
  3. Anyone other than super_admin who should edit settings needs View:ManageSiteSettings ticked on their role, under Roles → Pages. The deploy seeds it for super_admin only.

Safe under the previous release: it never reads the new site_settings table.

After the deploy: send a test message through the contact form ​

From #54. /contact now shows a form. Messages land in Site → Inbox and are emailed through the queue, so they need the worker running.

  1. In Site → Settings, fill in Send contact form messages to (or Contact email). With both empty, messages still reach the Inbox but nobody is emailed.
  2. Send a message from /contact in a private window. Check it shows in Site → Inbox and that the email arrives, with Reply-To set to the address you typed.
  3. Mark it handled, or delete it.
  4. Anyone other than super_admin who should read the inbox needs the Contact Message permissions on their role (Roles → Resources). The deploy seeds them for super_admin only.

Safe under the previous release: it never reads contact_messages or the new settings column. After a rollback, /contact goes back to being a plain Page.

v1.2.0 (2026-09-23) ​

Tagged from main on 2026-09-23. PRs #67, #68, #69, #71, #72, #73, #74, #75 and #76.

Before the tag: install the new nginx vhost (on the box, as root) ​

From #68. robots.txt is now a Laravel route instead of a file in public/. The vhost's location = /robots.txt block used to serve files only, so without the new try_files line nginx returns the right text under an HTTP 404. Crawlers treat a 404 robots.txt as "allow everything", which drops the /go/ rule without any visible error.

The vhost is installed by hand and never by the deploy (deploy/README.md), so do this before tagging. It's safe under the release that's live now: with the old release, the new block still serves the old static file.

From your machine, on the release/v1 checkout:

sh
scp -P 5497 deploy/nginx/blog-filament.conf deploy@119.18.36.16:/tmp/blog-filament.conf

On the box, as root:

sh
install -m 644 /tmp/blog-filament.conf /etc/nginx/sites-available/blog-filament
nginx -t && systemctl reload nginx
rm /tmp/blog-filament.conf

Check it's still serving the current release's file, before you tag:

sh
curl -sI https://filament.stackbridge.com.au/robots.txt | head -1   # 200

After the deploy ​

  • robots.txt comes from the app (#46):

    sh
    curl -sI https://filament.stackbridge.com.au/robots.txt | head -1   # 200, not 404
    curl -s  https://filament.stackbridge.com.au/robots.txt
    # Sitemap: https://filament.stackbridge.com.au/sitemap.xml

    A 404 means the vhost step above was skipped: do it now, and no redeploy is needed. On the day: the box answered correctly straight after the deploy, but Cloudflare kept serving the old file (cf-cache-status: HIT, max-age=14400) until it was purged. When both lines are right, close #46.

  • The verdict box discloses (#67). If a review is published, open it. "Paid link — we may earn a commission…" should sit directly above the buy button in the box at the top. Nothing to do on the server.

  • Admin dates are in Sydney time (#70). Every datetime in the admin, form fields and table columns alike, now shows Sydney time. The database still stores UTC. Nothing to set: ADMIN_TIMEZONE defaults to Australia/Sydney and only needs adding to the env if editors move. Tell the editors once, since dates they've seen before will look shifted by 10 or 11 hours.

  • Find content that says Published but isn't live. Rows saved before this release can still have a blank or future date. On the box, as deploy, from /var/www/blog-filament/current:

    sh
    php artisan tinker --execute='foreach ([App\Models\Review::class, App\Models\Comparison::class, App\Models\Listicle::class, App\Models\Article::class] as $m) foreach ($m::where("status", "published")->where(fn ($q) => $q->whereNull("published_at")->orWhere("published_at", ">", now()))->get() as $r) echo class_basename($m), " #", $r->id, " ", $r->title, "\n";'

    Nothing printed means nothing to fix. For each row it prints, open it in the admin and save it: a blank date becomes now, and a future date is refused with a pointer to Scheduled.

  • Give editors access to Redirects, if they should have it (#45). The deploy's shield:seed gives the new Redirect permissions to super_admin only. Any other role sees no Site → Redirects until someone ticks them under Administration → Roles → (role) → Redirect. Slug-change redirects are written either way, whoever edits the slug.

If this release is rolled back, the vhost can stay as it is. The previous release still has public/robots.txt, and the new block serves it.

Before v1.2.0 ​

Tags up to v1.1.1 predate this file. Their one-time steps, such as setting up the box, the runner, lingering for the worker and the first admin user, are in deploy/README.md and the README.