Deploy and build

So, you have a concile serve deployment up and running (feel free to check out Self-hosting if you need a hand with that). Now you want to push a new code change to it, but you'd really rather not deal with rebuilding the container or restarting the process.

You actually have a couple of options here, plus a third route if you want to skip containers completely:

• concile deploy takes your local concile/ changes, pushes them to a running serve, and hot-swaps them in live without any restarts.
• concile build bundles your entire app into a single, self-contained executable. It is perfect for when you prefer shipping a binary instead of a Docker image.
• The provisioning targets (cloudflare, docker, railway, fly, aws) are a totally different mode for concile deploy. They set up infrastructure instead of doing a hot-swap.

We'll cover all three on this page. If you know exactly what you need, feel free to jump right to it:

• concile deploy: live hot-swap
• The six deploy targets
• Deploying from CI (GitHub Actions)
• concile build: one self-contained binary
• Choosing between deploy, build, and Docker has a handy comparison table if you are trying to figure out which one is right for you.

concile deploy: live hot-swap onto a running server

When you use concile deploy, it transpiles your local concile/ functions along with any additive schema changes, and pushes them straight to your active concile serve deployment. The server checks everything over and applies the updates atomically. This means it keeps handling requests normally the entire time, and if a deploy gets rejected, it won't ever leave things in a half-updated state.

concile serve --dir concile --allow-deploy
# or, equivalently:
CONCILE_ALLOW_DEPLOY=1 concile serve --dir concile

CONCILE_ADMIN_KEY=your-strong-secret concile deploy --url https://myapp.example

✓ deployed via serve (production) - rev 4b3187d88b93 (7 functions, 2 changed)
  https://myapp.example

Responses and status codes

Additive-only schema: destructive changes are rejected, not migrated

Right now, Concile doesn't have data migrations. Instead, diffSchema carefully compares the schema you just pushed with the server's live one, checking it field by field and table by table.

Allowed (accepted, swap proceeds):

• Adding a brand-new table.
• Adding a new optional field to an existing table.

Rejected (409, server stays on the previous version):

