Zero-Downtime Deploys on a Raspberry Pi

People think zero-downtime deployment is something you buy. Kubernetes, a managed platform, a cloud bill that grows every month. I run it on a Raspberry Pi sitting on my desk, and it costs nothing.

Yes, a managed platform gives you this out of the box, and if you run a company, take the box. But that is not the point. The point is that when you rent the magic, you never learn the trick. The trick turned out to be small enough to fit on a 4GB board.

The Problem Is the Restart

Every simple deploy has the same hole in it. You stop the old version, you start the new one, and between those two moments your site is down. Usually seconds. Sometimes, when the new build is broken, much longer, because now you are debugging in production with nothing running.

Worse: you find out the build is broken after you killed the working one. The old version was fine. You deleted your only good copy to make room for a bad one.

So the real requirement is not speed. It is order. The new version must be up, healthy, and proven before the old one goes anywhere.

A Deploy Is One Moved Pointer

Here is the whole system. Every project on the Pi runs in one of two slots, called x and y. Only one slot is live. The live slot holds a Docker network alias, a name like mycvpath-active, and the Cloudflare tunnel that faces the internet points at that alias. Not at a container. At the name.

That one level of indirection is the entire trick.

A deploy then works like this:

• Build the new version in the idle slot, while the live slot keeps serving
• Health-check the new slot until it proves it is actually up
• Move the alias from the old slot to the new one
• Tear down the old slot

The public hostname never changes. The tunnel configuration never changes. Traffic follows the name, and the name moves in one atomic step. If the new build fails its health check, nothing moves, and the failure costs you nothing: the old version never stopped serving.

The Rules That Keep It Boring

The pattern is simple. Keeping it simple took a few scars.

Never deploy by hand. Running docker compose up directly skips the alias swap. The tunnel then points at a name nobody holds, and the site returns 502 while every container is technically running. One script does the deploy, always the same way, or the guarantee is gone.

State never lives in a slot. Slots are disposable by design, so a database inside one gets destroyed with it. Named external volumes, created once, shared by both slots. I learned this the sharp way: a compose file run from the wrong folder quietly created a second, empty volume, and the app came up with a blank database while the real data sat one name away. The fix is to make volume names literal and external, so there is exactly one truth for the data no matter where the deploy runs from.

A health check must prove the thing you care about. Checking that a port is open proves the process started. It does not prove the app can serve a page. Each project's check matches what its image can actually answer, because a green check that tests nothing is worse than no check: it moves the alias onto a corpse.

What the Pi Taught Me

The lesson was never about Raspberry Pis. It is that the distance between "hobby setup" and "production pattern" is smaller than the pricing pages want you to believe. Blue-green deployment sounds like enterprise architecture. Stripped to its core, it is two folders and a name that moves.

Constraints did the teaching. On a small board with no budget, I could not buy my way past the problem, so I had to understand it. Now, when a managed platform advertises zero-downtime deploys, I know exactly what I am being sold: one moved pointer, wrapped in a subscription.

Rent it when your time is worth more than the lesson. But learn it once on hardware you own, because the engineer who knows the trick can always tell when the magic is overpriced.