How to Integrate Fly.io with Your Headless CMS

What is Fly.io?

Fly.io is an application hosting platform that runs Dockerized apps, full-stack frameworks, APIs, and workers on Firecracker microVMs in regions close to users. Teams use it when they want app servers, background jobs, private networking, volumes, and global deployment controlled through flyctl, GitHub Actions, and the Machines API.

Why integrate Fly.io with a headless CMS?

If your app runs on Fly.io, the content workflow can’t stop at “publish.” A new pricing page, product guide, or homepage banner needs to reach the Fly-hosted app, invalidate the right cache entries, and show up for users without someone running fly deploy from a laptop.

A headless CMS integration solves that handoff. With Sanity’s AI Content Operating System, editors publish structured content into the Content Lake, a webhook fires on that publish event, GROQ selects only the fields your Fly app needs, and a Sanity Function or webhook handler sends the payload to Fly.io. For dynamic apps, that might update an internal cache. For static routes, it might trigger a rebuild endpoint or restart Fly Machines after a cache refresh.

The disconnected version is slower and easier to break. Editors publish, developers get pinged in Slack, a deploy runs later, and stale content can sit in memory, Redis, or generated HTML until someone notices. The trade-off is that you need to design your invalidation path carefully. Restarting Machines on every small edit is simple, but it’s usually wrong for high-volume publishing. A targeted route or tag-based cache update is better when content changes many times per hour.

Architecture overview

Content starts in Sanity’s Content Lake as typed JSON. When an editor publishes, updates, or deletes a document, a Sanity webhook fires with the document ID and mutation details. A Sanity Function can receive that event, run a GROQ query such as *[_id == $id][0]{title, "slug": slug.current, modules[]{...}}, and shape the result into the exact payload your Fly-hosted app expects. From there, the Function can POST the content payload to a private endpoint on your Fly.io app, for example https://your-app.fly.dev/internal/content-sync, using a shared secret header. The Fly app can write the content into an in-memory cache, Redis, SQLite on a Fly Volume, LiteFS, or any storage layer you already run there. If the app pre-renders pages or keeps long-lived process caches, the same Function can call the Fly.io Machines API with Authorization: Bearer FLY_API_TOKEN. A common flow is GET /v1/apps/{app_name}/machines to list running Machines, then POST /v1/apps/{app_name}/machines/{machine_id}/restart after the sync endpoint confirms the new content is available. End users then receive fresh content from the Fly region closest to them.

Common use cases

Step-by-step integration

1. 1

   Create and deploy your Fly.io app

   Install flyctl, run fly auth signup or fly auth login, then run fly launch in your app directory. Choose your organization, app name, primary region, and Dockerfile or framework preset. Deploy once with fly deploy so you have a live https://your-app.fly.dev URL.

2. 2

   Create a Fly.io API token

   For local testing, fly auth token can give you a token tied to your account. For automation, create a scoped token with Fly.io’s token commands and store it as FLY_API_TOKEN in Sanity or your webhook runtime. Your handler will use it with the Machines API at https://api.machines.dev.

3. 3

   Model the content your Fly app needs

   In Sanity Studio, define schemas for the routes your app renders. A typical page schema includes title, slug, seoTitle, description, locale, cacheTags, and modules. Keep app-specific fields explicit so GROQ can fetch them without parsing HTML or page blobs.

4. 4

   Create the sync trigger

   Add a Sanity webhook for create, update, and delete mutations on publish, or use a Sanity Function if you want the server-side logic to run inside Sanity. Filter events with GROQ so only relevant document types, such as page, product, or article, trigger the Fly.io sync.

5. 5

   Connect the handler to Fly.io

   Have the handler fetch the latest document with @sanity/client, POST the shaped JSON to an internal route on the Fly app, and call the Fly.io Machines API only when a restart or cache reset is needed. Keep the internal route protected with a secret header.

6. 6

   Test the end-user path

   Publish a draft in Sanity Studio, confirm the webhook fires, inspect the Fly.io app logs with fly logs, and load the affected route from at least two regions if you run multiple Machines. Test delete events too, since removed slugs often break integrations first.

Code example

import {createClient} from '@sanity/client';

const sanity = createClient({
  projectId: process.env.SANITY_PROJECT_ID!,
  dataset: process.env.SANITY_DATASET!,
  apiVersion: '2025-01-01',
  token: process.env.SANITY_TOKEN,
  useCdn: false,
});

async function fly(path: string, init: RequestInit = {}) {
  return fetch(`https://api.machines.dev/v1/apps/${process.env.FLY_APP_NAME}${path}`, {
    ...init,
    headers: {
      authorization: `Bearer ${process.env.FLY_API_TOKEN}`,
      'content-type': 'application/json',
      ...(init.headers || {}),
    },
  });
}

export default async function handler(req: Request) {
  const event = await req.json();

  const page = await sanity.fetch(
    `*[_id == $id][0]{_id,_type,title,"slug":slug.current,"updatedAt":_updatedAt,cacheTags}`,
    {id: event._id}
  );

  if (!page) return Response.json({skipped: event._id}, {status: 202});

  await fetch(`https://${process.env.FLY_APP_NAME}.fly.dev/internal/content-sync`, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-sync-secret': process.env.FLY_SYNC_SECRET!,
    },
    body: JSON.stringify(page),
  });

  const machines = await (await fly('/machines')).json();
  await Promise.all(
    machines.map((m: {id: string}) => fly(`/machines/${m.id}/restart`, {method: 'POST'}))
  );

  return Response.json({synced: page.slug, machines: machines.length});
}

How Sanity + Fly.io works

CMS approaches to Fly.io

Keep building

Explore related integrations to complete your content stack.