Cloudflare

Concile gives you two cool ways to deploy on Cloudflare. Most folks will want to go with the first approach since it's the smoothest. The Containers path is still experimental and doesn't handle scheduled work yet, but you can totally read more about it below if you're curious!

The recommended path: Durable-Object-native

When you run concile deploy --target cloudflare, we set up a Durable Object host from @concile/runtime-cloudflare using wrangler deploy. If you aren't familiar with it, a Durable Object is Cloudflare's way of handling state. It gives you a globally addressable, single-instance object that has its own storage and runs on a single thread.

In this setup, one Durable Object takes care of everything. It acts as the OCC writer, manages your DO-SQLite store, handles all hibernatable WebSockets, and even triggers your scheduled functions and crons. The best part is that it wakes itself up for those scheduled tasks, even if it goes idle between requests! Keep in mind that for v1, this is a single global DO rather than a sharded fleet. If you're looking to scale out later, check out our Scaling guide for details on the paid-tier multi-shard options.

npm i -D wrangler

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "my-app",
  "main": "worker.ts",
  "compatibility_date": "2024-11-27",
  // node:crypto (fingerprint/resume hashing) needs nodejs_compat.
  "compatibility_flags": ["nodejs_compat"],
  "durable_objects": {
    "bindings": [{ "name": "CONCILE_DO", "class_name": "ConcileDO" }]
  },
  "migrations": [
    // DO-SQLite needs the SQLite-backed class migration tag.
    { "tag": "v1", "new_sqlite_classes": ["ConcileDO"] }
  ]
}

concile deploy --target cloudflare --env production

import { defineConfig } from "@concile/component";

export default defineConfig({
  components: [], // your composed components, if any
  deploy: {
    targets: {
      cloudflare: {
        provider: "cloudflare",
        environments: {
          production: {},                      // wrangler deploy
          staging: { wranglerEnv: "staging" },  // wrangler deploy --env staging
        },
      },
    },
  },
});

wrangler secret put CONCILE_ADMIN_KEY

Optional configuration

cloudflare: {
  provider: "cloudflare",
  r2: true,
  r2BucketName: "my-app-storage", // optional, defaults to "concile-storage"
},

wrangler r2 bucket create my-app-storage

What works

Global tables (D1)

When you add .global() to a table definition, it stores that table in Cloudflare D1 (which is a shared relational database) rather than inside a Durable Object's local store. This means you get access to the exact same data regardless of which shard or DO is running your query! This is perfect for information that needs to be globally unique or consistent across your app, like a users table organized by email or an orgs table organized by a slug. It pairs beautifully with our paid-tier multi-shard router, and you can even use it on a single-DO host by simply wiring up a D1 binding.

Just remember that .global() and .shardKey() cannot be used together. A table can be sharded or global, but never both! If you try to declare both, you will get an error when building your schema.

import { defineSchema, defineTable, v } from "@concile/values";

export default defineSchema({
  accounts: defineTable({
    email: v.string(),
    name: v.string(),
  })
    // { unique: true } on a .global() table is a REAL global-unique constraint
    // (a D1 CREATE UNIQUE INDEX), enforced across every shard.
    .index("by_email", ["email"], { unique: true })
    .global(),
});

The great thing is that reads and writes are automatically routed to D1, and your function body will look exactly the same as it does for any other table! We support ctx.db.get(id) as well as equality index queries like .eq(field, value) and optionally .take(n). If you have a mutation that inserts a global row and reads it back right away, it will successfully see its own write. Also, once a row is written through one shard-DO, it becomes instantly readable through any other shard right after the commit! If a unique constraint is violated, the mutation will be rejected and give you a helpful error naming the specific table and field.

If you want to subscribe to a .global() table, you can do so easily using the same useQuery hook as your other tables. Behind the scenes, this works using a poller instead of a commit-time push. A DO with at least one active global subscription will check a D1 version counter roughly every 2 seconds, and it only pushes updates when something actually changes. If a DO doesn't have any subscriptions, it won't poll at all! You can expect global changes to show up within that two-second window, but if your writing client's UI needs to feel instantaneous, we highly recommend adding an optimistic update.

We believe in honest boundaries, so any limitations will fail quickly rather than failing silently:

