blog.thms.uk

Reducing Docker deploy downtime for Laravel and FrankenPHP

Sat, 15 Aug 2026 06:15:00 +0000

Reducing Docker deploy downtime for Laravel and FrankenPHP

A little while ago I wrote about the multi-stage Dockerfile I put together for Laravel and FrankenPHP. It worked, the site went live, and I was quietly pleased with myself.

Then I started deploying to it a few times, and noticed something I hadn’t realised when I wrote it: every deploy took the site down for an uncomfortably long time. Not catastrophic - it’s a small site on my homelab, not a bank - but long enough to annoy me.

So this is the follow-up: what was actually taking so long, and what I did to speed it up.

What was actually happening

The first thing worth doing was to stop guessing and think properly about the actual sequence of what happens when I run docker compose up -d after pulling a new image, given my docker-compose.yml:

All running containers stop. The site is now down.
The init container is created, boots Laravel, runs php artisan migrate --force, and exits.
The app container is created. Its entrypoint runs a recursive chown over the bind mounts, then php artisan optimize.
FrankenPHP finally starts and binds :80. The site is back.

Everything between steps 1 and 4 is downtime, and it’s all strictly serial.

And there is a further wrinkle: my init, app, queue and scheduler services all run the same image, which means they all run the same entrypoint, which means all four of them were also running that recursive chown over the same two bind mounts at the same time! Four containers, two mounts, all fighting over the same disk. Ouch!

Fix 1: Bake everything that doesn’t depend on the environment into the image

The first thing to realise is that optimize is doing two quite different kinds of work:

Compiled Blade views and the event-to-listener map are derived purely from the source tree. They cannot change between building the image and running it. Config and route caching, on the other hand, read my .env, so they genuinely have to happen at runtime, on the machine, with the real environment present.

Which means half of optimize had no business being in the entrypoint at all. It belongs in the image, where it’s done once at build time and doesn’t hold up boot at all:

RUN php artisan view:cache --no-interaction \
 && php artisan event:cache --no-interaction

And in the entrypoint, php artisan optimize becomes just the two that need the environment:

php artisan config:cache && php artisan route:cache

Config first, incidentally, because route definitions can read config values.

The gotcha that caught me out the first time

Compiled Blade views normally live in storage/framework/views. But storage/ is a bind mount, because it’s where the logs and file storage need to persist. So anything I bake into /app/storage/framework/views at build time gets yanked out from under my feet by the host directory the moment the container starts. Yes, the cache is there in the image, but invisible at runtime, and everything is uncached. Second ouch!

The fix is to put the compiled views somewhere that isn’t a mount:

ENV VIEW_COMPILED_PATH=/app/bootstrap/cache/views

RUN mkdir -p "$VIEW_COMPILED_PATH" \
 && php artisan view:cache --no-interaction \
 && php artisan event:cache --no-interaction

VIEW_COMPILED_PATH might be a bit obscure, but it’s an env var built into Laravel to configure exactly where the compiled views are stored.

One thing to watch: this ENV line has to come before the chown in the Dockerfile, so the compiled views end up owned by www-data along with the rest of bootstrap/cache.

Fix 2: Do the volume setup once, not four times

This is the concurrent-chown problem from earlier.

The entrypoint scaffolds Laravel’s storage directories, touches the SQLite file, and chowns it all to www-data. That work does need doing - on a fresh host those bind mounts start empty and owned by root - but it needs doing once, not simultaneously in every container.

So, it needs to go into the init server, together with the migration and caching: do it once before any of the other services start. I put the whole block behind an environment variable:

if [ "${BOOTSTRAP_VOLUMES:-0}" = "1" ]; then
  mkdir -p \
    storage/framework/cache/data \
    storage/framework/sessions \
    storage/framework/views \
    storage/logs \
    storage/app/public

  mkdir -p "$(dirname "$DB_FILE")"
  touch "$DB_FILE"

  chown -R "$APP_USER" storage "$(dirname "$DB_FILE")" 2>/dev/null || true
  chmod -R ug+rwX storage "$(dirname "$DB_FILE")" 2>/dev/null || true
fi

and set BOOTSTRAP_VOLUMES: "1" on the init service only:

# ...
  init:
    <<: *app-common
    command: php artisan migrate --force
    environment:
      BOOTSTRAP_VOLUMES: "1"
# ...

Fix 3: Deploying in stages

The changes above shorten the work, but the sequence is still fundamentally “stop the old container, do some stuff, start the new one”. The other half of the problem is that docker compose up -d recreates everything at once, so the web container’s downtime includes waiting for containers that have nothing to do with serving requests.

Splitting the deploy into three commands fixes that:

docker compose pull
docker compose up -d app
docker compose up -d --no-deps queue scheduler

You might wonder why no docker compose up -d init: Because the app service depends_on: init, the init service will run and complete before the app service is recreated.

The --no-deps on the last line ensures that we are not running the init container for a second time, when we recreate the queue and scheduler containers.

The trade-off

Keeping the site up during migrations means the old code is now serving requests (and processing the queue and scheduled tasks) against the new schema. For additive migrations that’s fine. For anything destructive (dropping a column, renaming one, tightening a constraint) the old container will throw errors for the short period between init finishing and the swap.

But then this is just what modern development looks like to me: I’ve done zero-downtime deployments for years, so I’m used to planning deployment in such a way that my old code can run with new schema. When I do need to do destructive migrations I’ll have to phase them over two deployments. That is just business as usual.

Alternatively, you can always stop the cron and scheduler services before you run docker compose up -d app, to stop these running during that restart window.

Takeaway

With Docker, as with bare code deployments, it pays to think about the sequence of deployment steps. That sequence is a bit more obvious when you’re deploying the code itself rather than building an image, pulling it, and restarting containers. But fundamentally the same things matter.

Comments

Join the conversation on the Fediverse.

When restart: always isn't enough: making Compose stacks recover at boot

Mon, 10 Aug 2026 06:15:00 +0000

When restart: always isn’t enough: making Compose stacks recover at boot

My Mastodon instance runs on Docker Compose, in an LXC container on a Proxmox host at home. The host reboots most weeks to pick up kernel updates, and that has never been a problem: every service in my compose files has restart: always or restart: unless-stopped, so everything comes back on its own.

Until one morning, when it didn’t.

My monitoring did its job and alerted me. However, the reboot is scheduled in the small hours, so I was fast asleep, and the instance was down for four hours before I got round to looking at it.

When I did look, docker ps was empty. Not a list of crashed containers - nothing running at all.

The first thing I did was bring everything back up by hand:

docker compose up -d

That worked, first time, in every project directory. Which was actually kinda annoying, because it meant whatever had gone wrong had already gone away, and I now had to find it after the fact.

The problem

The compose files were fine - I checked the restart policies first, and every service had one. So if the containers weren’t running, the daemon was the place to look:

sudo journalctl -u docker.service -b

And there it was:

level=error msg="Failed to load default apparmor profile" error="AppArmor enabled on
system but the docker-default profile could not be loaded: running
'/usr/sbin/apparmor_parser -Kr' failed with output: apparmor_parser: Unable to
replace "docker-default". apparmor_parser: Access denied. You need policy admin
privileges to manage profiles. error: exit status 243"

Followed by thirteen of these, one per container:

level=error msg="failed to start container" container=518ed98356409f...
error="AppArmor enabled on system but the docker-default profile could not be
loaded: ... error: exit status 243"

And then, immediately after:

level=info msg="Loading containers: done."
level=info msg="Daemon has completed initialization"

So Docker couldn’t load its default AppArmor profile, every container refused to start as a result, and the daemon then declared itself fully up and left me hanging.

Worth knowing: restart: always does not help here. The restart policy governs what happens when a running container exits. When the daemon restores containers at startup it makes exactly one attempt each, and if that attempt fails, the policy never comes into play. Nothing retries. The daemon reports itself healthy with zero containers running, and sits there indefinitely.

Chasing the cause

I spent a while trying to work out why the profile load was denied, and I should say up front that I haven’t yet got to the bottom of it. Here’s what I ruled out, in case it saves someone else the time.

It wasn’t specific to Docker. Two seconds before dockerd tried, rsyslogd had failed the same way:

reload-apparmor-profile[136]: apparmor_parser: Unable to replace "rsyslogd".
apparmor_parser: Access denied. You need policy admin privileges to manage profiles.

So nothing inside the LXC container could load AppArmor policy at that moment.

My first theory was a startup race on the Proxmox host: the container starting before the host had finished setting up AppArmor. That turned out to be wrong. The host’s apparmor.service finished at 02:01:16 and the container started at 02:01:28, a full twelve seconds later.

Nesting is enabled on the container, so that wasn’t it either.

And it doesn’t reproduce. I ran pct reboot on the container against the already-running host, and all thirteen came back perfectly. It’s also intermittent across host reboots - the host reboots most weeks, and every previous one has been fine.

So: something denied AppArmor policy loading inside the container for a window after the host booted, then quietly stopped denying it. I don’t know what, and I can’t trigger it on demand.

One dead end worth flagging

While testing this I reached for an obvious-looking check - try loading an existing profile and see if it works:

sudo apparmor_parser -Kr /etc/apparmor.d/usr.sbin.rsyslogd

This fails with “Access denied” every single time, whether or not Docker is healthy. It looks exactly like a reproduction, and it isn’t one. That profile is loaded by the Proxmox host, and a nested container can’t replace a profile owned by the parent namespace. It’s a different permission failing for a different reason.

There’s also no /etc/apparmor.d/docker to test with, because dockerd doesn’t read its profile from a file - it generates docker-default at runtime and pipes it to apparmor_parser. So if you want to test the permission Docker actually needs, load a throwaway profile of your own:

printf 'profile probe {\n file,\n}\n' | sudo apparmor_parser -a -; echo "rc=$?"
printf 'profile probe {\n file,\n}\n' | sudo apparmor_parser -R -

The solution

Since I couldn’t find the trigger, and it clears itself, I stopped trying to prevent it and made the recovery automatic instead.

What’s needed is something that runs after Docker at boot, brings every stack up, and - crucially - keeps trying if it doesn’t work the first time. That last part is the whole point. A one-shot docker compose up -d at boot would have failed on that particular morning exactly like the daemon did.

So I wrote compose-autostart.sh: it finds every compose project in the BASE_DIR directory, brings each one up, drops the ones that succeeded, and retries the rest every 30 seconds for up to an hour. On a normal boot it does one round and exits.

Two things I should highlight here.

This script only runs at boot, not on a timer. My backup script deliberately stops each stack while it snapshots it, and a reconciler running on a schedule would happily start them again mid-backup. For the same reason, the script skips any round where the backup is holding its lock.

And it will bring up any containers that I may have stopped on purpose, since it doesn’t know what was and wasn’t running by the time the host rebooted.

Making the solution permanent

The unit itself is unremarkable:

[Unit]
Description=Bring all Docker Compose stacks up at boot, retrying until they start
Requires=docker.service
After=docker.service network-online.target
Wants=network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/path/to/compose-autostart.sh
TimeoutStartSec=infinity

One systemd wrinkle: you can’t use Restart= with Type=oneshot, so the retry loop has to live in the script rather than in the unit. TimeoutStartSec=infinity is there because the script owns its own deadline.

Enable the service with

sudo systemctl daemon-reload
sudo systemctl enable compose-autostart.service

Wrapping up

I haven’t yet found out what denied AppArmor policy loading that morning. I’d love to know if you have any theories.

The more important part for now is that - hopefully - a failure like this should in future clear itself: retrying in a loop turns a middle-of-the-night outage into something that’s already fixed by the time I wake up.

Comments

Join the conversation on the Fediverse.

Exempting an IP from Mastodon's rate limits

Thu, 06 Aug 2026 06:15:00 +0000

Exempting an IP from Mastodon’s rate limits

I have always wanted to exempt my FediFetcher install from Mastodon’s rate limits: rate limits are of course really crucial to the security of a (web) application, but when I run my own FediFetcher against my own instance, the frequent resolving of remote posts triggers the rate limits a lot and really slows it down.

Unfortunately, Mastodon has no configuration option to do this, but it uses the Rack::Attack gem, and that can be configured by simply adding another file to the file system. So let’s get to work.

The commands below assume a traditional systemd install. The initialisers themselves are identical on Docker Compose, but you’ll need to get the files into the container and restart it differently: I’ve implemented the same thing (plus pinning an IP address for my FediFetcher container) in my mastodon-compose project.

Confirming the IP address Rack::Attack actually sees

Since this is security critical, I really wanted to make sure I’d got the IP addresses configured correctly, rather than relying on assumptions. So the first thing to do is log the IP addresses Rack::Attack sees. Create a file at config/initializers/zz_rack_attack_safelist.rb. (The zz_ prefix ensures it loads after Mastodon’s own rack_attack.rb, since Rails loads initializers in alphabetical order.) Give it the following content:

# frozen_string_literal: true
#
# Logs whenever a throttle or blocklist matches, so you can see which rule fired
# and for which IP.
ActiveSupport::Notifications.subscribe(/rack_attack/) do |_name, _start, _finish, _id, payload|
  req = payload[:request]
  next if req.nil?

  Rails.logger.warn(
    "[rack_attack] type=#{req.env['rack.attack.match_type']} " \
    "rule=#{req.env['rack.attack.matched']} " \
    "remote_ip=#{req.remote_ip} raw_ip=#{req.ip} " \
    "xff=#{req.get_header('HTTP_X_FORWARDED_FOR').inspect} path=#{req.path}"
  )
end

# Logs the IP for every API request without ever safelisting anything
# (the block always returns false). Run FediFetcher and read remote_ip out of 
# the logs
Rack::Attack.safelist('probe (never matches)') do |req|
if req.path.start_with?('/api/')
  Rails.logger.warn(
    "[rack_attack probe] remote_ip=#{req.remote_ip} raw_ip=#{req.ip} " \
    "xff=#{req.get_header('HTTP_X_FORWARDED_FOR').inspect} " \
    "ua=#{req.get_header('HTTP_USER_AGENT').inspect} path=#{req.path}"
  )