• Removing or renaming a table.
• Changing a table's internal table number. You shouldn't see this under normal use, as table numbers are kept stable across deploys specifically so this check doesn't block legitimate changes.
• Removing a field from an existing table.
• Changing a field's type. This includes changes that might look like a safe widening, like going from a string to a union that includes string, or changing any to string. The diff can't be sure a widening is safe for every single existing row (for example, an any column might hold values that aren't valid strings). Because of this, we take a conservative approach and reject any field-type changes. Being overly cautious here only fails a deploy; it can never corrupt your data, which is the whole reason this protection is here.
• Turning an existing optional field into a required one.
• Adding a new required field to a table that already exists. Since existing rows wouldn't have this new field, make it optional instead, and then backfill the data with a mutation if you need it populated for every row.

If any of these issues happen, you will get a deploy failed: <reason> error that tells you exactly which table and field failed and why:

✗ deploy failed: field "notes.priority" changed type string→number (destructive)

The component set is fixed at boot

Any components you've set up in concile.config.ts (like @concile/scheduler, @concile/workflow, and so on) are locked in when serve first boots. While concile deploy is great for pushing new functions and additive schema updates for those components, it cannot add or remove a component on a live server. If you need to change the component list in concile.config.ts, you will have to restart the process or redeploy your container entirely.

Worked example

# 1. Start a deploy-enabled server (once)
CONCILE_ADMIN_KEY=prod-secret concile serve --dir concile --allow-deploy &

# 2. Make a change locally: add a new query, add an optional field to schema.ts
#    (edit concile/notes.ts, concile/schema.ts)

# 3. Push it live (run `concile codegen` first if schema/functions changed)
CONCILE_ADMIN_KEY=prod-secret concile deploy --url http://localhost:3000
# ✓ deployed via serve (production) - rev 4b3187d88b93 (8 functions, 2 changed)
#   http://localhost:3000

# 4. The new function is callable immediately, no restart:
curl -X POST http://localhost:3000/api/run \
  -H 'content-type: application/json' \
  -d '{"path":"notes:add","args":{"box":"b1","text":"hello"}}'

If you have any WebSocket clients subscribed to a query on the notes table before step 3, they will see the write from step 4 pushed to them reactively. The deploy that happened in between won't drop or reset their subscriptions.

Going deeper: what a deploy actually does

The six deploy targets

concile deploy --url <url> (documented above) is shorthand for one specific target: --target serve, the default. The general form is --target <name> --env <name> (plus --dry-run and --check), and the other five targets provision infrastructure instead of hot-swapping an already-running process. Target settings and credentials can live in the deploy block of concile.config.ts (see Configuration).

We never bundle provider CLIs into concile itself. Instead, each target simply shells out to the CLI you already have installed. If it's missing, you will get a clear install hint during the preflight check. Just remember that only the serve target actually uses the additive-schema gate we described earlier. The other provisioning targets ship a brand new build or image, so there is nothing to gate, because the platform's own rollout handles replacing the process.

Deploying from CI (GitHub Actions)

Think of CI as just another caller running the same command. The workflow below runs the exact same concile deploy that you would run locally, pulling credentials from your repository secrets instead of your environment.

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: bun run test
      # PRs: verify committed codegen is current; exits before any target preflight, so
      # it needs no secrets. Add --dry-run to also validate target preflight/packaging
      # (the serve target's preflight then wants CONCILE_DEPLOY_URL + CONCILE_ADMIN_KEY).
      - if: github.event_name == 'pull_request'
        run: bunx concile deploy --check
      # main: the real deploy (serve target).
      - if: github.ref == 'refs/heads/main'
        run: bunx concile deploy
        env:
          CONCILE_DEPLOY_URL: ${{ secrets.CONCILE_DEPLOY_URL }}
          CONCILE_ADMIN_KEY: ${{ secrets.CONCILE_ADMIN_KEY }}

Here are three reasons why this workflow is perfectly safe to copy:

• It never hangs. concile deploy figures out its interactive mode from stdin.isTTY and the CI environment variable (GitHub Actions automatically sets CI=true on every runner). Because of this, if a credential is missing, it will fail fast with a helpful message and a non-zero exit rather than sitting there prompting you forever.
• --check gates codegen drift. It will exit 1 if concile/_generated/ doesn't perfectly match a fresh codegen run. This is especially important for the serve target since a serve deploy will never regenerate it. Adding --dry-run goes a step further by validating the target's preflight and package steps without actually pushing anything.
• Exit codes are real. A rejected schema change, a failed --check, or a provider CLI error will always exit 1 and fail the job just like any standard CI step.

If you are using a provisioning target, you just need to swap out the deploy line and your secrets. For example, use bunx concile deploy --target cloudflare with a CLOUDFLARE_API_TOKEN (and remember to add an npm i -D wrangler install step). Or use --target railway with RAILWAY_TOKEN, --target fly with FLY_API_TOKEN, and so forth, as shown in the table above. Make sure your tokens always come from CI secrets, because the interactive login flows of provider CLIs really have no place in a headless runner.

concile build: one self-contained binary

Using concile build will compile your entire app, the Bun runtime, the Concile engine, bun:sqlite, your concile/ functions and schema, plus any composed components, directly into a single executable using bun build --compile. When it comes time to deploy, all you need is that binary and a data directory. You won't need a bun or node install, no node_modules, and no concile/ source tree at all.

concile build

concile build --outfile ./dist/my-backend

✓ built ./concile-server (58MB)

CONCILE_ADMIN_KEY=your-strong-secret ./concile-server --port 3000 --hostname 0.0.0.0 --data-dir ./data

{"ready":true,"port":3000,"url":"http://0.0.0.0:3000"}

Other limitations

• Single instance. SQLite strictly requires exclusive file access, meaning you can only have one binary process per data directory. The only exception is if you pass --database-url to point it at Postgres. In that case, the usual single-writer advisory-lock rules from Postgres apply instead.
• No concile init scaffolder. You have to bring your own concile/ directory, because concile build will not generate one for you.

Worked example: fixture app with a component, then cross-compiled

This matches what we do in our shipped end-to-end test:

concile build --dir concile --outfile ./concile-server --no-dashboard
# ✓ built ./concile-server (58MB)

CONCILE_ADMIN_KEY=e2e ./concile-server --port 3599 --hostname 127.0.0.1 --data-dir ./data
# {"ready":true,"port":3599,"url":"http://127.0.0.1:3599"}

curl -X POST http://127.0.0.1:3599/api/run \
  -H 'content-type: application/json' \
  -d '{"path":"notes:add","args":{"box":"a","text":"compiled"}}'
# {"value":null,"committed":true,...}

# Cross-compile the same app for a Linux server:
concile build --dir concile --target linux-x64 --outfile ./dist/server-linux --no-dashboard
# ✓ built ./dist/server-linux (95MB)

Going deeper: how the build works

Cross-compilation

concile build --target linux-x64 --outfile ./dist/server-linux

concile build --target linux-arm64 --outfile ./dist/server-linux-arm64

concile build --target darwin-arm64 --outfile ./dist/server-macos

concile build --target darwin-x64 --outfile ./dist/server-macos-x64

concile build --target windows-x64 --outfile ./dist/server-windows.exe

For the windows-x64 target, it will automatically append .exe to your --outfile if you didn't include it yourself.

Deployment patterns for the binary

CONCILE_ADMIN_KEY=your-strong-secret ./concile-server --hostname 0.0.0.0 --port 8080 --data-dir /var/lib/concile

FROM gcr.io/distroless/base-debian12
COPY dist/concile-server /concile-server
EXPOSE 3000
VOLUME /data
ENTRYPOINT ["/concile-server", "--hostname", "0.0.0.0", "--data-dir", "/data"]

concile build --target linux-x64 --outfile ./dist/concile-server
docker build -f Dockerfile.binary -t my-app-binary .
docker run -p 3000:3000 -e CONCILE_ADMIN_KEY=your-strong-secret -v concile-data:/data my-app-binary

[Unit]
Description=Concile Server
After=network.target

[Service]
Type=simple
Environment=CONCILE_ADMIN_KEY=your-strong-secret
ExecStart=/opt/concile/concile-server --data-dir /var/lib/concile --hostname 0.0.0.0
Restart=on-failure
User=concile

[Install]
WantedBy=multi-user.target

Choosing between deploy, build, and Docker self-hosting

In practice, these options aren't mutually exclusive at all. You could easily run concile serve --allow-deploy inside a container and use concile deploy against it for all your day-to-day shipping. Then, you can just fall back to fully rebuilding the image on those rare occasions when you actually need to change the composed component set.

Related

• Self-hosting with Docker: the serve deployment concile deploy pushes onto, and the bind-mounted-image alternative to the standalone binary.
• Postgres: --database-url/CONCILE_DATABASE_URL, accepted by both serve and the compiled binary.
• Cloudflare: concile deploy --target cloudflare, and the general --target/--env provisioning model.
• Local dev: concile dev, the hot-reload loop this page's deploy and build both build on.