• No co-writes. A single mutation can write to either global tables or sharded/root tables, but it can never write to both. A D1 write cannot join a shard's local transaction, so allowing both could lead to partial commits. The fix is easy, just split them into two separate mutations!
• Equality-only queries. If you try to use range comparisons, .order(), filters, or .paginate() on a .global() table, we will reject it with a clear and friendly error message.
• { unique: true } means D1. If you try to use this option on a non-global table's index, it will be rejected when loading the schema. A per-shard store just cannot enforce global uniqueness.
• Row policies aren't supported here yet. If you try to apply an authz read or write policy on a .global() table, we will politely reject it with an error instead of silently skipping it.
• Cloudflare only. If you don't have a D1 binding, any read or write to a .global() table will fail and let you know which table caused the issue. You are completely free to declare .global() in a schema that you run locally, but you won't be able to interact with those tables outside of Cloudflare.

For the wiring part, setting up the d1_databases binding is a manual step right now. Simply create the database once using wrangler d1 create <name>, add { "binding": "DB", "database_name": "...", "database_id": "..." } to your wrangler.jsonc file, and pass it through your DO subclass's appConfig as d1: bindingD1Client(env.DB) (which you can import from @concile/docstore-d1). We handle the rest! The D1 tables and indexes for all of your .global() tables are automatically created the very first time you boot with the binding present. No migration steps required!

CI: GitHub Actions

name: deploy
on:
  pull_request:
  push: { branches: [main] }
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: npm i -D wrangler
      - if: github.event_name == 'pull_request'
        run: bunx concile deploy --check --dry-run --target cloudflare
      - if: github.ref == 'refs/heads/main'
        run: bunx concile deploy --target cloudflare --env production
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          CONCILE_ADMIN_KEY: ${{ secrets.CONCILE_ADMIN_KEY }}

The alternative path: Cloudflare Containers (experimental)

If you really want to use the exact same portable concile serve image you would run anywhere else (with SQLite or Postgres storage options), you can run it inside a Cloudflare Container instead of a Durable Object! Just keep in mind that this approach is hand-wired and does not integrate with concile deploy. There are also some specific behaviors you should know about before making your choice.

This setup relies on Workers acting as a stateless router, Containers to run the concile serve image, and R2 as your object-store substrate. Since container storage is temporary, R2 must be your single source of truth. To make this work, you will need a Workers Paid plan (which is around $5 per month, as Containers and DOs do not have a free tier), an R2 bucket, and a Docker setup capable of building for linux/amd64. If you are using Apple Silicon, you will need to cross-build by running docker build --platform linux/amd64. Since Containers do not support bind mounts, your application has to be baked right into the image:

FROM concile:latest
COPY ./concile /app/concile

You will need to point serve at R2 using the --object-store flag like this: s3+https://<account-id>.r2.cloudflarestorage.com/<bucket>?region=auto&forcePathStyle=true. You should expect warm cold-starts to take about 4.5 seconds, or around 7.3 seconds for a true cold start. Writes will also be a bit slower compared to a local-disk host, simply because every commit requires a round trip to R2.

We suggest choosing this path only if scaling to zero is more important to your budget than fast write latency, and you are absolutely sure you don't need scheduled tasks! Otherwise, we highly recommend sticking with the Durable-Object-native path we talked about earlier, or exploring Docker self-hosting if you want to leave Cloudflare altogether.

Moving data between hosts

Because the two Cloudflare paths and our non-Cloudflare hosts store data in different ways, your data won't automatically sync between them. If you need to move things around, you can easily export a portable dump from one setup and import it into another:

CONCILE_ADMIN_KEY=… concile migrate export --url https://source.example.com --out dump.json
CONCILE_ADMIN_KEY=… concile migrate import --url https://target.example.com --in dump.json

Related

• Deploy and build: Learn more about the serve target in concile deploy and concile build, which give you other great ways to ship your changes.
• Scaling: Check this out if you need more power! This guide covers the paid-tier multi-shard Cloudflare router and the Postgres fleet for times when a single node is just not enough.
• Self-hosting with Docker: A fantastic baseline option if you want to skip Cloudflare entirely.
• Vite plugin: Everything you need to know about setting up local development for a Vite app that talks to your deployment.