end

false
end

Now, restart Mastodon:

sudo systemctl restart mastodon-web

Read the logs while FediFetcher is running:

journalctl -u mastodon-web -f | grep 'rack_attack probe'

You should find lines that look a bit like this:

[rack_attack probe] remote_ip=172.20.0.2 raw_ip=172.19.0.1 xff="172.20.0.2" ua="FediFetcher/8.0.0; +mstdn.thms.uk (https://go.thms.uk/ff)" path=/api/v2/search

The value you want is remote_ip, not raw_ip: that’s the address Rails derives after stripping trusted proxies, and it’s what the safelist below compares against.

It’s important to sanity check that this isn’t your reverse proxy’s IP. Stop here and fix your reverse proxy if it is!

Safelist the IP

Edit config/initializers/zz_rack_attack_safelist.rb and replace the whole contents with:

# frozen_string_literal: true
#
# safelist by IP as specified in env
RACK_ATTACK_SAFELIST_IPS = ENV.fetch('RACK_ATTACK_SAFELIST_IPS', '')
                              .split(',')
                              .map(&:strip)
                              .reject(&:empty?)
                              .filter_map do |cidr|
                                begin
                                  IPAddr.new(cidr)
                                rescue IPAddr::Error => e
                                  Rails.logger.error("[rack_attack] ignoring invalid RACK_ATTACK_SAFELIST_IPS entry #{cidr.inspect}: #{e.message}")
                                  nil
                                end
                              end

unless RACK_ATTACK_SAFELIST_IPS.empty?
  Rails.logger.info("[rack_attack] safelisting #{RACK_ATTACK_SAFELIST_IPS.map(&:to_s).join(', ')}")

  Rack::Attack.safelist('allow from safelisted clients') do |req|
    begin
      ip = IPAddr.new(req.remote_ip)
      RACK_ATTACK_SAFELIST_IPS.any? { |net| net.include?(ip) }
    rescue IPAddr::Error
      false
    end
  end
end

A safelist match short-circuits everything else, so a matching request skips all of Mastodon’s throttles and blocklists.

Then add the following to your .env.production file:

# Replace with whatever IP address you found above. Separate multiple IPs with
# commas. CIDR ranges are also supported.
RACK_ATTACK_SAFELIST_IPS=172.20.0.2

Restart Mastodon again and read the logs during boot:

sudo systemctl restart mastodon-web && journalctl -u mastodon-web -f | grep 'rack_attack'

You should find a line saying

[rack_attack] safelisting 172.20.0.2

Security

You are now giving one IP (or several) totally unfettered access to your Mastodon instance, so you really want to make sure your reverse proxy has its trusted proxy addresses locked down properly. If it doesn’t, remote_ip is derived from an X-Forwarded-For header anyone can set, and your safelist becomes trivially spoofable. But that’s beyond the scope of this post.

Comments

Join the conversation on the Fediverse.

Setting up OIDC for Mastodon with Pocket ID

Sun, 19 Jul 2026 06:15:00 +0000

Setting up OIDC for Mastodon with Pocket ID

Today I wanted to experiment with setting up OIDC (specifically Pocket ID) for my Mastodon instance. Annoyingly, there is very little documentation about this, but here is what I gathered.

OIDC provider setup

Now, this setup will vary slightly depending on the OIDC provider you are using. I’m writing up the Pocket ID steps here, but they should transfer to other providers.

The main thing you need to provide is the callback URL, which is https://example.com/auth/auth/openid_connect/callback, where example.com is your Mastodon domain. (Yes, double auth. No, I don’t know why 🤷‍♂️)

You should also enable PKCE.

You’ll then be given a Client ID and Client Secret. Keep a note of these.

Mastodon setup

The minimal setup requires adding the following to your .env.production file. The comments explain each option.

OIDC_ENABLED=true # The main switch to turn it on
OIDC_DISCOVERY=true # Required if you don't want to manually provide all the OIDC endpoints. Depends on your provider exposing these through the `/.well-known/openid-configuration` endpoint (which Pocket ID does)
OIDC_USE_PKCE=true # If you turned on PKCE when registering Mastodon with your OIDC provider. Turn on both or neither, but never one or the other
OIDC_DISPLAY_NAME="<Your Provider Name>" # Used on the "Log in with <Provider Name>" button
OIDC_ISSUER="https://id.example.com" # The root URL of your provider
OIDC_SCOPE="openid,profile,email" # The scopes you need
OIDC_CLIENT_ID="clientId" # The Client ID provided by your OIDC server
OIDC_CLIENT_SECRET="clientSecret" # The Client Secret provided by your OIDC server
OIDC_UID_FIELD="preferred_username" # The field to match on
OIDC_REDIRECT_URI="https://example.com/auth/auth/openid_connect/callback" # The same callback URL you provided above

Now, there is one thing worth dwelling on: the OIDC_UID_FIELD setting. This determines how accounts are matched between Mastodon and your OIDC provider. For example, if your OIDC username is michael, this will create a Mastodon account @michael@example.com.

If you later change your OIDC username (say, to michael-thomas) and log in to Mastodon again, Mastodon will see a new user and create @michael-thomas@example.com. So, yeah, you don’t want to change your OIDC username if you do this…

A couple of other settings worth considering:

If you want to disable password login altogether, add OMNIAUTH_ONLY=true to your .env.production. Users will then only be able to log in using your OIDC provider.

If you do that, you may as well also add ONE_CLICK_SSO_LOGIN=true, which skips Mastodon’s login form entirely and goes straight to the OIDC provider.

Switching to OIDC

There is an interesting wrinkle here: I already had my instance up and running, and so already had an account. When I tried to log in using my OIDC provider I got the message “Error creating an account for this identity.”

This is a sensible security feature by Mastodon, which prevents account takeovers from OIDC providers. To let me log in and link my existing @michael@thms.uk account to Pocket ID’s michael account, I needed to add ALLOW_UNSAFE_AUTH_PROVIDER_REATTACH=true to my .env.production too.

This matches on email address rather than username, though. So it requires that the OIDC user has the same email address as the Mastodon user you want to link. Keep that in mind.

Make sure you remove it again afterwards, as it isn’t called ‘unsafe’ for nothing. On a single user instance it matters less, since each account can only be attached to an OIDC provider once, but it’s still good practice.

With that done, logging in goes straight through Pocket ID and my instance is one fewer set of credentials to look after. It took far more digging than it should have, so hopefully this saves you some of it.

Comments

Join the conversation on the Fediverse.

TIL: MySQL view security context after a migration

Thu, 16 Jul 2026 06:15:00 +0000

TIL: MySQL view security context after a migration

Background: I had set up a MySQL view on a server. Then done a server migration by doing the classic dump and import dance.

After the migration I was suddenly unable to access the view, getting errors like this:

SQLSTATE[28000]: Invalid authorization specification:
1045 Access denied for user '<user>'@'<host>' (using password: YES)
(Connection: mysql, Host: <host>, Port: 3306, Database: <database>,
SQL: [SELECT * FROM `view`])

My initial thought was that I had made a mistake when defining the users or GRANTS on the new host, but no:

mysql> SELECT user, host FROM mysql.user WHERE user = '<user>';
+-----------+----------+
| user | host |
+-----------+----------+
| <user> | <host> |
+-----------+----------+

mysql> SHOW GRANTS FOR '<user>'@'<host>';
+----------------------------------------------------------------+
| Grants for <user>@<host> |
+----------------------------------------------------------------+
| GRANT USAGE ON *.* TO `<user>`@`<host>` |
| GRANT ALL PRIVILEGES ON `<database>`.* TO `<user>`@`<host>` |
+----------------------------------------------------------------+

That’s when I learned about SQL SECURITY for views. It lets you set the security context that a view or stored program runs under.

I had originally created the view with:

CREATE VIEW `view` AS
-- view definition here

The default security context for views is DEFINER, and the default definer is whichever account ran the CREATE VIEW. I’d done that on the old host, pre-migration, and mysqldump writes the DEFINER clause out into the dump, so it came across to the new server unchanged:

mysql> SELECT DEFINER, SECURITY_TYPE
    -> FROM information_schema.VIEWS
    -> WHERE TABLE_SCHEMA = '<database>' AND TABLE_NAME = '<view>';
+-------------------+---------------+
| DEFINER | SECURITY_TYPE |
+-------------------+---------------+
| <user>@<old-host> | DEFINER |
+-------------------+---------------+

See that? <user>@<old-host> is the definer, and the view runs in that account’s security context. That account doesn’t exist on the new host, so the view is what MySQL calls an orphan.

The fix is then quite straightforward:

CREATE OR REPLACE SQL SECURITY INVOKER VIEW `view` AS
-- view definition here

I chose to change the security context to INVOKER rather than repointing the definer at the new account. With INVOKER, MySQL never consults the definer account: it runs the view with the calling connection’s own privileges, which in my case is ALL PRIVILEGES on the database. The trade-off is that the invoker now needs privileges on the underlying tables too, not just on the view itself, so INVOKER isn’t the right call if you’re using views to expose a restricted slice of a table to an account that shouldn’t see the whole thing.

Comments

Join the conversation on the Fediverse.

