This post is the other order. The service keeps running on the machine it was built on, and a Cloudflare Tunnel gives it a public HTTPS hostname. Nothing on the laptop listens to the internet: no port forwarding, no router settings, no exposed IP address. The machine dials out to Cloudflare, and Cloudflare sends requests back down that connection. The tunnel is free, and the TLS certificate, DDoS protection and caching come with the Cloudflare zone you probably already have.

The example is real. One of my products runs on Fly.io, and its mobile app gets over-the-air JavaScript updates from the backend (self-hosted Expo Updates). I wanted a second copy of that update server running on my Mac for development builds, with production left exactly as it was. The outputs below are from that afternoon, including the part where it didn’t work.

What a Cloudflare Tunnel actually is

#

A normal server waits for connections. To reach a laptop from the internet, you’d have to open a port on your router, forward it to the laptop, and hope your ISP gives you a public IPv4 address (in a lot of places, mine included, it doesn’t). Then everything listening on that port is reachable by every scanner on the internet, all day.

A tunnel turns that around. cloudflared runs next to your app and opens outbound connections to Cloudflare’s edge, four of them to two nearby data centres. A DNS record in your zone points a hostname at the tunnel. When a request arrives for that hostname, Cloudflare terminates TLS and forwards the request down one of those connections. cloudflared then hands it to whichever local service your config names.

For security, the important part is that your router has no inbound rule and your IP address never appears in DNS. Someone scanning your home connection finds nothing, because nothing on it is listening.

Setting up cloudflared, start to finish

#

You need a domain on Cloudflare (the free plan is enough) and cloudflared installed (brew install cloudflared on a Mac).

1. Log in once. This opens a browser, you pick the zone, and it saves a certificate that lets this machine create tunnels and DNS records in that zone:

cloudflared tunnel login

2. Create the tunnel. I keep everything for this project in its own folder, because the credentials file is the tunnel’s identity: anyone who has it can serve traffic for your hostnames.

mkdir -p ~/.cloudflared/myapp && cd ~/.cloudflared/myapp
cloudflared tunnel create --credentials-file ./creds.json myapp-local
chmod 600 creds.json

Tunnel credentials written to ./creds.json. Keep this file secret. To revoke these credentials, delete the tunnel.
Created tunnel myapp-local with id 1ade030c-…

3. Point hostnames at it. One command per hostname creates a proxied CNAME to <tunnel-id>.cfargotunnel.com:

cloudflared tunnel route dns myapp-local ota.example.com
cloudflared tunnel route dns myapp-local checkin-local.example.com

4. Write the ingress rules. This is the part that matters for security, so it gets its own section below.

5. Run it. My app already runs under Docker Compose, so cloudflared is one more container on the same network. It reaches the app by service name, and the app doesn’t need a port published on the host at all:

# compose.tunnel.yml, used alongside the project's docker-compose.yml
services:
  cloudflared:
    image: cloudflare/cloudflared:2026.10.7
    command: tunnel --config /etc/cloudflared/config.yml run
    volumes:
      - ${HOME}/.cloudflared/myapp:/etc/cloudflared:ro
    restart: unless-stopped
    depends_on: [api, edge]

docker compose -f docker-compose.yml -f ~/.cloudflared/myapp/compose.tunnel.yml up -d cloudflared

INF Registered tunnel connection connIndex=0 … location=icn06 protocol=quic
INF Registered tunnel connection connIndex=1 … location=icn07 protocol=quic
INF Registered tunnel connection connIndex=2 … location=icn07 protocol=quic
INF Registered tunnel connection connIndex=3 … location=icn06 protocol=quic

Four connections to Seoul, and the laptop is on the internet, from the outside in. restart: unless-stopped brings it back after a reboot as soon as Docker starts.

Expose paths, not servers

#

This is the mistake I nearly made, and I’d guess it’s the most common one. The easy config is a single line: hostname → http://localhost:8000. That publishes the whole development server.

Development servers aren’t built for that. Mine runs with DEBUG=True, which shows full tracebacks and settings on any error. It also runs with authentication switched off (AUTH_MODE=disabled), so that any bearer token logs you in as a test user. That’s exactly right on localhost and a disaster on a public hostname. Yours probably has something similar: an admin with a default password, a seeding endpoint, a debug toolbar, or an API that trusts its caller because only you ever call it.

So the tunnel config is an allowlist. cloudflared checks each request against the ingress rules in order, by hostname and by a regular expression on the path. The first match wins, and the last rule catches everything else:

tunnel: myapp-local
credentials-file: /etc/cloudflared/creds.json

ingress:
  # OTA: the two read-only endpoints the phone calls, and the files they link.
  - hostname: ota.example.com
    path: ^/api/expo-updates/(manifest|status)/$
    service: http://api:8000
  - hostname: ota.example.com
    path: ^/media/
    service: http://api:8000
  # Device check-ins, authenticated by each device's own key.
  - hostname: checkin-local.example.com
    path: ^/c/$
    service: http://edge:8081
  # Everything else, including /admin/ and the publish endpoint: 404 at the edge.
  - service: http_status:404

The publishing endpoint lives on the same server under the same prefix (/api/expo-updates/import-update/), and it isn’t in the list. Neither is the admin, or the rest of the API. Those requests never leave Cloudflare.

You don’t have to trust your regexes; cloudflared will tell you which rule a URL matches:

cloudflared tunnel --config config.yml ingress rule https://ota.example.com/admin/

https://ota.example.com/api/expo-updates/manifest/        service: http://api:8000
https://ota.example.com/api/expo-updates/import-update/   service: http_status:404
https://ota.example.com/admin/                            service: http_status:404
https://ota.example.com/media/expo-updates/x.js           service: http://api:8000
https://checkin-local.example.com/c/                      service: http://edge:8081
https://checkin-local.example.com/health                  service: http_status:404

I’d put that check in a script and run it every time the config changes. It takes seconds, and a regex that matches more than you meant is the kind of mistake you only find out about from someone else.

Two more rules of thumb:

• What you expose should authenticate itself. The OTA endpoints serve public, read-only data. Device check-ins are signed with per-device keys. Neither one depends on the network to keep it safe. If you want to show someone a page that has no login, put Cloudflare Access in front of that hostname (free for up to 50 users) instead of building a login.
• Don’t run the tunnel as a background part of your dev workflow. Run it on purpose, for the hostname you mean, and stop it when you’re done. docker compose stop cloudflared takes everything off the internet in one command.

The redirect that ate my hostnames

#

With the tunnel connected and the rules verified, I tried it from outside:

https://ota.example.com/api/expo-updates/status/?…   301
https://ota.example.com/api/expo-updates/manifest/   301
https://ota.example.com/admin/                       301
https://checkin-local.example.com/c/                 301