Everything I self-host (and a few things I don't)

Fri, 10 Jul 2026 06:15:00 +0000

Everything I self-host (and a few things I don’t)

I thought it would be interesting to catalogue all the services I host for myself and my family, along with the ones I actually use but don’t self-host, and why. It’s as much a snapshot for my own reference as anything.

General philosophy

All my services (except for my static sites) run as Docker Compose services. All of my docker-compose files are tracked in Git.

Except for Headscale and Nextcloud HPB - which need direct, unproxied web access or ports open to the world - they all sit in VMs managed by Proxmox, on an HP EliteDesk 800 G3 in my cupboard.

They all proxy through an Oracle Cloud free-tier server that hosts the Headscale control node, Nextcloud HPB, and my static sites.

Static sites

I host a number of static sites for myself. I’ve written elsewhere about how I host and deploy these - Forgejo Actions copy the files to a remote Headscale node. These currently include:

thms.uk: A directory page for my domain.
michael.thms.uk: A profile page for me.
blog.thms.uk: This blog.
fedialgo.thms.uk: An algorithmic timeline client for Mastodon.

Infrastructure

Headscale: An open source, self-hosted implementation of the Tailscale control server. Yes, I could use Tailscale, but where would be the fun in that?
Headplane: An admin interface for Headscale.
Pocket ID: An OAuth 2 and OpenID Connect provider. I use this primarily for authenticating to Headscale and Headplane, but also for Forgejo, Proxmox, OCI, and a few other services.
diun: Docker Image Update Notifier. It notifies me whenever a new Docker image is available for any of my services.
Pi-hole: A DNS server that blocks ads and malicious websites. I use it primarily for resolving DNS locally within my homelab.
Caddy for proxying.

Monitoring

Grafana: A monitoring dashboard to keep track of the health of all my Docker services and VMs.
Uptime Kuma: A simple, attractive uptime monitor that I use for all my web services and important cron jobs.
status.thms.uk: A simple public status page for all my services. Powered by Uptime Kuma.
Plausible Community Edition: An analytics service to see how people read my blog and other sites so I can feel important (or unimportant?).

Coding

code.thms.uk: A Forgejo instance for my code. I also host some CI/CD runners with it, including the ones that deploy the static sites mentioned above.
paste.thms.uk: An Opengist instance to host my pastes.

Nextcloud helpers

Whilst I’m using Hetzner’s Storage Share for Nextcloud, I’ve set up a couple of ‘helpers’ in improve the experience of using Nextcloud:

Collabora CODE: Lets me edit documents from my Nextcloud instance in the browser.
Nextcloud HPB: The high-performance backend for Nextcloud Talk - needed to improve the performance of Talk, which we use for video calls etc.

mstdn.thms.uk: My self-hosted Mastodon instance.
read.thms.uk: A FreshRSS instance for reading my RSS feeds.
morss: A tool to convert non-full-text RSS feeds to full-text ones. The project is largely abandoned, and most of its functionality can now be replicated within FreshRSS itself, but a couple of my feeds still work better with morss in the middle, for whatever reason.

Others

Password Pusher: A really great tool to securely exchange passwords and other secrets.
Home Assistant for home automation.
A small number of sites and apps I’ve written myself, for myself or friends, hosted as Docker containers on my homelab.

What I’m not (yet) self-hosting

Nextcloud: I’m currently using Hetzner’s Storage Share instead of self-hosting. It’s good value for money, and given the importance of the data - and how upset my family would be about any outages - it’s the best option for now. I’m hoping to migrate to self-hosting Nextcloud eventually, but I think I’ll need better hardware for that first, including a proper RAID setup.
Email: I currently use Fastmail for my own and my family’s email, on our own custom domains. I really like the Fastmail experience, and I fear the complexity of self-hosting email - and getting deliverability right - far too much to make the move.

Wrapping up

If you self-host something I’ve not mentioned here and think I’m missing out, I’d love to hear about it in the comments/replies - especially anything that’s replaced a paid service you were glad to see the back of.

Comments

Join the conversation on the Fediverse.

Self-hosting a static site using Forgejo, Headscale, and Caddy

Tue, 30 Jun 2026 06:00:00 +0000

Self-hosting a static site using Forgejo, Headscale, and Caddy

When I first started this blog I was on the omg.lol platform.

This was a great way for me to get started, and I think without it, I probably would’ve never started my blog, so I’m really grateful for omg.lol!

But over the last few months I’ve gradually moved more and more of my stuff to self-hosted, and with omg.lol more than doubling their price (which, to be fair, is still excellent value!) it was time to move my blog to self-hosted too.

This post explains how I now host my static blog at blog.thms.uk, deployed straight from a Forgejo repo via Forgejo Actions, over a Tailscale/Headscale tailnet, onto a Caddy reverse proxy, auto-deploying when I push to main.

Set up the host machine

First job is to create a home for the site and a user to own it. The site will be hosted on my existing server that already has Caddy installed. We’ll create a deploy user that owns /var/www so the rsync at the end has somewhere to write to. On the web server, create the user and directory:

sudo useradd -m deploy
sudo mkdir /var/www
sudo chown deploy:deploy /var/www

Set up Headscale

The plan here is to let the CI runner reach the web server over the tailnet and nothing else. We do that with tags: the runner joins as tag:ci and the web server is tag:web. No keys, no exposed ports on the public internet.

I’m running my tailnet through a self-hosted Headscale instance via Docker Compose, so that’s what the rest of this section focuses on. If you’re using Tailscale you’ll have to do essentially the same steps in the Tailscale dashboard.

First, define the tags and permissions in the policy file:

{
    "tagOwners": {
      "tag:ci": ["<your-user>"],
      "tag:web": ["<your-user>"]
    },
    "acls": [
      { "action": "accept", "src": ["tag:ci"], "dst": ["tag:web:22"] }
    ],
    "ssh": [
      { "action": "accept", "src": ["tag:ci"], "dst": ["tag:web"], "users": ["deploy"] }
    ]
}

You need both acl and ssh rules because they work at different layers: the acls entry is the network firewall, while the ssh entry is what then authorises the actual SSH session.

Then restart headscale to apply the change:

docker compose up -d --force-recreate headscale

Now, assign the tag:web tag to the web server (<id> is the ID of the web server - you can find it with docker exec headscale headscale nodes list):

docker exec headscale headscale nodes tag -i <id> -t tag:web

Finally, we need a pre-auth key for the runner to authenticate with. We’ll create an ephemeral key so the node disappears from the tailnet when the job finishes (no pile-up of dead CI nodes), and mark it reusable so every run can use the same secret. We also add a long expiry to save us rotating it constantly - 876,000 hours is roughly 100 years, so dial that back if it makes you nervous:

docker exec headscale headscale preauthkeys create --ephemeral --reusable --tags tag:ci -e 876000h

This key will allow the deployer CI to join the tailnet as a machine tagged with tag:ci.

Finally, if it isn’t already on, enable Tailscale SSH on the web server:

tailscale set --ssh

Create your deployment script

With the tailnet sorted, it’s finally time to move on to the most important part of this post: the deploy workflow. We’ll create it in .forgejo/workflows/deploy.yml.

Deploying the site, for me, means:

Check out the repo.
Set up Hugo, as that’s what my blog is built with.
Build the site using hugo --minify.
Join the tailnet using Tailscale’s official GitHub Action.
rsync the site to the web server node.

Obviously steps 2 and 3 may well be different for your site, so adjust them accordingly.

It’s worth noting that step 3 produces the final static files for the blog in ./public, and that’s what we’ll be rsyncing in the final step. If your build step produces its files in a different location (or you aren’t using any build steps at all) you’ll need to change the rsync line at the end.

The comments in the file spell out each part, along with some reasoning behind each step. (If you’d rather not copy this by hand, I’ve since packaged it as a reusable action - see the postscript below.)

on:
  workflow_dispatch:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest # replace with whatever runner you have available.
    name: Deploy site
    steps:
      # 1. Check out the repo.
      - uses: https://github.com/actions/checkout@v4
        with:
          fetch-depth: 0

      # 2. Set up Hugo
      - name: Setup Hugo (extended)
        uses: https://github.com/peaceiris/actions-hugo@v3
        with:
          hugo-version: latest
          extended: true
          
      # 3. Build the site
      - name: Build site
        run: hugo --minify
        shell: bash

      # 4. Join the tailnet (Headscale) as an ephemeral, tagged node (tag:ci) via the
      # official action. authkey + login-server points it at Headscale; userspace
      # networking + a local SOCKS5 proxy means no TUN/privileges in the container.
      - name: Connect to Tailnet
        uses: https://github.com/tailscale/github-action@v3
        with:
          authkey: ${{ secrets.TS_AUTHKEY }} # Headscale pre-auth key (reusable, ephemeral)
          tailscaled-args: --tun=userspace-networking --socks5-server=localhost:1055
          args: --login-server=${{ secrets.TS_LOGIN_SERVER }} # Drop this if you are using Tailscale rather than Headscale.

      # 5. Publish ./public to the remote node over Tailscale SSH. ssh/rsync tunnel through
      # the SOCKS5 proxy the step above started.
      - name: Publish to Caddy
        env:
          SITE: blog.thms.uk # replace with your site name
          DEPLOY_HOST: ${{ secrets.DEPLOY_HOST }} # remote node tailnet IP (100.x.y.z)
          DEPLOY_USER: deploy # Unix user on the node (Tailscale SSH login)
        run: |
          set -e
          # Ensure we have all the tools we need: rsync, OpenSSH client, netcat for the SOCKS proxy
          pkgs= 
          command -v rsync >/dev/null 2>&1 || pkgs="$pkgs rsync" 
          command -v ssh >/dev/null 2>&1 || pkgs="$pkgs openssh-client" 
          command -v nc >/dev/null 2>&1 || pkgs="$pkgs netcat-openbsd" 
          [ -n "$pkgs" ] && { apt-get update -qq && apt-get install -y -qq $pkgs; }
          # Set up `~/.ssh/config` to configure the SSH tunnel and other SSH client settings
          install -d -m 700 ~/.ssh
          printf 'Host deploy-target\n HostName %s\n User %s\n ProxyCommand nc -X 5 -x localhost:1055 %%h %%p\n StrictHostKeyChecking accept-new\n ConnectTimeout 20\n BatchMode yes\n' \
            "$DEPLOY_HOST" "$DEPLOY_USER" > ~/.ssh/config
          chmod 600 ~/.ssh/config
          # create the required directory on the remote node
          ssh deploy-target "mkdir -p /var/www/$SITE"
          # rsync the site to the remote node
          rsync -az --delete -e ssh public/ "deploy-target:/var/www/$SITE/"
        shell: bash

The script requires three secrets, so add the following Action Secrets to the repository:

TS_AUTHKEY - the pre-auth key for the Tailscale node, which you created above.
TS_LOGIN_SERVER - the Headscale login server (which you can omit if you are using Tailscale).
DEPLOY_HOST - the tailnet IP address of the node you are deploying to.

Configure Caddy

The final step is getting Caddy to actually serve the files. I have Caddy running in a container, so it can’t see /var/www on the host until we mount it in - which we’ll do read-only, since Caddy only ever needs to read the site. Add the bind mount to the Caddy service:

services:
  caddy:
    # [...]
    volumes:
      - /var/www:/var/www:ro
      # other bind mounts

Then tell Caddy about the site. This is the whole config for a static site - point root at the deploy directory, turn on compression, and hand it to the file server:

blog.thms.uk {
  root * /var/www/blog.thms.uk
  encode zstd gzip
  file_server
  
  # This part is for pretty 404 pages, and assumes you have a 404 page at /404.html
  handle_errors {
    @404 expression {http.error.status_code} == 404
    rewrite @404 /404.html
    file_server
  }
}

The bind mount is a change to the container itself, so this one time you do need to recreate it:

docker compose up -d --force-recreate caddy

After that, adding new sites is much cheaper: The volume’s already mounted, so it’s just another block in the Caddyfile followed by a config reload - no restart, no dropped connections:

docker exec caddy caddy reload --config /etc/caddy/Caddyfile

Wrapping up

That’s the lot. Push to main and the site builds, joins the tailnet as an ephemeral tagged node, rsyncs ./public to the remote over Tailscale SSH, and Caddy serves it. Adding more sites later is just another block in the Caddyfile and a config reload.

Post scriptum

I’ve since extracted this deployment script into a reusable Forgejo Action, so you can drop it into your own projects without copying all the above by hand. You can find it at code.thms.uk/michael/tailscale-deploy.

Comments

Join the conversation on the Fediverse.

Using a Tailscale exit node on a Docker host

Thu, 18 Jun 2026 06:00:00 +0000

Using a Tailscale exit node on a Docker host

I’ve recently migrated my Mastodon instance to run on Docker Compose. This host sits on my home network, and gets exposed to the internet using Caddy on a VPS that’s connected to my server using Tailscale.

This works great, but I did want to route outgoing traffic through the same VPS, so that other server operators don’t see my domestic IP address in their server logs.

This should be easy enough:

On the edge server add the exit node flag:

sudo tailscale set --advertise-exit-node

Configure the Mastodon host to use the exit node:

sudo tailscale set --exit-node=<exit-node-ip> --exit-node-allow-lan-access=true

Easy as pie (yes, you also need to configure IP forwarding, may need to approve it in the admin UI, and set a policy to allow access - still easy as pie).

I did think it worked, as I ran

curl https://ip.me

and got my edge IP address.

But then I tested it from within the container:

docker exec mastodon-sidekiq-1 curl https://ip.me

and the whole thing just hung there.

The problem

Basically, the Docker host sits as a NAT device in front of the Docker containers. And when you enable the Tailscale exit node, that intercepts traffic on all interfaces and routes it via Tailscale - including traffic destined for your container subnet. So nothing can reach your Docker containers any longer, and connections just hang.

The solution

Firstly, let’s see what IP address we need to route to:

docker inspect mastodon-web-1

In the output look for IPAddress and make a note (in my case it was 172.19.0.2).

Now, check the route that your system has for that IP address:

$ ip route get 172.19.0.2
172.19.0.2 dev tailscale0 table 52 src 100.64.0.8 uid 1000
    cache

This gives us two insights:

Traffic for that IP address is indeed routed towards tailscale0, so our initial theory was correct.
The thing routing it is table 52.

So we need to add our own route to that IP address. And we need to do so with a priority that comes before (i.e. is lower than) the rule for table 52. So let’s look at our existing rules:

$ ip rule show
0: from all lookup local
5210: from all fwmark 0x80000/0xff0000 lookup main
5230: from all fwmark 0x80000/0xff0000 lookup default
5250: from all fwmark 0x80000/0xff0000 unreachable
5270: from all lookup 52
32766: from all lookup main
32767: from all lookup default

Okay, so the rule for table 52 has a priority of 5270.

Let’s add a new rule with a lower priority of 5269 (replace with a different value if your rules have different priorities, and replace your subnet, if your Docker is configured differently):

ip rule add to 172.16.0.0/12 lookup main priority 5269

This means we are routing all traffic to 172.16.0.0/12 (which covers Docker’s default subnets) outside of Tailscale, and we are doing this with priority 5269 - immediately before Tailscale’s rule. Let’s check the route now:

$ ip route get 172.19.0.2
172.19.0.2 dev br-29ab31f9f5aa src 172.19.0.1 uid 1000
    cache

indeed, this now routes to my Docker bridge device, and we can confirm by running docker exec mastodon-web-1 curl https://ip.me which should now return your exit node’s IP address rather than your own.

Making the solution permanent

I think the best solution is a quick service file that inserts the rule when Tailscale and Docker start up:

[Unit]
Description=Route Docker subnets via main table so exit-node return traffic reaches containers
After=network-online.target tailscaled.service docker.service
Wants=network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
# delete then add keeps it idempotent if the unit is re-run
# replace your subnets and/or priority as needed
ExecStartPre=-/sbin/ip rule del to 172.16.0.0/12 lookup main priority 5269
ExecStart=/sbin/ip rule add to 172.16.0.0/12 lookup main priority 5269
ExecStop=-/sbin/ip rule del to 172.16.0.0/12 lookup main priority 5269

[Install]
WantedBy=multi-user.target

Finally, enable the service:

sudo systemctl daemon-reload
sudo systemctl enable --now docker-tailscale-routing.service

Wrapping up

A bit of policy routing was all it took: one ip rule to keep Docker’s subnets out of Tailscale’s hands, made permanent with a small service file. My containers now reach the internet through the exit node like everything else, and my domestic IP stays out of other people’s logs.

Comments

Join the conversation on the Fediverse.

Moving Mastodon to Docker Compose

Mon, 15 Jun 2026 06:15:00 +0000

Moving Mastodon to Docker Compose

Now that I understand docker a lot better, I figured it’s finally time to tackle the migration of my mastodon server to docker.

This post outlines how I’ve done the migration. Turns out it’s really quite straightforward!

Inventory current setup

Firstly, we take stock of what we have: take a note of all the versions of our software dependencies, so we can point our docker compose files at the same versions. You can check all of these at the bottom of /admin/dashboard. For me these were:

Mastodon Version: glitch-soc, v4.6.0-rc.1
Postgres Version: 17.9
ES Version: 7.17.29
Redis Version: 7.0.15

Get docker compose file

Now let’s get the docker compose file from the official source. (I run glitch-soc, so I got it from https://github.com/glitch-soc/mastodon/blob/main/docker-compose.yml. If you run stock mastodon get yours from https://github.com/mastodon/mastodon/blob/main/docker-compose.yml.)

Then make some changes:

Un-comment the es service.
Point es, db, redis, web, streaming and sidekiq to the correct versions.
In the web service, un-comment depends_on: es

Migrate config

One thing that’s probably a bit controversial, but I do like to keep as much of my config as possible in the docker-compose.yml file. This allows me to add the file to git so I can version control it, and quickly see whatever might change.

In order to do this I’ll add a shared yaml anchor, with all the non-secret environment variables, and then reference this within each of the mastodon services:

x-mastodon-env: &mastodon-env
  LOCAL_DOMAIN: thms.uk
  WEB_DOMAIN: mstdn.thms.uk
  [...]

services:
  web:
    image: ghcr.io/glitch-soc/mastodon:v4.6.0-rc.1
    restart: always
    env_file: .env.production # secrets only
    environment:
      <<: *mastodon-env
    [..]

  streaming:
    image: ghcr.io/glitch-soc/mastodon-streaming:v4.6.0-rc.1
    restart: always
    env_file: .env.production # secrets only
    environment:
      <<: *mastodon-env
    [..]

  sidekiq:
    image: ghcr.io/glitch-soc/mastodon:v4.6.0-rc.1
    restart: always
    env_file: .env.production # secrets only
    environment:
      <<: *mastodon-env
    [..]

My .env.production file is now really short:

SECRET_KEY_BASE=
OTP_SECRET=
VAPID_PRIVATE_KEY=
AWS_SECRET_ACCESS_KEY=
SMTP_PASSWORD=
DEEPL_API_KEY=
ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY=
ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT=
ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY=

All of these values are simply copied from my production .env.production file.

Pull images so they are ready

We’ll pull the images, so they are ready to use when we want to migrate data. This just shortens our downtime slightly:

docker compose pull

Migrate data

Migrating the data is the same as it’s always been really. I host my media on Backblaze B2, so I don’t need to worry about this.

I also won’t bother migrating the elasticsearch index: this can simply be recreated afterwards.

As such, I need to migrate my SQL and redis databases.

We’ll firstly shut down the old system so we get a consistent state:

sudo systemctl stop mastodon-*

Then we make a postgres dump:

sudo -u mastodon pg_dump -Fc -p 5433 -d mastodon_production > mastodon.dump

And make sure we have an up-to-date redis snapshot:

redis-cli SAVE

On the new docker host we’ll now copy both files across:

scp old-vm:~/mastodon.dump ~/mastodon.dump
mkdir ./redis
scp old-vm:/var/lib/redis/dump.rdb ./redis/dump.rdb

We need to adjust permissions on the redis directory:

sudo chown -R 999:999 ./redis

And bring the redis service up:

docker compose up -d redis
docker compose logs redis

In the logs look for “DB loaded from disk”.

That’s redis ready. To import the postgres DB, firstly bring up the db service, and create the user and database:

docker compose up -d db
docker compose exec -T db psql -U postgres -c "CREATE ROLE mastodon LOGIN CREATEDB;"
docker compose exec -T db psql -U postgres -c "CREATE DATABASE mastodon_production OWNER mastodon;"

Then run the pg_restore command:

docker compose exec -T db pg_restore -U mastodon -d mastodon_production --no-owner < ~/mastodon.dump

Bring up new server

Now that this is all done, we just bring up the remaining services:

docker compose up -d

And finally we re-deploy the search index:

docker compose run --rm web nice -n 19 bin/tootctl search deploy

Wrapping up

That’s the migration done: mastodon is now running entirely on docker, with the bulk of my config version-controlled in a single docker-compose.yml. Before tearing down the old VM, give everything a once-over: check the web UI loads, federation is working, and the search index has finished deploying. Once you’re happy, the old systemd setup can go.

Postscript

I have since published the git repo which I use to track my docker compose files on Forgejo: https://code.thms.uk/michael/mastodon-compose.

Comments

Join the conversation on the Fediverse.

A multi-stage Dockerfile for Laravel and FrankenPHP

Thu, 11 Jun 2026 06:30:00 +0000

A multi-stage Dockerfile for Laravel and FrankenPHP

I recently rewrote an old website that I originally wrote 15+ years ago. Whilst I’m still running the site as a favour to old friends, I had sorely neglected it, making bug fixes incredibly difficult: It was some framework-less hot mess running on PHP 7.4, which I was really struggling to maintain.

So I decided to rewrite it in PHP 8.5 using Laravel 13, and to run it on my home lab where everything else I run lives in docker containers managed by docker compose.

So I had to learn to write my first Dockerfile. I mostly used Claude to write it for me, and then tried to figure out what each step does and why.

This post outlines what I learned, mostly as a note to self, so my learnings don’t get lost to time.

Starting point: What do I need?

I have so far been a consumer of docker only: I would get a docker-compose.yml, adjust it marginally to my need with some trial and error, and run it. So I first had to figure out what I need:

Dockerfile The Dockerfile tells docker how to build the image: Which files and software to include, in what order, etc.
Entrypoint The entrypoint is a (bash) script that runs after the image has been started, and as such is responsible for actually starting the app.
docker-compose.yml These I had seen many times before. Basically defines how the image(s) fit together, what ports they expose their service(s) on, what directories from the host they have access to etc.

Architecture

For my Laravel 13 project I need the following in my architecture:

A web server and PHP runtime. I decided on Caddy and FrankenPHP, as that’s the way the cool kids run these things now. Conveniently, FrankenPHP provides docker images that can be used as a base too
A queue worker: Based on the same image, but running as a separate service.
A cron worker: Same story.

One thing I learned in the process, but hadn’t planned out, is that I’d also want an init service that runs migrations and optimisations once at startup before the other services start.

The Dockerfile

With all of that out of the way, let’s start writing the Dockerfile.

Fundamentally, we are building the image in four discrete steps. Each step defines a slightly different image, and the final image, which we’ll push to production, only keeps what it needs from the others.

This keeps our runtime image really as small as possible, and avoids the inclusion of build tools such as git and npm in the final build.

We’ll place this file in our git repo’s root directory, and call it Dockerfile (no file ending).

Stage 1: The base build

This is really the shared foundation that everything builds on:

# syntax=docker/dockerfile:1
FROM dunglas/frankenphp:php8.5 AS base
WORKDIR /app
RUN install-php-extensions \
      pdo_sqlite \
      mbstring \
      intl \
      zip \
      gd \
      xml \
      opcache
COPY --from=composer:2 /usr/bin/composer /usr/bin/composer

COPY docker/opcache.ini /usr/local/etc/php/conf.d/zz-opcache.ini

# syntax=docker/dockerfile:1: We tell Docker to use version 1 Dockerfile syntax and features. Standard boilerplate.
FROM dunglas/frankenphp:php8.5 AS base: We are setting up an image (calling it base to reference it later) based on the official FrankenPHP image. It bundles FrankenPHP, PHP 8.5, and Caddy.
WORKDIR /app: sets /app as working directory where all later commands run from
RUN install-php-extensions ...: Install the PHP extensions our app needs.
COPY --from=composer:2 /usr/bin/composer /usr/bin/composer: This I thought was a pretty cool trick! This line grabs the composer binary from the official composer:2 image and just drops it in here, so we don’t need to install it manually.
COPY docker/opcache.ini /usr/local/etc/php/conf.d/zz-opcache.ini: This copies some opcache tuning in: as the code inside the image is immutable, we can instruct opcache to be really aggressive with its caching. Here is the content of my opcache.ini:

opcache.enable=1
opcache.enable_cli=1
opcache.memory_consumption=128
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=20000
opcache.validate_timestamps=0
opcache.revalidate_freq=0
opcache.jit=tracing
opcache.jit_buffer_size=64M

And with that our base image is complete: it contains all the binaries that our final app image needs.

Stage 2: PHP dependencies

This image will install PHP dependencies into the vendor/ folder:

FROM base AS vendor
RUN apt-get update \
 && apt-get install -y --no-install-recommends git unzip \
 && rm -rf /var/lib/apt/lists/*
COPY composer.json composer.lock ./
RUN composer install --no-dev --no-interaction --prefer-dist \
      --optimize-autoloader --no-scripts

FROM base AS vendor: build on the base, so it already has PHP + Composer.
RUN apt-get ...: installs git and unzip as they are required by composer, then deletes the package manager cache to keep the image small.
COPY composer.json composer.lock ./: From our repo, copy just these two files: It’s all composer needs
RUN composer install ...: Install production dependencies. The --no-scripts flag skips Laravel’s package discovery. We can’t run this, as that would require booting the app, which isn’t in the image, because we only copied the composer.json and lock files.

Stage 3: Asset compilation

This will build the frontend assets. This stage doesn’t use our base image or PHP. It just uses Node (which our production image won’t need):

FROM node:22-alpine AS assets
WORKDIR /app
COPY package.json package-lock.json ./
COPY resources ./resources
COPY public ./public
COPY vite.config.js tailwind.config.js postcss.config.js ./
COPY --from=vendor /app/vendor ./vendor
RUN npm ci
RUN npm run build

FROM node:22-alpine AS assets: This time we are starting from a separate lightweight Node 22 image.
COPY ...: We’ll again need to copy some stuff so that Node can build:
- package json and lock files to define dependencies
- resources folder as that’s where our JS and CSS dependencies live
- vite, tailwind, and postcss configs, as these define the configs for our build
- The vendor folder from the vendor image (built in step 2): This was a gotcha: Some Laravel dependencies ship their own JS/CSS so we need this here
RUN...: Install dependencies and build assets. The built assets will end up in public/build (or wherever else your vite.config.js instructs them to go).

Stage 4: The app image

Finally we are getting there. This is going to be the image that actually gets shipped and run in production. It primarily cherry picks parts from the preceding steps:

FROM base AS app
COPY --from=vendor /app/vendor ./vendor
COPY --from=assets /app/public/build ./public/build
COPY . .
RUN composer dump-autoload --no-dev --optimize
RUN chown -R www-data:www-data /app/bootstrap/cache /app/storage /config
ENV SERVER_NAME=":80"
EXPOSE 80
HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
  CMD php -r "exit(@file_get_contents('http://127.0.0.1:80/up') === false ? 1 : 0);"
COPY docker/entrypoint.sh /usr/local/bin/entrypoint
RUN chmod +x /usr/local/bin/entrypoint
ENTRYPOINT ["entrypoint"]
CMD ["frankenphp", "run", "--config", "/etc/frankenphp/Caddyfile"]

FROM base AS app: We start again with the base image that has FrankenPHP + composer
COPY FROM vendor ..., COPY FROM assets: Copy the installed dependencies and assets.
COPY . .: Copy the application code. We’ll define a separate .dockerignore file that will ignore the vendor folder so it shouldn’t override things.
RUN composer dump-autoload ...: As we now have both dependencies and application code the app will boot cleanly, so we can dump the auto loader, and run laravel’s package discovery.

Our app image is now fundamentally ready, but we need to wire it up to actually run something with the stuff we just built, and that’s the rest of these files:

RUN chown -R www-data:www-data we change the owner of all the generated files - don’t want to run the app as root any more than we’d do in a bare metal install.
ENV SERVER_NAME=":80": Tells FrankenPHP to serve plain HTTP on port 80. We’ll have an upstream proxy in front of this server, as it lives in my home lab.
EXPOSE 80: Documents that the container listens on port 80.
HEALTHCHECK ...: Defines a healthcheck — PHP fetches Laravel’s /up route. Docker reports the result as the container’s health status (visible in docker ps).
COPY docker/entrypoint.sh..., RUN chmod +x...: Copy the entry point and make executable. We’ll get back to that file later, but this is the script that will run when the container starts up.
ENTRYPOINT ["entrypoint"]: Tells docker to actually run the entry point script on startup.
CMD ["frankenphp", "run", "--config", ...]: The command the entrypoint hands off to: start the FrankenPHP web server with its bundled Caddyfile config.

Result

We’ll end up with a final app image that contains only PHP, application code, dependencies, and compiled assets. All the build machinery (Node, npm, git) live in throwaway stages that never ship, which makes the app image as small as it can be, and reduces attack surface.

The Docker ignore file

I mentioned this earlier. Think of it as ‘gitignore for docker’: There will be plenty of stuff in your git repo, or generated during the build process that you don’t want in the docker image. Here is mine, stored at .dockerignore in the repo root:

.git
.gitignore
node_modules
vendor
public/build
# Secrets + local state never go in the image
.env
.env.*
data
*.sqlite
# bootstrap caches. Laravel regenerates them at runtime.
bootstrap/cache/*.php
# Ephemeral storage contents (recreated by the entrypoint)
storage/app/*
storage/framework/cache/*
storage/framework/sessions/*
storage/framework/views/*
storage/logs/*
# Docker + dev files (note: docker/entrypoint.sh is intentionally NOT listed
# here — the Dockerfile COPYs it into the image, so it must stay in the context)
Dockerfile
docker-compose.yml
.dockerignore
README.md
tests
phpunit.xml

The Entrypoint

Let’s have a look at the entry point script. In a nutshell the entry point:

Ensures Laravel’s required directories (./storage/*, bootstrap/cache) as well as the SQLite database file exist (needed because ./storage and ./data are bind mounts that start empty on a fresh host).
Creates the public/storage symlink.
Fixes permissions.
Runs php artisan optimize.
Hands off to whatever command that service specified (or the default CMD).

#!/bin/sh
set -e

# The container starts as root so this script can fix ownership on the
# bind-mounted volumes, then drops to this unprivileged user to run the app.
APP_USER="${APP_USER:-www-data}"
DB_FILE="${DB_DATABASE:-/data/database.sqlite}"

# Laravel's storage skeleton must exist. storage/ is a bind mount, so on a
# fresh host it starts empty and these subdirs won't be there.
mkdir -p \
  storage/framework/cache/data \
  storage/framework/sessions \
  storage/framework/views \
  storage/logs \
  storage/app/public \
  bootstrap/cache

# Ensure the SQLite database file exists before anything opens it.
mkdir -p "$(dirname "$DB_FILE")"
touch "$DB_FILE"

# public/storage -> storage/app/public. Created here rather than via
# `artisan storage:link` so it exists in EVERY container (incl. app) without
# booting the framework, and so it survives in the app container's own fs.
ln -sfn /app/storage/app/public /app/public/storage

# Hand ownership of everything the app writes to the unprivileged runtime user.
# Done here (as root) because ./storage and /data are bind mounts that can start
# owned by the host's root on a fresh deploy.
chown -R "$APP_USER" storage bootstrap/cache "$(dirname "$DB_FILE")" /config 2>/dev/null || true
chmod -R ug+rwX storage bootstrap/cache "$(dirname "$DB_FILE")" 2>/dev/null || true

# Optimise Laravel's caches. Best-effort: a failure must never stop the container booting, 
# because the app runs fine uncached and caching is purely an optimisation. 
# Run as the app user so the cache files are owned by it, not root.
setpriv --reuid="$APP_USER" --regid="$APP_USER" --init-groups \
    php artisan optimize || echo "entrypoint: optimize failed, continuing uncached" >&2

# Drop root and exec the real command (CMD or the service's command) as the
# unprivileged user.
exec setpriv --reuid="$APP_USER" --regid="$APP_USER" --init-groups "$@"

Docker Compose services

With the app image and entry point ready, it’s time to define our docker compose services. We’ll need four of them. Each one inheriting a shared block:

x-app: &app-common
  image: code.thms.uk/michael/...
  env_file: .env
  volumes:
    - ./data:/data # the SQLite database file lives here
    - ./storage:/app/storage # logs + any file-based app storage
  restart: unless-stopped

x-app: &app-common: Is a yaml anchor, not a Docker feature. x-app is an “extension field” (the x- prefix tells Docker to ignore it as a service), and &app-common gives the block a label. Each service pulls this block in with <<: *app-common, so we define the common settings once instead of repeating them four times.
image: code.thms.uk/michael/...: The image to use. I’ve uploaded my image to my Forgejo repo, where it is rebuilt automatically every time I push to main. I will write a separate blog about this.
env_file: .env: Load environment variables from the .env file. Ensure that you define the database in there with

 DB_CONNECTION: sqlite
DB_DATABASE: /data/database.sqlite

volumes:: bind mounts that connect host folders to container folders, so data survives container restarts/rebuilds.
restart: unless-stopped: if the container’s process exits, Docker restarts it automatically.

Each of the following four services will inherit the &app-common stuff.

The init service

This service will run once on start, migrate the database, then exit. restart: "no" overrides the shared unless-stopped because this is a one-shot task. We disable healthchecks for the same reason.

services:
  init:
    <<: *app-common
    command: php artisan migrate --force
    restart: "no"
    healthcheck:
      disable: true

The web server

The next service is our web server. We use the depends_on: directive to start this service only after migrations are done. Then we map the host’s port 8080 to port 80 in the container. As such we’ll point our reverse proxy at port 8080 on this server.

  app:
    <<: *app-common
    depends_on:
      init:
        condition: service_completed_successfully
    ports:
      - "8080:80"

The cron and queue worker

These are really both the same: We override the command for each, disable healthchecks (no web server is running in here), and again make sure they only start after migrations are complete using depends_on:

  scheduler:
    <<: *app-common
    command: php artisan schedule:work
    depends_on:
      init:
        condition: service_completed_successfully
    healthcheck:
      disable: true

  queue:
    <<: *app-common
    command: php artisan queue:work --sleep=3 --tries=3 --max-time=3600
    depends_on:
      init:
        condition: service_completed_successfully
    healthcheck:
      disable: true

Deploying

To deploy this to production we now need to

Build the image and push it to our code repository.
Copy the docker-compose.yml file to our host.
Create a .env file and put it alongside the docker-compose.yml.
Run docker compose up -d on the host.

Updates are as simple as

Re-building and re-pushing the image
Running docker compose pull && docker compose up -d on the host.

We’ll be automating the building and pushing using Forgejo actions, but that’s for another day.

Comments

Join the conversation on the Fediverse.

Setting up a free Oracle VPS as a reverse proxy

Mon, 01 Jun 2026 06:00:00 +0000

Setting up a free Oracle VPS as a reverse proxy

Over the last few months I’ve gradually moved all my web services onto a little machine running in a closet at home.

Until now I’ve relied on Cloudflare Tunnels to let external traffic reach that home server, and deployed all my static pages to Cloudflare Pages.

In this post I’ll walk through how I set up a free Oracle VPS as a reverse proxy to replace those Cloudflare Tunnels.

I’m not quite sure what I’ll do about my Cloudflare Pages yet — I quite like the simplicity of these.

Basic architecture

Here’s the outline of what we’ll end up with:

One edge server. A VPS on Oracle’s Always Free tier, though it could just as easily live with any other provider, or even be self-hosted if you have a static IP. It runs Caddy to handle reverse proxying and TLS certificates.
Any number of origin servers. In my case, VMs hosted on a Proxmox box in that closet.
A tailnet to connect them all. Tailscale runs on every server, and they talk to one another over their tailnet IP addresses / hostnames.

Traffic enters through the edge server, which handles TLS termination and reverse-proxies to the right host/port combination based on the hostname.

Set up the Always Free server

Oracle’s Cloud free tier is really generous: you can run Ampere ARM instances with up to 4 CPUs and 24 GB of RAM, which is plenty for an edge proxy.

The catch is twofold. The Cloud console is cumbersome to navigate, and Oracle heavily restricts the provisioning of free Ampere ARM instances on trial accounts. To get around this, I upgraded to a Pay As You Go (PAYG) account. As long as you stay within the free tier you still won’t be charged, but the provisioning restriction goes away. All you need is a credit/debit card: Oracle places a temporary $100 hold as part of the upgrade, but they don’t actually collect anything, so it stays completely free.

I also set up a billing alert to warn me if my spend ever exceeds $0.10 in a month, just in case I accidentally provision something that incurs a cost.

I won’t cover the upgrade steps in detail here; your preferred search engine or LLM will get you there.

Install Tailscale

With the bare server up, install Tailscale on it:

Go to https://login.tailscale.com/admin/machines/new-linux
Paste and run the generated script on the new server so it joins your existing tailnet.
Optionally, enable Tailscale SSH. This lets you block SSH at the firewall so only tailnet members can reach the edge server:
```
sudo tailscale set --ssh
```

You can now close port 22 on your firewall — and while you’re there, open ports 80 and 443 for HTTP(S) traffic.

Install Docker

We’ll use Docker to manage Caddy on the edge server. The built-in repository would work, but I prefer the official one, so let’s start by adding Docker’s GPG key to apt:

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

Then add the Docker repository itself:

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Update the package list and install Docker:

sudo apt update
sudo apt install docker-ce

Finally, I always add the current user to the docker group so we don’t need sudo every time:

sudo usermod -aG docker ${USER}

Set up Caddy with Docker

Create a directory and change into it:

mkdir caddy
cd caddy

Create a docker-compose.yml file:

services:
  caddy:
    image: caddy:latest
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
      - caddy_config:/config

volumes:
  caddy_data:
  caddy_config:

Create a Caddyfile:

# optionally redirect `www.` to the bare domain
www.example.com {
  redir https://example.com{uri}
}
# reverse proxy to the backend server using its Tailnet IP address (or hostname)
example.com {
  reverse_proxy 100.x.y.z
}

Since we’re on the tailnet, you can use the hostname here instead of the IP address if you prefer.

Point your DNS

If you haven’t already, point your domain at the edge server’s public IP address before continuing.

Start Caddy

docker compose up -d

That’s it. In the background, Caddy provisions a TLS certificate, and within a few seconds your new site is served through the edge server.

Adding more sites

To put another site behind the reverse proxy, just add it to your Caddyfile:

example.org {
reverse_proxy 100.x.y.z
}

then validate and reload Caddy:

docker exec caddy caddy validate --config /etc/caddy/Caddyfile
docker exec caddy caddy reload --config /etc/caddy/Caddyfile

Conclusion

That’s a complete, free reverse-proxy setup: an Oracle Always Free edge server running Caddy, connected to your home servers over Tailscale, with automatic TLS and a one-line process for adding new sites. Compared to Cloudflare Tunnels, you get something you fully control, with no single provider sitting in front of your ingress — and it costs nothing to run.

Comments

Join the conversation on the Fediverse.

Auto-Deploying a static site from Forgejo to CloudFlare Pages

Wed, 20 May 2026 06:15:00 +0000

Auto-Deploying a static site from Forgejo to CloudFlare Pages

When migrating from GitHub to my self-hosted Forgejo instance, I’ve lost the ability to use GitHub Pages to host a couple of static pages I have been hosting on GitHub.

One alternative is CloudFlare Pages. And whilst CloudFlare Pages has a direct integration with GitHub to deploy from GitHub to CloudFlare, no such direct integration exists with Forgejo.

This post walks us through setting up a Forgejo Action that will auto-deploy to CloudFlare Pages on every push.

Note: If you want to fully self host your static site, you may wish to have a look at how I’m self hosting my blog using Forgejo, Caddy, and Tailscale

Prerequisites

Here is what you need before you get started:

A Forgejo account on an instance with a runner configured. If you are self hosting look at the Forgejo docs on setting up a runner.
A CloudFlare account.

Creating your CloudFlare Page

Before you can deploy from your Forgejo action you must manually create a CloudFlare Page, and upload the first deployment manually by uploading it in the CloudFlare UI:

Go to dash.cloudflare.com, and under Build > Compute, find Workers & Pages.
Click the blue Create Application button.
Find the small “Looking to deploy Pages? Get started” text underneath the card - CloudFlare are hiding it these days.
On the next page for “Drag and drop your files” click Get Started.
Give it a name such as my-page and click ‘Create project’. You’ll need that name later, as that’s how CloudFlare identifies your page.
Upload the files or folders for your first deployment (You could always just upload a folder with a single index.html file if you wanted to at this stage).
Click ‘Deploy site’

Your page is now ready, and accessible at https://my-page.pages.dev (or whatever else you may have chosen for your name).

You can set up your custom domain now, if you wish, as well as any other configuration options.

Getting a CloudFlare Access Token and Account ID

Next we’ll need to get your Account ID and generate an Access Token for the automated deployments:

Go to Manage Account > Account API Tokens and click ‘Create Token’.
Assign the correct permissions: You’ll need Read and Edit access for Pages (which is found under the Developer Platform heading). Set your expiration and/or IP address restrictions if desired.
On the next page you’ll be presented with your Account ID and your API Token. Take a note of both. You’ll need them.

Configure your Forgejo Action

We’ll need to provide the Account ID and Token to Forgejo as Secrets. That way they stay out of our code and hidden from prying eyes: Go to your repository settings, and find Actions > Secrets in the left column. Provide two secrets: CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN. It should look like this:

Creating your Forgejo Action

In your repository create a file at .forgejo/workflows/deploy.yml.

Paste the following content:

on:
  workflow_dispatch:
  push:
    branches: [main] # replace branch name, if you are not using `main`

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: npm install
        run: npm install

      - name: build
        run: npm run build

      - name: Deploy to Cloudflare Pages
        run: npx wrangler@latest pages deploy ./dist --project-name=my-page # replace `./dist` with your build output directory, and `my-page` with your name chosen earlier
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

This action makes the following assumptions:

You will be deploying from your main branch - you can adjust the branch on line 4 if needed.
We’ll also add the workflow_dispatch trigger. This will enable a button in the Forgejo UI to allow you to trigger a manual deploy should you wish to do so.
You are using npm install and npm run build as your build process. If you don’t need those, you can remove those steps. if you need different steps you can replace or add them.
Your build output directory is ./dist and your page name my-page - replace on line 23 if needed.

If you don’t use any build process you can skip the install and build steps. E.g. I have one repo that is just static HTML, CSS and JS. In this case I just need to delete the .git and .forgejo directories before deployment:

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Delete unwanted files
        run: |
          rm -rf .forgejo
          rm -rf .git

      - name: Deploy to Cloudflare Pages
        run: npx wrangler@latest pages deploy ./ --project-name=my-page
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

And that’s it - your site will be deployed to CloudFlare Pages automatically every time you push to your Forgejo instance.

Comments

Join the conversation on the Fediverse.

Re-verifying failed backups with Proxmox Backup Server

Tue, 05 May 2026 06:15:00 +0000

Re-verifying failed backups with Proxmox Backup Server

I’m running Proxmox Backup Server using Backblaze B2 (an S3 compatible object storage service) for storing backups. This does work fine, but my scheduled verification (I verify once a week) regularly fails on some backups due to what appears to be transient issues with the B2 API. I simply get these entirely unhelpful entries in my verification log:

verify backblaze:ct/{id}/{timestamp}/root.pxar.didx failed: chunks could not be verified

I wanted to have a simple script that would attempt a re-verification job of any backups that are currently marked as ‘failed’ on the backup store, so I can simply re-try: If verification still fails I assume the backup is broken. But otherwise I can just move on.

The script is pretty straightforward: First get a list of failed backups, then create a new verification ensuring we pass in --ignore-verified false so it actually re-verifies.

You can run the script with --dry-run to see a list of any backups that would be re-verified.

#!/bin/bash
DATASTORE="backblaze" # replace with your datastore name!

# Verify Dry Run
DRY_RUN=false
if [‎[ "$1" == "--dry-run" ]‎]; then
    DRY_RUN=true
    echo ""
    echo "-------------------------------------------------"
    echo "Dry run mode — no verification will be triggered."
    echo "-------------------------------------------------"
    echo ""
fi

# Wait while a verification job is running - we don't want to have multiple jobs running in parallel
while proxmox-backup-debug api get /nodes/pbs/tasks \
  --running true \
  --output-format json 2>/dev/null \
  | jq -e '[.[] | select(.worker_type == "verificationjob" or .worker_type == "verify_snapshot")] | length > 0' > /dev/null 2>&1; do
    echo "Verification job still running, waiting 60s..."
    sleep 60
done

# get list of failed jobs
FAILED=$(proxmox-backup-debug api get /admin/datastore/$DATASTORE/snapshots \
  --output-format json 2>/dev/null \
  | jq -r '.[] | select(.verification.state == "failed") | "\(.["backup-type"]) \(.["backup-id"]) \(.["backup-time"])"')

# Bail out if nothing has failed
if [ -z "$FAILED" ]; then
    echo "No failed backups found."
    exit 0
fi

# Re-Verify any failed jobs
while IFS=' ' read -r BTYPE BID BTIME; do
    LABEL="$BTYPE/$BID/$(date -u -d "@$BTIME" '+%Y-%m-%dT%H:%M:%SZ')"
    echo "Re-verifying $LABEL..."
    if [ "$DRY_RUN" = false ]; then
        proxmox-backup-debug api create /admin/datastore/$DATASTORE/verify \
          --backup-type "$BTYPE" \
          --backup-id "$BID" \
          --backup-time "$BTIME" \
          --ignore-verified false
    fi
done <<< "$FAILED"

As I’m running my verifications on schedule on Sunday evenings, I’ve scheduled the re-verification for early Monday mornings:

0 1 * * 1 /path/to/reverify-backups.sh > /path/to/reverify-backups.log 2>&1

Comments

Join the conversation on the Fediverse.

FreshRSS mobile improvements

Mon, 23 Mar 2026 01:00:00 +0000

FreshRSS mobile improvements

I have recently started using a self-hosted version of FreshRSS to aggregate RSS feeds. I love it, and the web version is pretty good, but the mobile version needed some work for my taste. I have used the Custom CSS and Custom JS extensions to make some minor adjustments:

Converted the article list into multiple lines.
Added some more space for the article summary.
Hide the fixed footer bar when scrolling.

Here is a before/after comparison:

Custom CSS

Navigate to Configuration > Extensions.
Click the gears button next to Custom CSS. (Don’t forget to activate it.)
Paste the below.

.flux .flux_header .item .summary {
    /* Remove excessive white space from summary */
    white-space: normal; 
}
.flux .flux_header .item .item-element.bookmark {
    /* Remove ellipsis from bookmark/favourite icon */
    text-overflow: clip;
}
@media (max-width: 840px) {
    /* Set up layout */
    .flux .flux_header:has(.thumbnail):has(.summary) {
 display: grid;
 grid-template-columns: auto 1fr auto auto auto;
 grid-template-rows: auto auto;
 grid-template-areas:
 "website website manage-read manage-bookmark manage-share manage-labels link"
 "thumbnail content content content content content content";
 align-items: start;
 list-style: none;
 }
 /** place all the elements in their respective template areas */
 .flux .flux_header:has(.thumbnail):has(.summary) li.website {
 grid-area: website;
 }
 .flux .flux_header:has(.thumbnail):has(.summary) li.thumbnail {
 grid-area: thumbnail;
 }
 .flux .flux_header:has(.thumbnail):has(.summary) li.titleAuthorSummaryDate {
 grid-area: content;
 }
 .flux .flux_header:has(.thumbnail):has(.summary) li.manage:has(.read) {
 grid-area: manage-read;
 }
 .flux .flux_header:has(.thumbnail):has(.summary) li.manage:has(.bookmark) {
 grid-area: manage-bookmark;
 }
 .flux .flux_header:has(.thumbnail):has(.summary) li.link {
 grid-area: link;
 }
 .flux .flux_header:has(.thumbnail):has(.summary) li.labels {
 grid-area: manage-labels
 }
 .flux .flux_header:has(.thumbnail):has(.summary) li.share {
 grid-area: manage-share
 }

 /** Show feed name */
 .flux .flux_header:has(.thumbnail):has(.summary) li.website {
 width: auto;
 }
 .flux .flux_header:has(.thumbnail):has(.summary) li.website .websiteName {
 display: inline;
 }

    .flux .flux_header:has(.thumbnail):has(.summary) .item .summary {
        /* This now gives us space for a 3rd row in the summary */
        -webkit-line-clamp: 3;
    }

    /* Hide footer scrolling down */
    #nav_entries {
        transition: transform 0.3s ease;
    }
    body.scrolling-down #nav_entries {
        transform: translateY(100%);
    }

}

Custom JS

Paste the below into Custom JS. It’s just the bit needed to get the fixed footer hidden when scrolling down:

let lastY = 0;

window.addEventListener('scroll', () => {
  const y = window.scrollY;
  document.body.classList.toggle('scrolling-down', y > lastY && y > 80);
  lastY = y;
}, { passive: true });

Comments

Join the conversation on the Fediverse.

Self-Hosting Mastodon Behind Cloudflare Tunnel

Wed, 18 Mar 2026 06:15:00 +0000

Self-Hosting Mastodon Behind Cloudflare Tunnel

I recently migrated my Mastodon server to my homelab. As I’m on a domestic UK internet connection, my IP address changes periodically - which rules out relying on a static public IP. I also didn’t want to forward ports 80 and 443, so I opted for Cloudflare Tunnels instead.

Here’s how I got Mastodon running behind a Cloudflare Tunnel.

Set Up Mastodon

I covered the initial setup in my first ever blog post, so I won’t repeat it here. For the migration of my existing server I followed the official migration docs which are really really thorough.

Set Up Cloudflare Tunnel

Install cloudflared. On Ubuntu or another Debian-based distro, I recommend using the Cloudflare package repository:

# Add the Cloudflare GPG key
sudo mkdir -p --mode=0755 /usr/share/keyrings
curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null