Every path returned the same 301, including ones the tunnel should have answered with 404. That means the request never reached cloudflared. The Location header said https://www.example.com/, and the server: cloudflare header settled it: Cloudflare was answering on its own.

I’d done this to myself. Months ago I added a zone-level redirect rule, “any other subdomain → www”, as a sinkhole for scanners that walk invented subdomains. Redirect rules run in Cloudflare’s request pipeline before the request is sent to the origin, and a tunnel is just an origin. The same rule caught my preview environments before Workers could see them. The fix is the same as last time: one more exception in the rule’s expression.

… and not http.host in {"ota.example.com" "checkin-local.example.com"}

If your tunnel hostname answers with a redirect or an error page from Cloudflare instead of your app, check Rules → Redirect Rules, Page Rules and any WAF custom rules for the zone before you debug the tunnel. cloudflared logs every request it forwards, so an empty log means the request never got that far.

What it can’t do

#

• UDP from the public internet. Public tunnel hostnames carry HTTP(S) (plus WebSockets and gRPC). My product’s devices normally check in over CoAP on UDP, and that can’t go through a tunnel; the devices on the local copy fall back to HTTPS check-ins, which cost them a few seconds on each one. If your idea is a game server or VoIP, a tunnel isn’t the tool.
• Uptime. It’s your laptop. Close the lid and the site is down; Cloudflare shows a 530 error page. That’s fine for a demo, a beta with ten people, or a staging copy. It isn’t fine for anything someone depends on.
• Things baked into a build. A mobile app’s update URL is native config, so only builds made with the tunnel’s URL use it. My store builds keep talking to production, and that’s why this setup was safe to try.

The cost: is Cloudflare Tunnel free?

#

A Cloudflare zone on the free plan, the tunnel, its certificate, and the DNS records: $0. The machine was already running. The only real cost is that you’re now the uptime team.

What it saves you is the phase between “it works on my machine” and “it’s worth paying to host”. You can send a link to a tester, a designer or a first customer the same afternoon. If nobody cares, you’ve lost nothing. If they do, moving to a real host is one change: point the CNAME somewhere else.

Disclosure. Codemagic paid me to do this migration and write about it. They get a review pass for factual accuracy, not for tone, and nothing here was changed at their request. Where I hit a problem and reported it, I say so; if it’s fixed by the time you read this, it’s described as fixed.

Update, 23 September 2026. Codemagic’s developers have worked through the issues I reported. Most are now fixed, including the iOS version-detection bug, the double-counted installs, the silent first run and the noisy debug command, and the docs now cover committed native projects and the crash-rollback budget. I’ve marked each one below where it comes up, and left the few that are still open as they were.

Update, 16 October 2026. The first native upgrade since moving to Patch (Expo SDK 58) built an Android release with no Patch configuration in it, and nothing reported an error. What happened and the one-file fix are in The first native upgrade.

In February I wrote about building my own Expo update server. It still works. maru, the community app I run, has taken every over-the-air fix through it since, on both platforms, for about a dollar a month.

It also means I own every piece of it: the database tables, the API endpoint, an admin command, a publish script, a shared secret, and a set of gotchas I learned one broken update at a time. When I sat down to plan this, I found that the script had been printing “Sent 0 push notifications” after every production publish since the day I wrote it, reading a field this server has never returned. Nobody noticed, least of all me. That’s roughly what running your own thing turns into.

So when Codemagic asked whether I’d try Patch, their open-source, self-hostable take on CodePush, I agreed on one condition: a real app rather than a demo. Real signing, real release process, committed native projects with hand edits in them, the lot. Most people moving off EAS Update are moving an app like that, not a fresh template.

This is how that went, with the rough edges left in.

What Patch is

#

Patch is a server you run yourself and an SDK you put in your app. The server side is an API, a background worker, Postgres, S3-compatible object storage and a web dashboard, shipped as a Docker Compose stack. The client side is @codemagic/react-native-patch, a TurboModule for iOS and Android with an Expo config plugin, plus a CLI, cmpatch, that bundles your JavaScript and publishes it.

Two design decisions stood out once I’d read the source.

The first is that the app never asks the API whether there’s an update. When a release is published, the worker writes plain JSON manifests into object storage, and the app just fetches those. An update check is two static GETs against storage or a CDN; the API only receives metrics. My old endpoint was on the request path of every app launch. This one can’t be.

The second is that every release names the exact binary version it’s for, and the CLI computes a fingerprint of your native project and refuses to publish JavaScript onto a binary whose native code doesn’t match. My server had a version string and a lot of hoping.

Trying it on my laptop first

#

The docs start you on a local evaluation stack, and that’s the right place to start.

npm install -g @codemagic/patch-cli
cmpatch selfhost local-eval up

The CLI installed in two seconds. The stack took 3 minutes 14 seconds the first time, most of it building the server and dashboard images locally, and in non-interactive mode it prints nothing at all while it does that, which looks exactly like a hang. (Since fixed: it now prints one progress line per step.) Then four healthy containers appeared, all bound to localhost: the dashboard on 8080, the API on 3000, Postgres, and MinIO on 9100. It sensibly avoided the ports my own stack was already using.

Sign-in is disabled in this mode, with a warning on every page not to expose it.

localhost:8080

The stack comes seeded with an app called Example Data, which is worth a look before you’ve published anything, because it shows what the dashboard is for. The numbers in the next two screenshots are that seed data, not real users.

localhost:8080

localhost:8080

For comparison, my dashboard was an admin list of updates with an “active” checkbox. I had no idea how many phones had actually taken an update.

Logging the CLI in is a proper browser flow with PKCE and a localhost callback, and the approval page tells you which account is asking and that the code expires in about a minute.

localhost:8080

Pointing it at a real app

#

Patch wants one app per platform, each with a Staging and a Production deployment created for you. I made maru-ios in the dashboard and maru-android with cmpatch app create, mostly to see both. The dialog you get after creating an app is the most useful screen in the product for a migration: both deployment keys, the two URLs the SDK needs, and a note that deployment keys aren’t secrets.

localhost:8080

Two small things. cmpatch init linked a project to apps that already existed, so it couldn’t be the first command, whatever the migration guide implied. That’s since been fixed: in interactive mode it now creates one app per platform itself. And the dialog gives the API URL as http://localhost:8080 while the docs and the CLI say 3000. Both work, because each port serves both, but you’ll wonder.

Then I ran cmpatch doctor against the untouched app, and it found a real problem in three seconds. It reported the iOS binary version as 2.0.0. The app is 2.5.1.