# Add the repo to your apt sources
echo 'deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared any main' | sudo tee /etc/apt/sources.list.d/cloudflared.list

# Install cloudflared
sudo apt-get update && sudo apt-get install cloudflared

Log in:
```
cloudflared tunnel login
```
Create a tunnel:
```
cloudflared tunnel create mastodon
```
mastodon here is just the internal name for the tunnel - it’s for your reference only. Cloudflare will return a tunnel UUID; keep a note of it for the next step.

Configure the tunnel by creating ~/.cloudflared/config.yml:

tunnel: {uuid} # replace with your UUID here
credentials-file: /home/mastodon/.cloudflared/{uuid}.json # replace with your UUID here

ingress:
  - hostname: mastodon.example.com # replace with your Mastodon domain
    service: https://127.0.0.1:443
    originRequest:
      httpHostHeader: mastodon.example.com # replace with your Mastodon domain
      noTLSVerify: true
  - service: http_status:404

Two things to note here:

originRequest.httpHostHeader must be set, otherwise the underlying nginx can’t identify your virtual host.
originRequest.noTLSVerify: true is required because nginx won’t have a valid certificate for 127.0.0.1. Without this, the tunnel will refuse to connect.

Create the DNS record:
```
cloudflared tunnel route dns mastodon mastodon.example.com
```
Replace mastodon with your tunnel name (if you used a different one in step 3), and mastodon.example.com with your actual domain.

Install cloudflared as a service:

sudo cloudflared --config /home/mastodon/.cloudflared/config.yml service install

That’s it. Visit https://mastodon.example.com in your browser and you should land on your Mastodon instance.

Comments

Join the conversation on the Fediverse.

Setting Up BIMI for Your Email

Tue, 17 Mar 2026 06:15:00 +0000

Setting Up BIMI for Your Email

Some mail clients (e.g. Gmail, Fastmail) show sender avatars in the inbox next to the sender name. Where they don’t have a logo on file, they’ll often fall back to initials.

BIMI is a DNS-based standard that tells email clients which logo to display for your domain - a straightforward way to get your brand logo showing up in recipients’ inboxes.

Limitations

BIMI is far from a perfect solution. To do it properly you need a Verified Mark Certificate (VMC), which costs $500+ per year and isn’t easy to obtain. Support is also patchy - not all clients honour it, and many use their own fallback mechanisms regardless (Fastmail, for example, seems to prefer Gravatar, then the domain’s favicon).

Self-Asserted BIMI

You can set up BIMI without a certificate, which eliminates the cost. This is known as self-asserted BIMI, and it’s currently only supported by AOL/Yahoo - so the practical value is limited. That said, it’s a straightforward process, so here’s how to do it.

DMARC Requirements

Before you start, you need a DMARC record set to either quarantine or reject. If you have a pct value set, it must be 100. In short, you need strict DMARC alignment in place.

If you’re not familiar with DMARC, I’ve written about SPF, DKIM, and DMARC previously - you’ll need all three configured correctly before proceeding.

A minimal DMARC record looks like this:

v=DMARC1; p=reject; sp=reject; pct=100;

The Logo

The logo must be an SVG file, but not just any SVG - it needs to conform to the SVG Portable/Secure (SVG P/S) standard. This is a strict (and somewhat obscure) subset of SVG that most vector editors don’t export natively. The easiest path is to export your logo as a standard SVG, then run it through a converter. I used EasyDMARC’s BIMI logo converter.

Once converted, open the file and update the <title></title> element to your company name, then host it somewhere publicly accessible.

Setting the BIMI Record

Add a TXT record at default._bimi.<your-domain>. Here’s mine as an example:

dig default._bimi.thms.uk txt +short
"v=BIMI1; l=https://media.thms.uk/logo-bimi.svg; avp=personal;"

Breaking down the fields:

v=BIMI1 - identifies this as a BIMI record.
l=https://media.thms.uk/logo-bimi.svg - the URL of your hosted SVG logo.
avp=personal - Avatar Preference. personal means the client should show the sender’s personal avatar if one exists, falling back to the BIMI logo. brand always shows the BIMI logo and is the default if this field is omitted.
a=https://example.com/certificate.pem - the location of your VMC certificate (.pem file). Omit this if you’re going self-asserted.

Testing Your BIMI Record

MXToolbox has a dedicated BIMI checker at https://mxtoolbox.com/bimi.aspx. Enter your domain and you’ll get results immediately.

Comments

Join the conversation on the Fediverse.

On Serving Markdown to AI Agents

Fri, 27 Feb 2026 06:15:00 +0000

On Serving Markdown to AI Agents

Recently the idea of serving Markdown to AI agents has gained traction. Cloudflare wrote about it and built a dashboard toggle to convert responses to Markdown automatically, using content negotiation to detect whether the requesting client wants Markdown or HTML.

Spatie then released laravel-markdown-response, a Laravel package that does much the same thing - but goes a step further by detecting AI agents via User Agent and serving them Markdown by default, even without an explicit Accept: text/markdown header.

Why this is interesting

AI is increasingly how people interact with the web, and AI responses are increasingly citing sources - meaning click-throughs from AI are becoming a meaningful traffic source, even if lower volume than traditional search.

This creates a new SEO-adjacent consideration: if your content is easier for AI to parse, does it get cited more often? Hugely speculative, but then so was a lot of early SEO thinking.

There’s also a practical bandwidth argument. AI crawlers can hammer a server, and if serving raw Markdown is cheaper to generate and transfer than a full HTML page - especially if Markdown is already your source format - that’s a worthwhile optimisation.

But ChatGPT can’t handle `text/markdown`

I tried implementing a similar mechanism in a project I’m working on: serve raw Markdown if the client sent Accept: text/markdown, or if the User Agent matched a known AI bot. Otherwise, serve normal HTML.

I was pleased with the results: If nothing else it’s cool and fun to do. However, within a day the editorial team complained. They had asked ChatGPT to summarise an article on the site and got:

I couldn’t load the text of the exact article you linked directly, but based on the parts that are visible in search results and summaries of that piece […]

I reverted the change, re-tested in a fresh conversation (ChatGPT caches responses and won’t re-fetch the same URL within a conversation), and it worked fine.

Clearly ChatGPT just can’t handle markdown responses. Not what I wanted.

I asked ChatGPT to explain the failure. The relevant part of its response (unbelievably it gave me a 5.5k character novel in response to a short question):

The browsing system I use does MIME-type gating before parsing. It expects:

text/html

application/xhtml+xml

sometimes text/plain

When it sees Content-Type: text/markdown it typically […] rejects the response as non-renderable, aborts parsing [and] surfaces a generic “failed to fetch” error.

This is not a limitation of “AI” in general. It’s a limitation of the controlled browsing sandbox’s MIME policy.

If you pasted the Markdown directly into chat, I could read and parse it instantly. But when retrieving via HTTP, strict MIME validation applies.

Conclusion

The idea has merit - reduced bandwidth, simpler parsing, potential AI visibility benefits. But don’t rely on User Agent sniffing to decide who gets Markdown without first verifying that each bot on your list can actually handle a text/markdown response. ChatGPT, at least for now, cannot.

Comments

Join the conversation on the Fediverse.

Adding Plausible to Uptime Kuma Status Page

Mon, 16 Feb 2026 06:15:00 +0000

Adding Plausible to Uptime Kuma Status Page

Since version 2.1, Uptime Kuma supports adding Plausible to its status pages. However, the setup is unintuitive and not documented: it asks for an Analytics ID and an Analytics Script URL.

These field names are generic, and when you create a site in Plausible, neither value is explicitly provided. Instead, Plausible gives you a single script snippet to copy and paste. That script contains what appears to be an ID (a random alphanumeric string prefixed with pa-), but this is not the Analytics ID that Uptime Kuma expects. In fact, none of the required values are shown directly in Plausible’s installation instructions.

Having had a look at the code, it becomes clear what Uptime Kuma actually expects:

Analytics ID
This is simply your status page domain, for example status.example.com. It must match the domain you configured when creating the site in Plausible.
Analytics Script URL
This is the legacy (pre–October 2025) script URL, which is the same for all sites. For Plausible Cloud, use https://plausible.io/js/script.js. If you are running Plausible Community Edition, replace plausible.io with your own Plausible instance domain.

Once these two values are entered into the Status Page configuration in Uptime Kuma, Plausible tracking should function correctly.

Comments

Join the conversation on the Fediverse.

Investigating the performance of Laravel's `whereIn` vs `whereIntegerInRaw`

Thu, 08 Jan 2026 06:15:00 +0000

Investigating the performance of Laravel’s `whereIn` vs `whereIntegerInRaw`

I recently came across a post claiming that Laravel’s ->whereIn() method is slow and that you should prefer ->whereIntegerInRaw() when working with integer IDs.

This claim appears to trace back to a 2016 blog post where the author reported that a ->whereIn() query with 10,000 IDs took ~4 seconds, and with 20,000 IDs ~15 seconds.

Notably, that post did not include comparable timings for ->whereIntegerInRaw().

Historically, I believe the root cause was not Laravel itself, but an old PDO bug related to parameter binding, which was fixed around 2020. Given that, I wanted to see whether the performance penalty still exists today - and if so, how significant it actually is.

What’s the difference between the two?

Firstly, let’s look at the actual difference between the two:

->whereIn() uses prepared statements, so the resulting query will look like this (assuming MySQL):

-- Step 1: Prepare the statement
PREPARE stmt FROM 'SELECT * FROM models WHERE id IN (?,?)';
SET @id1 = 1, @id2 = 2;
EXECUTE stmt USING @id1, @id2;
DEALLOCATE PREPARE stmt;

->whereIntegerInRaw() on the other hand casts every value in your array to (int) before simply adding them to the statement, so the resulting query will be a lot simpler and look like this:

SELECT * 
FROM models
WHERE id IN (1,2)

Testing