The CLI finds every Info.plist under ios/ and, if none has “test” in its path, takes the first alphabetically. maru has a WidgetKit extension whose folder sorts before the app’s own, so the CLI picked the extension’s Info.plist. That plist was stale at 2.0.0, which is my bug, but the effect is nasty: auto-detection would target every iOS release at a version no phone runs, and nothing would error. Updates would just never arrive, which is exactly the failure I warned about in my self-hosting post. Android read versionName correctly. The workaround is to pass --target-binary-version or --plist-file, and my publish script now passes the version explicitly after checking that app.config.js and both native projects agree. Later, the same bug made doctor’s own manifest check fail against a deployment that was working fine, because it went looking for version 2.0.0’s manifest. Once I’d fixed my stale plist, doctor passed all 24 checks.

Codemagic has since fixed this. The CLI now reads the version from the app target’s Info.plist, not an extension’s, and if more than one target could be the app, cmpatch asks you which.

The JavaScript side

#

Removing expo-updates and adding the SDK is a two-line change. Replacing what the app did with updates took more thought.

maru checks for updates on launch and whenever it comes back to the foreground, at most every fifteen minutes. If it finds one, it downloads it, and offers to restart; say no and it applies on the next cold start. There’s also a manual check in Settings that shows which bundle you’re running, and the error reporter tags every report with the update it came from.

The first thing I learned from the SDK source is that it looks up its native module at import time with TurboModuleRegistry.getEnforcing, which throws if the module isn’t there. maru also ships a web build, and a top-level import would take the web app down. So everything goes through one small module that loads the SDK lazily, with a .web.ts twin that returns nothing, which also keeps the SDK out of the web bundle entirely.

// ota.ts (ota.web.ts exports a patchSdk() that always returns null)
import { Platform } from "react-native";

type PatchSdk = typeof import("@codemagic/react-native-patch");
let sdk: PatchSdk | null | undefined;

export function patchSdk(): PatchSdk | null {
  if (sdk !== undefined) return sdk;
  if (Platform.OS === "web") return (sdk = null);
  try {
    sdk = require("@codemagic/react-native-patch") as PatchSdk;
  } catch {
    sdk = null;
  }
  return sdk;
}

The automatic check itself is mostly sync(), which never throws and resolves to a status:

const status = await patch.sync({
  installMode: "ON_NEXT_RESTART",
  mandatoryInstallMode: "ON_NEXT_RESUME",
});
if (status === "update-installed") offerRestart();

The SDK’s default for mandatory releases is IMMEDIATE, which reloads the JavaScript wherever the user happens to be. I changed it to apply the next time the app comes back from the background, because losing a half-written post is a worse bug than most fixes are good. At the time, InstallMode was a string union, not the enum object the docs’ examples suggested; it’s now exported as a constants object, so InstallMode.ON_NEXT_RESTART works as documented.

The native side, when you commit ios/ and android/

#

The migration guide says to run npx expo prebuild --clean after adding the config plugin. I ran it in a separate checkout and it deleted bundled images, my Android network security config, the iOS privacy manifest and Podfile.lock, and reverted a test-runner fix in build.gradle along with a few hundred lines of Info.plist. Without --clean, Expo cleared both directories anyway.

This isn’t Patch’s fault. maru started as a managed Expo app and grew native customisations, so ios/ and android/ are committed and EAS builds them as they are. But plenty of apps look like that, and the guide didn’t warn you. It does now: the Expo migration guide has two paths, prebuild for generated native projects and the exact hand-applied changes for committed ones.

What the plugin actually changes turns out to be small enough to do by hand. On iOS, one import and one line in AppDelegate.swift:

return CodemagicPatch.bundleURL() ?? Bundle.main.url(forResource: "main", withExtension: "jsbundle")

On Android, one import and one argument in MainApplication.kt (this is the React Native 0.82+ shape; older versions override getJSBundleFile() instead):