I wanted to answer two questions:

Is there still a measurable performance difference between ->whereIn() and ->whereIntegerInRaw() in 2026?
If so, does the difference still scale non-linearly as the input size grows?

To test this, I wrote a small benchmark that queries between 1,000 and 50,000 IDs using both methods and compares execution time.

To isolate query performance, I used ->count() instead of ->get() to avoid the overhead of hydrating large collections, which would otherwise dominate the results.

Here’s the script:

foreach (
    [
        1_000,
        10_000,
        20_000,
        50_000,
    ]
    as $number
) {
    echo "Number of Records: ".number_format($number).PHP_EOL;
    
    $start = hrtime(true);
    Model::query()
        ->whereIn('id', range(1, $number))
        ->count();
    $durationWhereIn = hrtime(true) - $start;

    printf('Duration: %s ms (whereIn)%s',
        number_format($durationWhereIn / 1_000_000, 2),
        PHP_EOL
    );

    $start = hrtime(true);
    Model::query()
        ->whereIntegerInRaw('id', range(1, $number))
        ->count();
    $durationRaw = hrtime(true) - $start;

    printf('Duration: %s ms (whereIntegerInRaw)%s',
        number_format($durationRaw / 1_000_000, 2),
        PHP_EOL
    );

    printf('Time difference: %s ms / %s%%%s',
        number_format(($durationWhereIn - $durationRaw) / 1_000_000, 2),
        round(($durationWhereIn - $durationRaw) / $durationWhereIn * 100, 2),
        PHP_EOL.PHP_EOL,
    );
}

And the output:

Number of Records: 1,000
Duration: 67.10 ms (whereIn)
Duration: 4.06 ms (whereIntegerInRaw)
Time difference: 63.04 ms / 93.95%
Number of Records: 10,000
Duration: 109.93 ms (whereIn)
Duration: 9.54 ms (whereIntegerInRaw)
Time difference: 100.39 ms / 91.32%
Number of Records: 20,000
Duration: 134.75 ms (whereIn)
Duration: 18.03 ms (whereIntegerInRaw)
Time difference: 116.73 ms / 86.62%
Number of Records: 50,000
Duration: 226.52 ms (whereIn)
Duration: 41.59 ms (whereIntegerInRaw)
Time difference: 184.93 ms / 81.64%

Takeaways

Yes, ->whereIn() is slower than ->whereIntegerInRaw(). This is expected: ->whereIn() relies on parameter binding, which has non-zero overhead. That said, it’s still surprising to see differences approaching an order of magnitude in relative terms.
The absolute difference is small. Even at 50,000 IDs, the gap is ~185 ms. In most real-world applications, this is unlikely to be the dominant bottleneck.
The relative difference decreases as the input grows. While the percentage difference is large for small sets, it steadily declines as the number of IDs increases. For very large IN clauses, the overhead of binding becomes less significant relative to the rest of the query execution. This is the opposite of the observation from 2016.
In 2026, switching to ->whereIntegerInRaw() is probably no longer worth it. I feel that the readability and simplicity of ->whereIn() generally outweigh the modest performance gain.

As always: benchmark in your own environment. Your database, driver, schema, and workload will matter far more than any micro-optimization shown here.

Comments

Join the conversation on the Fediverse.

Adding Plausible to Mastodon Using nginx `sub_filter`

Mon, 05 Jan 2026 06:15:00 +0000

Adding Plausible to Mastodon Using nginx `sub_filter`

I’m running an instance of Plausible Analytics Community Edition on my VPS, mostly so I can see how many people read my blog.

I don’t actually need analytics - I have no plans to monetise the site - but it’s interesting to see what people engage with, and self-hosting Plausible was an itch I wanted to scratch anyway.

In this post I’ll explain how I also injected Plausible Analytics into my Mastodon instance’s web UI, and then explain why you probably shouldn’t do this yourself 😁

Set up Plausible Analytics

Start by creating a new site in Plausible and copying the tracking code it gives you.

It’ll look something like this:

<!-- Privacy-friendly analytics by Plausible -->
<script async src="https://plausible.example/js/pa-abcdef.js"></script>
<script>
  window.plausible=window.plausible||function(){(plausible.q=plausible.q||[]).push(arguments)},plausible.init=plausible.init||function(i){plausible.o=i||{}};
  plausible.init()
</script>

The first thing we’ll do is remove comments and unnecessary whitespace so the whole thing fits on a single line. This is purely because nginx’s sub_filter is much easier to work with that way:

<script async src="https://plausible.example/js/pa-abcdef.js"></script><script>window.plausible=window.plausible||function(){(plausible.q=plausible.q||[]).push(arguments)},plausible.init=plausible.init||function(i){plausible.o=i||{}};plausible.init()</script>

Keep this handy - you’ll need it in the next step.

Configure `sub_filter`

On your Mastodon server, open your nginx configuration file (for me this lives at /etc/nginx/sites-enabled/mastodon) and find the @proxy location block.

We’ll use sub_filter to replace the closing </body> tag with our Plausible script followed by </body>:

server {
    [...]
    location @proxy {
        [...]

        sub_filter '</body>' '{your tracking script here}</body>';
        sub_filter_once on;
    }
}

Replace {your tracking script here} with the single-line Plausible snippet from above.

Then validate and reload nginx:

nginx -t
systemctl reload nginx

Fix Content Security Policy headers

If you now load your Mastodon instance in a browser, you’ll see two errors in the console:

Loading the script 'https://plausible.example/js/pa-abcdef.js' violates the following Content Security Policy directive: "script-src 'self' https://mastodon.example 'wasm-unsafe-eval'". Note that 'script-src-elem' was not explicitly set, so 'script-src' is used as a fallback. The action has been blocked.

and:

Executing inline script violates the following Content Security Policy directive 'script-src 'self' https://mastodon.example 'wasm-unsafe-eval''. Either the 'unsafe-inline' keyword, a hash ('sha256-Ui4JgH0e3Hy16saR0evkbiiRF3sLnhJ6gTgTVWOYDFI='), or a nonce ('nonce-...') is required to enable inline execution. The action has been blocked.

This is expected. Mastodon’s Content Security Policy correctly blocks both the external Plausible script and the injected inline JavaScript.

To fix this, we need to extend the existing CSP.

Extract the current CSP

First, grab the CSP header your instance currently sends. There are several ways to do this; one easy option is to visit securityheaders.com and enter your Mastodon URL.

Scroll down to Raw Headers and copy the content-security-policy header into your editor.

Update connect-src

Find the connect-src directive and add your Plausible domain:

connect-src 'self' data: blob: https://mastodon.example https://media.mastodon.example wss://mastodon.example https://plausible.example;

Update script-src

Next, update the script-src directive. You need to add:

Your Plausible domain
The SHA-256 hash shown in the browser error for the inline script (replace the example hash below with your own)

Example:

script-src 'self' https://mastodon.example 'wasm-unsafe-eval' https://plausible.example 'sha256-Ui4JgH0e3Hy16saR0evkbiiRF3sLnhJ6gTgTVWOYDFI='

Example full CSP

Putting it all together, your final header might look something like this:

base-uri 'none'; default-src 'none'; frame-ancestors 'none'; font-src 'self' https://mastodon.example; img-src 'self' data: blob: https://mastodon.example https://media.mastodon.example; media-src 'self' data: https://mastodon.example https://media.mastodon.example; manifest-src 'self' https://mastodon.example; form-action 'none'; child-src 'self' blob: https://mastodon.example; worker-src 'self' blob: https://mastodon.example; connect-src 'self' data: blob: https://stati.stic.dev https://mastodon.example https://media.mastodon.example wss://mastodon.example https://plausible.example; script-src 'self' https://mastodon.example https://stati.stic.dev 'wasm-unsafe-eval' https://plausible.example 'sha256-Ui4JgH0e3Hy16saR0evkbiiRF3sLnhJ6gTgTVWOYDFI='; frame-src 'self' https:; style-src 'self' https://mastodon.example 'nonce-d8e4i1dmKEMCD9Wl6x+Usw=='

Note

Your CSP will differ from mine. Differences may include:

Different domains

No separate media domain

Different nonces (or none at all)

A different SHA hash for the inline script

Plenty of other small variations

Do not copy this header verbatim. Don’t even use it as a starting point. Use your own CSP as a base and apply only the changes described above.

Apply the new CSP in nginx

Open your nginx config again and return to the @proxy location.

Add two directives: one to remove Mastodon’s CSP header, and one to add your modified version:

server {
    [...]
    location @proxy {
        [...]
        proxy_hide_header Content-Security-Policy;
        add_header Content-Security-Policy "{your header here}" always;
    }
}

Replace {your header here} with your full CSP string. Make sure it’s wrapped in double quotes, uses single quotes internally, and ends with the unquoted always keyword.

Finally, validate your config file,

nginx -t

and if everything is OK, reload nginx:

systemctl reload nginx

If everything worked, the console errors should be gone and you should start seeing events in Plausible.

Why you shouldn’t install Plausible on your Mastodon instance

I did this mostly out of curiosity and as a learning exercise. Here are a few reasons - in no particular order - why you probably shouldn’t:

It violates fediverse norms. Mastodon and the fediverse strongly lean towards a no-tracking social contract. On a single-user instance this mostly affects me, but on a multi-user instance this would be a serious breach of trust.
The data is incomplete. Traffic from mobile and desktop apps isn’t tracked at all - only users accessing the web UI.
The data is really incomplete. Federated traffic is entirely invisible. For a single-user instance especially, the vast majority of readers will never hit your web UI.
CSP changes are brittle. Editing Content Security Policy headers is fiddly and error-prone. If Mastodon updates its CSP, you’ll need to manually track and merge changes - and you’ll probably only notice when something breaks.

So let me repeat: you probably shouldn’t do this. At best it’s a mostly pointless exercise; at worst it undermines user trust.

That said, I wanted to know whether it was possible to add Plausible to Mastodon’s web interface. The answer is yes - and it’s not particularly hard.

Comments

Join the conversation on the Fediverse.

Using Pi-hole as a DNS Server for my Tailnet

Tue, 16 Dec 2025 06:15:00 +0000

Using Pi-hole as a DNS Server for my Tailnet

After recently setting up Pi-hole as my home DNS server and network-wide ad blocker, I wanted to be able to use it when I’m away from home on mobile data as well. I also wanted all of my servers (such as my Mastodon instance) to use the same DNS infrastructure.

I already use Tailscale across my devices. My Raspberry Pi, which runs Pi-hole, is configured as an exit node for situations where I’m on dodgy Wi-Fi. However, I don’t want to route all traffic from all devices through my home network. Exit nodes are inherently slower: they’re limited by upstream bandwidth and by the CPU cost of decrypting and re-encrypting every packet.

Fortunately, with a small amount of additional configuration, it’s possible to make every device in your Tailnet use Pi-hole only for DNS, without routing general traffic through an exit node. Here’s how.

Configure Pi-hole to accept Tailnet traffic

First, Pi-hole needs to accept DNS queries originating from your Tailnet. By default, Pi-hole only accepts connections from local devices, which is the correct and safe default, as you don’t want to open your Pi-hole to the internet.

However, if your firewall rules are sane and you understand the implications, you can relax this restriction. In the Pi-hole admin UI, go to Settings → DNS → Interface settings and select Permit all origins.

Before enabling this, make sure you read the official documentation so you understand exactly what this option does and when it’s appropriate.

Install Tailscale on the Pi-hole host

Tailscale has excellent installation documentation, so I won’t repeat it here.

If you’re feeling lazy, don’t mind running a remote install script directly from the internet, and generally live the YOLO lifestyle, you can install it with:

curl -fsSL https://tailscale.com/install.sh | sh

Otherwise, follow the manual installation steps in the docs.

Configure Tailscale DNS to use Pi-hole

Next, tell Tailscale to use your Pi-hole instance as a DNS resolver for the entire Tailnet.

Open the Tailscale Admin Dashboard and navigate to the DNS tab.
Scroll to Nameservers and click Add nameserver.
Select Custom.
Enter your Pi-hole’s Tailscale IP address.
Optionally enable Use with exit node if you also want DNS to work when an exit node is active.
Click Save.

At this point, most devices should automatically start using Pi-hole for DNS resolution.

Accept DNS and subnet routes on Linux clients

In practice, I found that some Linux machines picked up the new DNS configuration immediately, while others didn’t. I haven’t dug deeply into why this happens, but the fix was simple.

On the affected machines, explicitly tell Tailscale to accept both DNS settings and subnet routes:

tailscale set --accept-routes
tailscale set --accept-dns

After running these commands, DNS resolution started flowing through Pi-hole as expected.

Result

That’s really all there is to it. Every device in my Tailnet now uses Pi-hole for DNS, regardless of location, without forcing all traffic through an exit node. This gives me ad blocking, internal name resolution, and consistent DNS behaviour everywhere, while keeping latency and bandwidth usage to a minimum.

Comments

Join the conversation on the Fediverse.

Configuring a Custom Block Page for Pi-hole

Mon, 17 Nov 2025 06:15:00 +0000

Configuring a Custom Block Page for Pi-hole

I recently installed Pi-hole on my home network. I share my home with a few people, not all of whom are particularly tech-savvy. So I wanted a block page to appear whenever a domain is blocked, helping users understand what’s happening and what to do if they want a domain unblocked.

Pi-hole used to support a custom block page, but the feature was removed a few years ago because widespread HTTPS adoption made it less useful. They’re not wrong: a custom block page served by Pi-hole will trigger a certificate warning before users see the page.

I accept this limitation - but, as a Brit, I’ll counter that “every little helps,” and it’s still better than nothing. Enabling a custom block page is actually quite straightforward, and I wanted to write down the steps here for my own notes.

Create the Block Page HTML

I cheated a little and asked Claude AI to generate the HTML for me. You can view the source at gist.thms.uk/michael/pi-hole-block-page.
It’s straightforward, and you can adjust it as needed - for example, you probably don’t want your users to “Contact Michael” if they have questions.