ExpoReactHostFactory.getDefaultReactHost(
  jsBundleFilePath = CodemagicPatch.getJSBundleFile(applicationContext),
  // ...

Plus three config values per platform and the removal of the old expo-updates settings: 13 lines added and 20 removed across both projects.

The plugin writes those config values as literals at prebuild time, which, with committed native projects, would mean one hard-coded deployment for every build. I wanted preview builds on Staging and store builds on Production from the same project, so the values come from the build environment instead. In Info.plist, Xcode expands build settings:

<key>CodemagicPatchDeploymentKey</key>
<string>$(PATCH_IOS_DEPLOYMENT_KEY)</string>

And in android/app/build.gradle:

def patchEnv = { name -> System.getenv(name) ?: (findProperty(name) ?: "") }
resValue "string", "CodemagicPatchDeploymentKey", patchEnv("PATCH_ANDROID_DEPLOYMENT_KEY")

The keys then sit in each eas.json build profile next to the EXPO_PUBLIC_ values. An empty value means the SDK quietly does nothing, which is fine for a local build and a disaster for a store build, so app.config.js now throws if a preview or production EAS build is missing them or still points at localhost.

The first update

#

For the first release I changed the onboarding headline, which you can see without signing in, and published it:

./scripts/publish-update.sh ios --notes "Onboarding headline over the air"

That took 30 seconds, most of it Metro and Hermes. The server’s worker published the manifest 0.6 seconds after the upload finished. The update is a 7.3 MB compressed tarball, against the 11 MB Hermes bundle plus assets my old export produced.

One thing to get right here: the JavaScript bundle inlines your EXPO_PUBLIC_ values when it’s built, so an update has to be built with the same values as the binary it lands on, or you ship JavaScript that talks to the wrong backend. My script loads them from the same eas.json profile that built the binary. Patch’s CI docs now spell this out too, along with the fact that release-react doesn’t read EAS profiles itself.

Then I relaunched the app. The device log showed the whole update check as two requests to object storage, meta.json and 2.5.1/manifest.json. The SDK wrote a Downloaded event three seconds after launch and staged the update, and the app offered a restart.

The bug was mine

#

Then I looked at the dashboard. One simulator had installed release v1, and it showed two successful installs and two active users.

localhost:8080

The SDK keeps its state and pending metric events as files in the app’s container, which made this easy to chase. There were two Success events with identical timestamps and different ids. My hook confirmed the running bundle with notifyAppReady() on mount, and then called sync() straight away, and sync() calls notifyAppReady() itself. The two calls overlapped, each saw the release as pending, and each recorded the events. The server de-duplicates on event id, but these had different ids, so both counted, and those duplicates are permanent.

The fix on my side was one shared confirmation per launch that everything else awaits. The SDK could also guard against overlapping calls itself, and I suggested that. It now does: overlapping notifyAppReady() calls, including the one inside sync(), share a single confirmation, so each install is recorded once. The SDK reference also now says that sync() confirms readiness itself, so an app that uses it doesn’t need to call notifyAppReady() separately.

The nice part was shipping the fix. It’s a JavaScript-only change, so it went out as release v2, and because a device on v1 can be sent a binary diff, v2 downloaded as a 543 KB patch instead of the 7.3 MB bundle, about 7% of the size. After the restart: one download, one install, one success, one active device.

localhost:8080

Breaking it on purpose

#

Rollback is the feature I cared about most, because my old setup had none on the device. A bad update would have crashed every launch until I noticed and un-ticked a checkbox.

So I released a v3 that throws before the first render, which means it can never call notifyAppReady(). The app downloaded it, offered a restart, and died to the home screen.

The next launch booted v3 again and crashed again, which surprised me, because the docs say a bundle that crashes before notifyAppReady() is rolled back. The source explains it: the SDK allows three unconfirmed launches before deciding it’s a crash, because one unconfirmed launch can just mean iOS killed a healthy process before any JavaScript ran. The fourth launch came back up on v2.

The device then reported the failure itself, as crash_rollback, and the dashboard showed it against v3. That’s a sensible design, but it’s worth being plain about what it means: a bad release costs each user three crashed launches before they recover, and at the time the docs didn’t mention the number. They do now, and the budget is configurable, with CodemagicPatchMaxLaunchAttempts natively or the Expo plugin’s maxLaunchAttempts. That’s the case for Staging first and a small Production rollout second.

Stopping a bad release for everyone else is one command, and it took under a second:

cmpatch release rollback --app maru-ios --deployment Staging

It doesn’t rewrite history. It publishes the previous release again as a new one (v4, marked as a rollback of v2), so the crashing release stays in the list with its failure count, which is the honest record. The dashboard does the same from a dialog.

localhost:8080

Android

#

Android had two surprises, neither Patch’s. The R8 keep rule I’d added for the SDK lived in app.config.js, which only reaches the native project through prebuild, so my first release build accidentally tested whether the SDK survives R8 without one. It does: R8 renamed all its classes, and updates downloaded, installed and rolled back fine. And the emulator, freshly cold-booted with Gradle still holding memory, was so slow that my first test gave up 45 seconds before the SDK finished the download it had already started.

Release v1 applied, with one success and one active device, and a crashing v2 rolled back after the same three-launch budget.

Past the happy path

#

Updates arriving and rolling back is the core of it, but a team lives in the other features, so I went through them one at a time.

Staged rollouts are deterministic, which I liked. A device is in if the first eight hex digits of md5(deviceId + "-" + releaseLabel), modulo 100, are below the rollout percentage, so the same phone stays in or out for a given release. I worked out that my simulator sat in bucket 91 for the next release, published it at 25%, and the simulator correctly got nothing. Raised to 95% with cmpatch release patch, which took under a second, it updated on the next launch.

Then my next release failed with a 409: “deployment has an active rollout below 100 percent”. Only one partial rollout per deployment is allowed, so you finish, disable or roll back a canary before shipping anything else. That’s reasonable, and documented, but a pipeline that publishes on every merge will run into it in the middle of a canary. Since I reported it, the CLI explains itself here: if an active partial rollout is blocking you, it says waiting won’t help and how to complete or disable the rollout, and if another release job is still running it tells you to wait with release inspect --wait. The docs now have a section on sequential release changes.

Mandatory releases use the SDK’s mandatoryInstallMode. With mine set to apply on the next resume, the app downloaded the update and showed its prompt, and when I ignored the prompt, sent the app to the background and brought it back, the new version was simply there.

Disabling a release does more than stop offering it. The moment I disabled the latest one, the manifests pointed at the newest release still enabled, and devices on the disabled one were offered a patch back to it. Disable everything for a binary version and the manifest’s target becomes null, and the SDK reverts the app to the bundle it shipped with. My update hook didn’t prompt for that case at first, so now it does.

Promoting from Staging to Production took under a second and reused the exact package that was tested, same hash and notes, rather than rebuilding it. It also accepts a rollout percentage, so “promote to 10% of Production” is one command.

Building and publishing can also be separate steps. cmpatch bundle produces a .cmpatch artifact, and the dashboard’s “Bundle upload” option reads it before uploading: platform, target version, fingerprint, signing status, size and bundler. That suits a setup where CI builds the artifact and someone else decides when to publish it.

That’s also where I ran into the fingerprint guard in earnest. After I fixed my stale widget plist, the server refused my next release with a 409, because the native project’s fingerprint no longer matched the one it had recorded for 2.5.1. On Android, editing a comment in app.config.js was enough, since Expo includes the app config in the fingerprint. The dashboard shows the same check as a warning with both fingerprints and an “Upload anyway” button. In both cases nothing native had changed on the installed binary, so overriding was right. In real use, though, the honest answer is nearly always a version bump and a store build, and my publish script now says exactly that when it happens.

Code signing is RS256: the CLI signs the package hash with an RSA private key, and the SDK checks it against a public key compiled into the binary. The key goes in as a single base64 line, which fit my build-setting approach, and I tested it on both platforms. With the key in the app, an unsigned release was refused before it downloaded. With “require code signing” turned on for the app, the server rejected an unsigned publish with an error that named the fix and linked the guide. A signed release installed, and the SDK recorded the signature as verified. It also refused an older unsigned release the server fell back to when I disabled the signed one. The catch is that the public key has to be in the first binary you ship, because an update can’t add it.

localhost:8080

Teams and CI are covered as well. Members get one of four team-wide roles (owner, admin, developer, viewer) and invitations wait until the person first signs in. Personal access tokens worked with an empty home directory, passed either as --token or through environment variables, and the token list shows when each was last used. I’ve also written a manually triggered CI workflow that runs the same publish script on a Linux runner with the signing key from a secret, though I haven’t run it yet, since it needs the hosted server.

One tool I’d have skipped at the time is cmpatch debug ios. It streamed the system log filtered on “OTA” case-insensitively, which matches “Rotation”, so a twenty-second app launch produced a screenful of SpringBoard messages and nothing from the app. That’s fixed: it now shows only lines carrying the SDK’s markers. The SDK doesn’t log much on its own, mostly errors and development-build warnings, so expect a quiet stream. The getpwuid_r warning you may see comes from xcrun simctl, not Patch.

How hard is it, really

#

Codemagic asked for my opinion, so here it is, as plainly as I can put it.

Trying it out is easy. Two commands, a few minutes, and you have the real server, a dashboard with demo data, and a CLI you can point at your own app. I’d rate it the best part of the first hour.

Integrating the SDK is moderate work, and most of the difficulty is in your own project rather than in Patch. On a fresh Expo app with generated native folders, it really is the plugin plus a few lines replacing expo-updates calls. On an app like maru, with committed native projects, a widget extension, a web build, R8 and build profiles, the work was in the edges. I had to apply the native changes by hand to avoid prebuild, make the configuration build-time so Staging and Production builds could differ, and keep the SDK away from web. I also had to make sure the JavaScript in an update was built with the same environment as the binary. None of it was hard once I understood it. When I did it most of that wasn’t in the docs, though the committed-native-projects path and the bundle-time environment now are.

Day-to-day use is good. Publishing is one command and about half a minute. Rollouts, promotion, disabling and rollback are all under a second from the CLI or the dashboard, and the errors say what went wrong and what to do. The server’s guards (the fingerprint check, one canary at a time, signing) are strict in ways that stopped me doing the wrong thing more than once.

Running it in production is the bigger commitment. It’s a Docker Compose stack with Postgres and object storage that you have to host, back up and upgrade, and it needs two domains and an OAuth app. For a team already running servers that’s a quiet afternoon. For a team on EAS precisely because they didn’t want servers, it’s the real cost of switching, more than the SDK work.

In wall-clock terms, I installed the CLI at 12:29 and had the first update applying on a simulator at 13:34, and half an hour of that was an Xcode build that stalled for reasons unrelated to Patch. Everything in this post, on both platforms, was done by mid-afternoon, not counting the hosted server.

The things that cost me the most time, in order: expo prebuild --clean wiping my committed native projects, and then working out how to wire everything by hand; the iOS version-detection bug, which would have sent updates to a version nobody runs; the double-counted installs, which were my own doing but easy for anyone to repeat, since sync() calls notifyAppReady() itself; and the undocumented three-launch crash budget, which surprised me halfway through a test. After those came things that are correct but need planning: the fingerprint guard firing after harmless native-adjacent edits, one canary at a time per deployment, and lifecycle jobs that can’t overlap, which matters as soon as a script does several things in a row. The rest was small: a silent first-run setup, a noisy debug command, and a few docs examples that didn’t match the code.

I wrote all of it up for Codemagic, with the details, and by 23 September most of it was fixed: the version detection, the overlapping confirmations, the prebuild warning, the crash budget, the silent setup, the debug command, the InstallMode examples, and the error you get when a release job or a canary is in the way. What’s still open is smaller: the dashboard showing the API on :8080 while everything else says :3000, the SDK throwing on import on web and in Jest, and a few docs gaps.

Going to production

#

Everything above ran against the evaluation stack. Production is the same app and the same scripts pointed at a real server, and this is the plan for maru.

The supported way to run the server is the Docker Compose install: a Linux machine with ports 80 and 443 open, two domains (one for the API and dashboard, one for downloads), and a GitHub OAuth app for sign-in, which the server won’t start without. The installer does the rest, including TLS:

scripts/selfhost/install.sh \
  --api-domain updates.example.com \
  --storage-domain storage.updates.example.com \
  --email you@example.com \
  --github-oauth-client-id <id> --github-oauth-client-secret <secret>

It writes a .env.selfhost with the database and storage secrets, which belongs in your password manager.

You don’t have to use the bundled database and storage, though, and that’s what makes it fit a stack like mine. maru’s API already runs on Fly.io and its files live on Tigris, and Patch works on both. Underneath the Compose file, the server is one container running in MODE=all (API and release worker together) that needs a Postgres database, S3-compatible storage and a public HTTPS URL for the files. That’s a Fly app built from the repository’s Dockerfile (there’s no published image yet, so fly deploy builds it), a Fly Postgres database, and a Tigris bucket:

MODE=all
DATABASE_URL=postgresql://…            # Fly Postgres
STORAGE_ADAPTER=s3
S3_ENDPOINT=https://fly.storage.tigris.dev
S3_REGION=auto
S3_BUCKET=myapp-patch
S3_FORCE_PATH_STYLE=true
PUBLIC_BASE_URL=https://myapp-patch.fly.storage.tigris.dev/codemagic-patch

Two caveats. Running it outside Compose is documented in the repository as reference material, not a supported path in this first open-source release, so on Fly you’re on your own for upgrades and backups. I haven’t deployed it that way yet either; this is the plan, not a report. And if you’ve read my post on Fly’s scale-to-zero, keep at least one machine running. Phones never wait on the API for an update check, since manifests come straight from storage, but every metrics upload and every release job would otherwise start with a cold boot.

Tigris is the part I’m most keen on. It’s where maru’s files already are, and it puts a CDN in front of the URL every app launch hits. Mind the manifest caching if you do this: with the plain base-URL delivery adapter Patch serves manifests as no-cache, because it can’t purge a CDN, and a manifest cached on its own TTL would keep serving a release you’ve just rolled back. The configuration reference now documents this under MANIFEST_CACHE_CONTROL, and the docs site covers S3-compatible storage.

On the hosted server you create the apps again, put the new keys in the preview and production profiles in eas.json (Staging keys and Production keys), and create a token for publishing:

cmpatch token create --name ci

If you want code signing, decide now: generate the production key pair, keep the private key as a CI secret, put the public key in the build profiles, and turn on “require code signing” for both apps. The first Patch binary also needs a new version number, because the binaries already in the stores run expo-updates. Build it with the preview profile for TestFlight and Play internal testing first, and check the keys actually made it into the built Info.plist and Android resources before handing it to anyone. That’s the one link my local tests didn’t exercise, since I exported the environment by hand. Then publish to Staging, confirm one download and one success per tester, and only then build for the stores.

Production releases start small and grow:

./scripts/publish-update.sh ios --production --rollout 10
cmpatch release patch --app maru-ios --deployment Production --label v1 --rollout-percentage 100

The old server stays up in the meantime. Every copy of 2.5.1 that people haven’t updated still checks it, and hotfixes for them still go through the old script. Once the logs show those requests have stopped, the old server, its publish script and its secret can all go.

The first native upgrade

#

Added 16 October 2026.

Patch has been carrying maru’s production updates since early October. The first native release since then was the move to Expo SDK 58: React Native 0.88, and on Android a new major version of the Gradle plugin. A native change can’t go over the air, so it’s a new binary, 2.6.0, and my publish script refuses to send 2.6.0 updates until that binary exists. Both platforms built cleanly the first time.

The production section above says to check the keys really made it into the built Info.plist and Android resources before handing a build to anyone. This time I did, and that check is the reason this section exists. The iOS build had its four Patch settings. The Android build had none:

bundletool dump resources --bundle=build.aab --values | grep -A1 "string/Codemagic"

That command printed four keys for the 2.5.11 build and nothing for 2.6.0. The environment wasn’t the problem: Gradle’s generateReleaseResValues writes all four. They’re removed later by the release resource shrinker, which in Android Gradle Plugin 9 is much more aggressive. The same app went from 9,240 resources to 7,116. The SDK reads its configuration by name with getIdentifier, which the shrinker can’t see, so it removed the four strings as unused. A missing string reads as empty, and empty means “no updates”. Nothing would have failed. Android 2.6.0 would have installed, run normally and never received an update, and the only sign would have been no Android 2.6.0 devices on the dashboard.

The fix is one resource file that tells the shrinker to keep the four strings:

<!-- android/app/src/main/res/raw/codemagic_patch_keep.xml -->
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:keep="@string/CodemagicPatch*" />

Don’t call it keep.xml: React Native’s bundle task already generates a raw/keep.xml for your JavaScript assets (which is why images and fonts survived), and the two would collide. The better place for this rule is the SDK itself, since a library’s keep file is merged into the app automatically, and a warning when a release build starts with no deployment key would turn the silent case into a visible one. This is the same kind of failure as the iOS version-detection bug earlier: nothing errors, and the updates just never arrive.

The same check turned up a second problem that has nothing to do with Patch, and it’s worth knowing for a different reason. The Android release build crashed on launch, twice, for two separate reasons inside Expo’s own modules. First, Expo’s widgets module failed to register its native classes, so the app died before any JavaScript ran. With that fixed, the app got as far as starting its JavaScript and then stopped, because three modules that had moved to Expo’s new module system were never registered. Patch’s crash rollback can’t help with either, because there is no update to roll back. It protects you from a bad update, not from a bad binary. A native upgrade still has to be installed and opened on a real device or emulator before it goes to the store, Patch or no Patch.

One smaller thing came out of the same testing. When sync() fails, it returns "error" and keeps the reason to itself unless the app is running in development, so a release build can only log that something went wrong. My hook now calls checkForUpdate() once after a failed sync and logs what that throws, which is how I learned that a local simulator build had empty Patch URLs (unsupported URL) rather than a broken server. It would help if the last error were readable in release builds too.

My checklist for a native release now has three lines it didn’t have before: dump the Patch settings from the built .ipa and .aab, compare the deployment keys with the build profile, and launch the release build itself, not a debug build, before submitting.

What I’d tell someone with an Expo bill

#

If you’re paying for EAS Update because building a server looked like too much work, Patch is a real answer: you run a server, but it’s a Compose stack and an installer, not code you maintain. Compared with what I built, you get staged rollouts, per-release install and failure numbers, binary patches, a fingerprint guard, code signing, crash rollback on the device, and a rollback button. I had built none of those.

What it costs: a new binary before anyone gets a Patch update, since the SDK has to be in the app; a server to keep upgraded and backed up; three crashed launches per user by default when a release is bad enough; and some hand work if your native projects are committed. It’s also young. This was version 0.3.0, and I hit a version-detection bug, a noisy debug command and a few gaps in the docs, and made a bug of my own that the SDK could have prevented. The version detection and the debug command have since been fixed, most of the docs gaps filled, and the SDK now guards against the mistake I made. None of it stopped the migration, and all of it was visible, in the CLI, in the dashboard, or in the SDK’s own files on the device, which is more than I can say for my old setup.

Update, 13 September 2026. Since this went up, Codemagic have released Patch, an open-source, self-hostable OTA server in the CodePush mould. If you got here because you’d rather not build the server yourself, it’s now a real option: I’ve since moved an app from the setup below to Patch and written up how that went, and there’s a short note on it under Wrapping up. Disclosure: Codemagic paid me to do that migration and write about it, and asked for a mention here. The code in the rest of this post has since been trimmed to short examples.

My estimating app gets its bug fixes pushed over the air: JavaScript changes land on users’ phones without going anywhere near App Store review. Expo’s hosted service, EAS Update, will happily do this for you. I built my own version anyway, with Django REST Framework and Tigris S3, and it has served every iOS and Android update since.

Expo OTA updates work like this: the app’s expo-updates library asks an update server for a manifest, sending its platform and runtime version in headers. The server answers with the newest compatible update and the URLs of its JavaScript bundle and assets, and the app downloads them and runs the new bundle on its next launch. EAS Update is Expo’s hosted server for that protocol, but any server that speaks it will do, and that’s what I built.

This post walks through the whole thing: the models, the manifest endpoint, the publishing pipeline, and the gotchas that only show up once you’re running it yourself.

Why self-host at all?

#

Mostly cost, in my case. EAS Update pricing scales with usage, so pushing frequent updates to a growing user base adds up, while S3-compatible storage like Tigris stays nearly free. There are other reasons that might weigh more for you: some industries have to keep every application asset inside their own infrastructure, and owning the server means owning the update flow, so you can roll out to specific user segments or A/B test bundles if your product calls for it. It also means nothing about your update pipeline depends on Expo’s availability or their next pricing change.

How the pieces fit

#

Four components: a Django backend that serves update manifests and stores metadata, Tigris holding the actual bundle and asset files, a publishing script that exports, uploads and registers updates, and the mobile app itself pointed at my server instead of Expo’s.

┌─────────────────┐
│   Mobile App    │
│  (expo-updates) │
└────────┬────────┘
         │ 1. Request manifest
         │    (with headers: platform, runtime-version)
         ↓
┌─────────────────┐
│  Django Server  │
│  /api/expo-     │◄─── 2. Query DB for latest update
│   updates/      │
│   manifest/     │
└────────┬────────┘
         │ 3. Generate presigned URLs
         │
         ↓
┌─────────────────┐
│   Tigris S3     │
│  (Asset Files)  │◄─── 4. App downloads bundles directly
└─────────────────┘

Building it

#

The two models

#

Everything hangs off ExpoUpdate and ExpoUpdateAsset. The first stores metadata for each update:

class ExpoUpdate(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
    runtime_version = models.CharField(max_length=50, db_index=True)
    platform = models.CharField(
        max_length=10,
        choices=[("ios", "iOS"), ("android", "Android")],
        db_index=True
    )
    is_active = models.BooleanField(default=True, db_index=True)
    manifest_data = models.JSONField()
    description = models.TextField(blank=True)
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        indexes = [
            models.Index(fields=["runtime_version", "platform", "is_active", "-created_at"])
        ]

A few deliberate choices in there. runtime_version mirrors the runtimeVersion in app.json, and it does a lot of work: clients only ever download updates matching their own runtime version. iOS and Android get separate rows because the bundles differ. is_active is the rollback mechanism; deactivate a bad update and clients fall back to the previous one. And manifest_data holds the complete Expo Updates v1 protocol manifest as JSON, so serving it later is just a lookup.

ExpoUpdateAsset tracks the individual files:

class ExpoUpdateAsset(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
    update = models.ForeignKey(ExpoUpdate, on_delete=models.CASCADE, related_name="assets")
    hash = models.CharField(max_length=255, db_index=True)
    key = models.CharField(max_length=255)
    content_type = models.CharField(max_length=100)
    file_extension = models.CharField(max_length=10)
    file_path = models.CharField(max_length=500)
    file_size = models.IntegerField(default=0)

Assets are keyed by SHA-256 hash, which makes them immutable and cacheable. The same asset can be shared across any number of updates.

The manifest endpoint

#

/api/expo-updates/manifest/ is where app and server actually talk. It implements the Expo Updates v1 protocol:

@action(detail=False, methods=["get"], url_path="manifest")
def manifest(self, request):
    # Extract required headers
    protocol_version = request.META.get("HTTP_EXPO_PROTOCOL_VERSION")
    platform = request.META.get("HTTP_EXPO_PLATFORM")
    runtime_version = request.META.get("HTTP_EXPO_RUNTIME_VERSION")

    # Validate protocol version
    if protocol_version != "1":
        return Response(
            {"error": f"Unsupported protocol version: {protocol_version}"},
            status=400
        )

    # Find latest active update for this runtime + platform
    update = ExpoUpdate.objects.filter(
        runtime_version=runtime_version,
        platform=platform,
        is_active=True,
    ).order_by("-created_at").first()

    # No update available - client uses embedded bundle
    if not update:
        response = Response(status=204)
        response["expo-protocol-version"] = "1"
        return response

    # Generate presigned URLs for all assets
    manifest_data = build_manifest(update)  # fills in presigned asset URLs

    return Response(manifest_data, status=200)

Three details matter here. A 204 response means “no update”, and the app carries on with its embedded bundle. The asset URLs in the manifest are presigned, so the app downloads straight from Tigris’s CDN rather than streaming everything through Django. And the expo-protocol-version response header isn’t optional; the client checks for it.

Publishing updates

#

Publishing is a Django management command with a shell script wrapped around it. The command reads the output of expo export, hashes every asset with SHA-256, uploads bundles and assets to Tigris in parallel, writes the database records, and optionally drops an import JSON into the bucket for production sync. Cut down to the part that matters:

from concurrent.futures import ThreadPoolExecutor

from django.db import transaction


def publish(platform, runtime_version, manifest, files):
    # Upload the bundle and assets in parallel (keys are content hashes)
    with ThreadPoolExecutor(max_workers=10) as executor:
        list(executor.map(upload_asset, files))

    # Swap the active update in one transaction
    with transaction.atomic():
        ExpoUpdate.objects.filter(
            runtime_version=runtime_version,
            platform=platform,
            is_active=True,
        ).update(is_active=False)

        return ExpoUpdate.objects.create(
            runtime_version=runtime_version,
            platform=platform,
            manifest_data=manifest,
        )

The wrapper script is what I actually type:

# Publish to local environment
./publish.sh ios

# Publish to production
./publish.sh ios --production

# Dry run to validate
./publish.sh --dry-run

It loads production environment variables before exporting, handles one platform or both, and takes care of the production sync described next.

Syncing to production

#

I didn’t want production credentials sitting on my laptop, so production deploys happen in two steps: publish locally (assets go to Tigris, along with a JSON snapshot of the metadata), then call a production API endpoint with the S3 path so the server imports the metadata itself:

@action(detail=False, methods=["post"], url_path="import-update")
def import_update(self, request):
    # Authenticate via Bearer token
    token = request.META.get("HTTP_AUTHORIZATION", "").removeprefix("Bearer ")
    if not hmac.compare_digest(token, settings.IMPORT_TOKEN):
        return Response({"error": "Invalid token"}, status=401)

    # Download the import JSON from the bucket
    s3_key = request.data.get("s3_key")
    obj = s3_client.get_object(Bucket=bucket_name, Key=s3_key)
    data = json.loads(obj["Body"].read())

    # Import into the production database
    with transaction.atomic():
        update, _ = ExpoUpdate.objects.update_or_create(id=data["id"], defaults={...})
        for asset_data in data["assets"]:
            ExpoUpdateAsset.objects.update_or_create(...)

    # Clean up the import JSON
    s3_client.delete_object(Bucket=bucket_name, Key=s3_key)
    return Response({"update_id": str(update.id)})

Pointing the app at your server

#

In app.json, set the update URL and runtime version:

{
  "expo": {
    "runtimeVersion": "1.0.0",
    "updates": {
      "url": "https://api.example.com/api/expo-updates/manifest/"
    }
  }
}

Be strict about keeping runtimeVersion matched between app and server. When you change native code or upgrade the Expo SDK, bump the runtime version and publish fresh updates for it.

Storage on Tigris

#

Tigris is S3-compatible object storage, considerably cheaper than actual AWS S3, and it includes global edge caching, which matters when users are pulling down multi-megabyte bundles. The Django configuration:

# settings.py
BUCKET_NAME = os.getenv("BUCKET_NAME")
AWS_ENDPOINT_URL_S3 = os.getenv("AWS_ENDPOINT_URL_S3")
AWS_ACCESS_KEY_ID = os.getenv("AWS_ACCESS_KEY_ID")
AWS_SECRET_ACCESS_KEY = os.getenv("AWS_SECRET_ACCESS_KEY")
AWS_REGION = os.getenv("AWS_REGION", "auto")

Creating the client is standard boto3:

import boto3

def create_s3_client(endpoint_url, region, access_key, secret_key):
    return boto3.client(
        "s3",
        endpoint_url=endpoint_url,
        region_name=region,
        aws_access_key_id=access_key,
        aws_secret_access_key=secret_key,
    )

Downloads go through presigned URLs, so the app fetches straight from the CDN:

presigned_url = s3_client.generate_presigned_url(
    "get_object",
    Params={"Bucket": bucket_name, "Key": asset.file_path},
    ExpiresIn=3600,  # 1 hour
)

Security

#

The manifest endpoint is unauthenticated on purpose, because apps need updates before anyone has logged in. The import endpoint is a different story. It can write to the production database, so it wants a shared secret, compared in constant time to rule out timing attacks:

IMPORT_TOKEN = os.getenv("IMPORT_TOKEN")

# Constant-time comparison prevents timing attacks
if not hmac.compare_digest(token, IMPORT_TOKEN):
    return Response({"error": "Invalid token"}, status=401)

Asset integrity comes free with the design: everything is verified against its SHA-256 hash, so a tampered asset simply fails. And presigned URLs expire after an hour, which keeps bundles from being hotlinked indefinitely.

Keeping it fast

#

The composite index on (runtime_version, platform, is_active, -created_at) keeps the manifest query quick no matter how many updates accumulate:

class Meta:
    indexes = [
        models.Index(fields=["runtime_version", "platform", "is_active", "-created_at"])
    ]

The publishing script uploads assets concurrently:

with ThreadPoolExecutor(max_workers=10) as executor:
    futures = {executor.submit(upload_asset, asset): asset for asset in assets}
    for future in as_completed(futures):
        # Track progress

For a typical update with 50 or so assets, that took publishing from about 2 minutes down to 15 seconds. Distribution needs no work at all: Tigris caches assets at edge locations near your users on its own.

Day-to-day workflow

#

During development

#

# 1. Make code changes in the app
git commit -am "Fix bug"

# 2. Publish OTA update to local environment
./publish.sh ios

# 3. Test on device
# App automatically downloads and applies update

Shipping to production

#

# 1. Publish to production
./publish.sh ios --production

# 2. Monitor
# Check Django admin for update records
# Verify assets in Tigris dashboard

Rolling back

#

# Mark problematic update as inactive in Django admin
# or via management shell:
python manage.py shell

>>> from updates.models import ExpoUpdate
>>> bad_update = ExpoUpdate.objects.get(id="uuid-here")
>>> bad_update.is_active = False
>>> bad_update.save()

# Clients will now receive the previous active update

What it costs

#

The app has around 500 active users. On Tigris, the ~200 MB of historical updates costs about $0.02/month, and the ~50 GB of monthly egress from update downloads about $1.00. The Django side rides along on the server my API already runs on, so its incremental cost is zero. Call it a dollar a month, all in. EAS Update at similar usage would land somewhere around $300–500/year, so this paid for itself more or less immediately.

Monitoring and debugging

#

Nothing fancy here. The viewset logs every manifest request:

logger.info(f"Manifest request: platform={platform}, runtime={runtime_version}")

The Django admin is the de facto dashboard. Register the models and you can inspect and filter everything:

@admin.register(ExpoUpdate)
class ExpoUpdateAdmin(admin.ModelAdmin):
    list_display = ["platform", "runtime_version", "is_active", "created_at"]
    list_filter = ["platform", "is_active", "runtime_version"]
    search_fields = ["description"]

And on the client, expo-updates will tell you what it sees:

import * as Updates from 'expo-updates';

Updates.checkForUpdateAsync().then(update => {
  console.log('Update available:', update.isAvailable);
  console.log('Manifest:', update.manifest);
});

Gotchas

#

Runtime version mismatches

#

The most common failure is also the quietest: clients only download updates matching their runtime version. If the installed app is on runtime 1.0.0 and you publish for 1.0.1, nothing arrives and nothing errors. Keep the runtime version in sync with your builds, and only bump it when native code changes.

The createdAt timestamp

#

The expo-updates client compares the manifest’s createdAt against the embedded bundle’s commitTime, and only applies an update whose createdAt is newer. The viewset overrides it with the database timestamp:

manifest_data["createdAt"] = update.created_at.strftime("%Y-%m-%dT%H:%M:%S.%fZ")

For local development, if you build a binary after publishing an OTA, republish the OTA so its timestamp wins.

Manifest asset key values

#

The key field on each manifest asset is what expo-updates uses for caching, and it must be a deterministic hash (the MD5 of the filename works), not a random UUID or arbitrary string. Get this wrong and the client may fail to cache or retrieve assets correctly, and updates silently break after the first successful load. Thanks to reader Raphael Mutschler for flagging this one; he had updates working exactly once before discovering the issue.

App config in expoClient

#

If your app uses Linking, Constants, or anything else that reads the app config at runtime, the manifest’s extra.expoClient field needs to include your app config. Without it the app may launch fine at first, then crash or refuse to reopen after being closed. That’s because expo-updates replaces the embedded manifest with the OTA one, and if expoClient is missing, those APIs lose the config they depend on. Raphael Mutschler caught this one too.

Asset cleanup

#

Old updates pile up in Tigris. For now, cleanup at my end is manual:

# Delete updates older than 30 days
from datetime import timedelta
from django.utils import timezone

cutoff = timezone.now() - timedelta(days=30)
old_updates = ExpoUpdate.objects.filter(created_at__lt=cutoff, is_active=False)

for update in old_updates:
    # Delete assets from S3
    for asset in update.assets.all():
        s3_client.delete_object(Bucket=bucket_name, Key=asset.file_path)
    # Delete DB records
    update.delete()

A scheduled task is the obvious home for this. I haven’t got round to it.

Things I’d add next

#

(September 2026: Patch now does all three of these and more; see the migration write-up.)

Gradual rollouts

#

A rollout_percentage field would let an update go out to a slice of users first:

rollout_percentage = models.IntegerField(default=100)

# In the manifest view:
if update.rollout_percentage < 100:
    # Hash user ID and check if they're in rollout group
    user_hash = int(hashlib.sha256(user_id.encode()).hexdigest(), 16)
    if (user_hash % 100) >= update.rollout_percentage:
        return Response(status=204)  # No update

Separate staging updates

#

An environment field would let staging builds receive different updates from production:

environment = models.CharField(max_length=20, default="production")

# Client sends environment in custom header
environment = request.META.get("HTTP_X_UPDATE_ENVIRONMENT", "production")
update = ExpoUpdate.objects.filter(environment=environment, ...).first()

Download analytics

#

And a small model would answer the “did anyone actually get this?” question properly:

class ExpoUpdateDownload(models.Model):
    update = models.ForeignKey(ExpoUpdate, on_delete=models.CASCADE)
    user_id = models.CharField(max_length=255, null=True)
    platform = models.CharField(max_length=10)
    downloaded_at = models.DateTimeField(auto_now_add=True)

Wrapping up

#

The whole system is two Django models, a couple of views, a publishing script and a dollar a month in infrastructure. That’s less than I expected going in, and it has quietly done its job for the app on both platforms since.

The snippets above are simplified examples of what runs in that production app, so adapt them to whatever you’re building. Reader Raphael Mutschler also published a standalone implementation at expo-ota-server if you’d rather start from something that already runs.

If you’d rather not write the server

#

Two things have appeared since I wrote this that cover the same ground without the Django. The first is Raphael’s expo-ota-server above. The second is Codemagic Patch: open source, runs on your own box from a Docker Compose install, and speaks CodePush rather than the Expo Updates protocol, so you swap expo-updates for its SDK and eas update for cmpatch release-react. It can use S3-compatible storage, so a Tigris bucket like the one in this post works too.

Out of the box it has the things I listed under “Things I’d add next” and never built: staging and production deployments, percentage rollouts, per-release download and install numbers, mandatory updates, binary patches, code signing, and a rollback on the device when a new bundle crashes before the app reports ready. The trade is a new native binary before anyone gets a Patch update, since the SDK has to be in the app, and a server to run instead of a management command.

I moved one of my own apps, with its committed native projects and real release pipeline, from the setup in this post to Patch. The write-up covers what worked, what didn’t, and how hard it really is. Codemagic sponsored that work and had a factual review pass on it, not an editorial one.

For the full spec, see the Expo Updates Protocol Specification.