Here’s what it looks like. It’s loosely based on Pi-hole’s default theme and colours:

You will need to place two copies of this file on your server:

One copy needs to go to /var/www/html/index.html. This file will be served if a user visits the root domain.
One copy needs to go to /var/www/html/error404.html. This file will be served if a user visits any other URL on the blocked domain.

Make sure both files are readable by the pihole user.

Enable the Custom Block Page

In order to enable the block page you need to change the DNS blockign mode:

SSH into your server and open /etc/pihole/pihole.toml.
Search for [dns.blocking] and find the mode setting. Change it to:
mode = "IP"
Search for [webserver] and find the advancedOpts settings. Change it to advancedOpts = [ "error_pages=/var/www/html/" ] (if you already have any values in there, make sure you don’t remove them, but rather append to the array of options.)
Restart Pi-hole:
sudo service pihole-FTL restart

And that’s it. You may want to visit a blocked domain (such as http://adclick.g.doubleclick.net) to confirm that it’s working.

Comments

Join the conversation on the Fediverse.

Seeing the Full Conversation: Fetching Replies on Mastodon

Mon, 21 Jul 2025 06:15:00 +0000

Seeing the Full Conversation: Fetching Replies on Mastodon

One of Mastodon’s biggest shortcomings is how it handles fetching replies to posts. This isn’t unique to Mastodon (it’s a limitation shared across much of the fediverse) but since I access the fediverse through Mastodon, that’s what I’ll focus on here.

The issue arises when I come across a post from a user on a different instance than my own. Since I run a single-user instance, every post I see is from another instance - and without taking extra steps, I can’t see the replies.

This happens because Mastodon primarily fetches content from users (and hashtags) that you - or someone else on your server - already follow. (This is a simplification, but it captures the core idea.)

This limitation has a few negative side effects:

It kills the flow of conversations.
It leads to reply duplication - I might unknowingly post the same reply as someone else, which can be frustrating for the original poster.
It makes Mastodon feel more fragmented than it needs to be.

In this post, I’ll outline a few ways you can work around this and see more replies to posts on your Mastodon instance.

1. Viewing Posts on Their Original Instance

This is the most straightforward and reliable method. Mastodon’s web interface has an “Open original page” option for any post, which opens the post on the author’s own instance. You’ll then be able to see all the replies there.

Most third-party apps offer similar functionality.

Pros:

Always works
Requires no setup

Cons:

Cumbersome to constantly open external links
Breaks the “stay in one app” experience

Still, if you just want to catch up on a conversation, this method is the only bulletproof one.

2. Using FediFetcher

I wrote this tool myself, so take this with a grain of salt - but I genuinely find it invaluable.

FediFetcher scans your home feed and proactively pulls in missing replies, injecting them into your instance. That way, when you open posts in your own timeline, the replies are already there. (FediFetcher can do a lot more, but that’s for another time.)

Pros:

Makes conversations more complete
Keeps you within your own Mastodon instance

Cons:

Doesn’t work with all remote servers (e.g., GoToSocial, Threads)
Requires setting up and running external software
Increases load on your server and others, as it scans many posts regularly

If you’re technically inclined and willing to run a small background service, this is a powerful option.

3. Using a Browser Extension

Substitoot is a browser extension (for Chrome, Firefox, and compatible browsers) that fetches remote replies when you open a post.

Pros:

Easy to install and use
Works in real time as you browse

Cons:

Only works in supported browsers
Doesn’t help if you use mobile apps or unsupported browsers (like Safari)

If you primarily use Mastodon through a desktop browser, this can be a simple, no-fuss solution.

4. Letting Mastodon Handle It

As of version 4.4, Mastodon includes an experimental option to fetch replies automatically. Admins can enable this in the instance’s configuration (via the .env.production file - see Fetch All Replies Documentation for details).

Unfortunately, this feature is opt-in, and there’s no way for end users to tell if their instance has it enabled, aside from asking their admin.

Maybe most importantly it really isn’t something that users can control: Their instance either has it enabled or not.

Pros:

Built-in, efficient, and seamless for users
No third-party tools required

Cons:

Not enabled by default
Some admins may worry about performance or storage overhead
Lack of visibility or control for end users

Long-term, I think this is the most sustainable and user-friendly solution. But awareness and adoption are currently lacking.

In Summary

Method	Pros	Cons
Open original page	Reliable, no setup	Interrupts workflow
FediFetcher	Powerful, automated	Needs setup, increases load, won’t work for all posts
Substitoot	Easy for browser users	Limited to desktop browsers
Mastodon 4.4+ reply fetch	Seamless, efficient	Opt-in by server admin, cannot be enabled by ’normal’ users

Until Mastodon adopts a more unified and user-centric approach to fetching replies, these workarounds can help fill the gap. Hopefully, as more users and admins understand the issue, we’ll see better adoption and wider availability of replies.

Comments

Join the conversation on the Fediverse.

Upgrading Mastodon from PostgreSQL 15 to PostgreSQL 17

Fri, 06 Jun 2025 06:15:00 +0000

Upgrading Mastodon from PostgreSQL 15 to PostgreSQL 17

I recently upgraded my Mastodon Ubuntu host from Ubuntu 22.04 to 24.04 and noticed that this comes with PostgreSQL 17 installed side-by-side with version 15.

So I thought I’d actually make use of PostgreSQL 17, since I already got it installed.

Backup!

Firstly, take a backup. Always a good idea. In my case I took a snapshot through the Hetzner console, because I host my instance on a Hetzner VPS.

Upgrade PostgreSQL 15 to 17

We start the update by stopping all mastodon services, to ensure that there are no writes to the DB during the process, and thus reduce the risk of errors:

systemctl stop mastodon-sidekiq
systemctl stop mastodon-streaming
systemctl stop mastodon-web

In my case the PostgreSQL 17 cluster was already running, so I first had to stop it. You can confirm this by looking at the output of pg_lsclusters:

$ pg_lsclusters
Ver Cluster Port Status Owner Data directory Log file
15 main 5432 online postgres /var/lib/postgresql/15/main /var/log/postgresql/postgresql-15-main.log
17 main 5433 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17-main.log

As you can see both versions 15 and 17 are running, so lets stop version 17:

pg_dropcluster 17 main --stop

Confirm that only the PostgreSQL 15 cluster is now running:

$ pg_lsclusters
Ver Cluster Port Status Owner Data directory Log file
15 main 5432 online postgres /var/lib/postgresql/15/main /var/log/postgresql/postgresql-15-main.log

Finally, it’s time for the actual upgrade. PostgreSQL offers the pg_upgrade tool, which on Ubuntu is wrapped in pg_upgradecluster.

By default this will pg_dump your database to disk from version 15, then pg_restore it into version 17. That means you need a lot fo free disk space, which I don’t have on my system. (It’s also pretty slow,but that was less of a concern for me.) Thankfully pg_upgradecluster gives us the option to upgrade the existing files and simply place a hard link. To quote from the docs:

If you use link mode, the upgrade will be much faster (no file copying) and use less disk space, but you will not be able to access your old cluster once you start the new cluster after the upgrade. Link mode also requires that the old and new cluster data directories be in the same file system. (Tablespaces and pg_wal can be on different file systems.)

I’m fine with these drawback, so I’m using link mode. The command to run in order to upgrade using link mode is:

pg_upgradecluster -m link 15 main

This took about a minute in my case, so it was very quick. This will crucially also copy your database config files, so it will make sure that the PostgreSQL 17 cluster is now running on the same port as the version 15 cluster was running previously. This can again by confirmed by running pg_lsclusters:

$ pg_lsclusters
Ver Cluster Port Status Owner Data directory Log file
15 main 5433 online postgres /var/lib/postgresql/15/main /var/log/postgresql/postgresql-15-main.log
17 main 5432 online postgres /var/lib/postgresql/17/main /var/log/postgresql/postgresql-17-main.log

Note the swapped ports.

At this stage we can bring our mastodon services back online:

systemctl start mastodon-sidekiq
systemctl start mastodon-streaming
systemctl start mastodon-web

You can now navigate to the Mastodon admin dashboard on your instance at /admin/dashboard and at the bottom it should show you are using PostgreSQL 17 now.

Tidying up

Once you have verified that this is all working, you can do some tidy up. First drop the PostgreSQL 15 cluster:

pg_dropcluster 15 main

Then remove the PostgreSQL 15 packages:

apt remove postgresql-15 postgresql-client-15

Summary

Really, these are a lot of words to say: Upgrading your PostgreSQL 15 cluster to PostgreSQL is very simple, if you are hosting your Mastodon instance on Ubuntu. The actual upgrade boils down to just two commands:

pg_dropcluster 17 main --stop
pg_upgradecluster -m link 15 main

It’s really quick too, taking just about a minute on my database.

Comments

Join the conversation on the Fediverse.

OpenAI's crawler is overriding your Sentry sampling rate

Tue, 06 May 2025 06:15:00 +0000

OpenAI’s crawler is overriding your Sentry sampling rate

This is one of those ‘I cannot believe it!’ moments:

I have been debugging for days why Sentry would use up all our transaction spans. I had reduced our traces_sampler rate from 0.1 to 0.01 to 0.00001, and seen no difference in the consumption of spans, so this told me that Sentry was ignoring what we gave them.

Strange! Well, I finally opened a ticket, and Sentry (kudos to their support team! They gave a human, helpful answer within 2 hours!) provided a good pointer:

I checked one of your transactions and noticed that it has the following header in the incoming request:
Traceparent 00-[redacted]-01
The header tells the transaction should be sampled and takes preference over the sample rate you set in your SDK configuration to keep the trace consistent. Are you using tracing with other libraries/OTEL?

Huh, strange. As far as I know we aren’t using any other tracing library. Where could this come from?

To be sure, I checked our CloudFlare configuration, and found nothing, so I decided to log incoming request headers from nginx. Honestly, at this stage I was absolutely convinced Sentry had sent me on a wild goose chase.

I watched my logs in real time for a few minutes and saw no traceparent headers come in.

Whenever I hit a point where I don’t know what to do, I make a coffee (or another drink), because I’ve long learned that I get my best revelations when I’m away from the screen/problem. So off I go for my coffee.

This time, the coffee machine offered no enlightenment. But when I came back a few minutes later - log tail still running - I saw it: traceparent headers lighting up the screen.

Here’s one (IDs redacted, just in case):

GET /
Host: example.com
Connection: close
cf-ray: [redacted]
cdn-loop: cloudflare; loops=1
tracestate: dd=p:[redacted];s:2;t.dm:-4;t.tid:[redacted]
x-forwarded-for: 68.221.75.25
accept-encoding: gzip, br
x-request-id: [redacted]
x-forwarded-proto: https
x-openai-internal-caller: browse
x-openai-product-sku: unknown
cf-visitor: {"scheme":"https"}
cf-ipcountry: ES
x-openai-originator-env: prod
cf-connecting-ip: 68.221.75.25
x-openai-originator: browse
x-openai-traffic-source: user
x-envoy-expected-rq-timeout-ms: 15000
x-datadog-origin: rum
user-agent: Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; ChatGPT-User/1.0; +https://openai.com/bot
accept-language: en-US,en;q=0.9
accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9
x-datadog-trace-id: [redacted]
x-datadog-parent-id: [redacted]
x-datadog-sampling-priority: 2
x-datadog-tags: _dd.p.tid=[redacted],_dd.p.dm=-4
traceparent: 00-[redacted]-01

It appears as though OpenAI’s crawler sets tracing headers on every request it makes. Every tracing library it touches dutifully obeys, samples the trace, and bills the site owner for the privilege. I doubt it’s deliberate. It’s just the kind of thing that happens when you crawl the entire web with production defaults switched on.

Comments

Join the conversation on the Fediverse.

blog.thms.uk

Reducing Docker deploy downtime for Laravel and FrankenPHP

Reducing Docker deploy downtime for Laravel and FrankenPHP

What was actually happening

Fix 1: Bake everything that doesn’t depend on the environment into the image

The gotcha that caught me out the first time

Fix 2: Do the volume setup once, not four times

Fix 3: Deploying in stages

The trade-off

Takeaway

Comments

When restart: always isn't enough: making Compose stacks recover at boot

When restart: always isn’t enough: making Compose stacks recover at boot

The problem

Chasing the cause

One dead end worth flagging

The solution

Making the solution permanent

Wrapping up

Comments

Exempting an IP from Mastodon's rate limits

Exempting an IP from Mastodon’s rate limits

Confirming the IP address Rack::Attack actually sees

Safelist the IP

Security

Comments

Setting up OIDC for Mastodon with Pocket ID

Setting up OIDC for Mastodon with Pocket ID

OIDC provider setup

Mastodon setup

Switching to OIDC

Comments

TIL: MySQL view security context after a migration

TIL: MySQL view security context after a migration

Comments

Everything I self-host (and a few things I don't)

Everything I self-host (and a few things I don’t)

General philosophy

Static sites

Infrastructure

Monitoring

Coding

Nextcloud helpers

Reading and Social

Others

What I’m not (yet) self-hosting

Wrapping up

Comments

Self-hosting a static site using Forgejo, Headscale, and Caddy

Self-hosting a static site using Forgejo, Headscale, and Caddy

Set up the host machine

Set up Headscale

Create your deployment script

Configure Caddy

Wrapping up

Post scriptum

Comments

Using a Tailscale exit node on a Docker host

Using a Tailscale exit node on a Docker host

The problem

The solution

Making the solution permanent

Wrapping up

Comments

Moving Mastodon to Docker Compose

Moving Mastodon to Docker Compose

Inventory current setup

Get docker compose file

Migrate config

Pull images so they are ready

Migrate data

Bring up new server

Wrapping up

Postscript

Comments

A multi-stage Dockerfile for Laravel and FrankenPHP

A multi-stage Dockerfile for Laravel and FrankenPHP

Starting point: What do I need?

Architecture

The Dockerfile

But ChatGPT can’t handle `text/markdown`

Investigating the performance of Laravel’s `whereIn` vs `whereIntegerInRaw`