Deploy and build

You've got a concile serve deployment running (see Self-hosting). Now you want to ship a code change to it without rebuilding the container or restarting the process.

There are two ways to do that, plus a third path if you'd rather skip containers entirely:

• concile deploy pushes local concile/ changes to an already-running serve and hot-swaps them in live, with no restart.
• concile build compiles your whole app into one self-contained executable, for when you'd rather ship a binary than a Docker image.
• The provisioning targets (cloudflare, docker, railway, fly, aws), a different concile deploy mode entirely. They provision infrastructure, they don't hot-swap.

This page covers all three. If you already know what you're looking for, jump straight there:

• 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, the comparison table, if you're not sure which of the three fits

concile deploy: live hot-swap onto a running server

concile deploy transpiles your local concile/ functions and additive schema changes, then pushes them to a running concile serve deployment. The server validates everything and applies it atomically: it keeps serving requests the whole time, and a rejected deploy never leaves it half-updated.

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

There are no data migrations in Concile today. diffSchema compares your pushed schema against the server's live one, 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. This shouldn't happen under normal use: table numbers are stable across a deploy specifically so this check never fires on a legitimate change.
• Removing a field from an existing table.
• Changing a field's type, including what looks like a safe widening, like string to a union that includes string, or any to string. The diff can't verify a "widening" is actually sound against every existing row (an any column may hold values that aren't valid strings), so v1 takes the conservative position: any field-type change is rejected. Over-rejecting only fails a deploy. It can never corrupt data, which is the property this gate exists to protect.
• Turning an existing optional field required.
• Adding a new required field to an existing table. Existing rows don't have it, so make it optional instead, and backfill via a mutation if you need every row populated.

Any of these come back as deploy failed: <reason> describing 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

Components composed via concile.config.ts (@concile/scheduler, @concile/workflow, and any others) are whatever was declared when serve booted. concile deploy can push new functions and additive schema against that fixed component set, but it can't add or remove a component on a live server. Changing the component list in concile.config.ts requires restarting the process, or redeploying the container.

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"}}'

Any WebSocket client subscribed to a query touching the notes table before step 3 sees the write from step 4 pushed to it reactively. The deploy in between didn't drop or reset the subscription.

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).

Provider CLIs are never bundled into concile; each target shells out to the one you already have installed, and fails preflight with a clear install hint if it's missing. Only the serve target uses the additive-schema gate described above. The provisioning targets ship a whole new build/image, so there's nothing to gate: the platform's own rollout replaces the process.

Deploying from CI (GitHub Actions)

CI is just another caller of the same command: the workflow below runs the identical concile deploy a human runs locally, with credentials coming from repository secrets.

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 }}

Three properties make this workflow safe to copy:

• It never hangs. concile deploy derives its interactive mode from stdin.isTTY and the CI environment variable (GitHub Actions sets CI=true on every runner), so a missing credential fails fast with an actionable message and a non-zero exit instead of prompting.
• --check gates codegen drift. It exits 1 if concile/_generated/ doesn't match a fresh codegen run, which matters doubly for the serve target since a serve deploy never regenerates it. --dry-run additionally runs the target's preflight and package steps without pushing.
• Exit codes are real. A rejected schema change, a failed --check, or a provider CLI error all exit 1 and fail the job like any other CI step.

For a provisioning target, swap the deploy line and secrets: bunx concile deploy --target cloudflare with CLOUDFLARE_API_TOKEN (plus a npm i -D wrangler install step), --target railway with RAILWAY_TOKEN, --target fly with FLY_API_TOKEN, and so on per the table above. Tokens always come from CI secrets; the provider CLIs' interactive login flows have no place in a headless runner.

concile build: one self-contained binary

concile build compiles your entire app, the Bun runtime, the Concile engine, bun:sqlite, your concile/ functions and schema, and any composed components, into a single executable via bun build --compile. At deployment time you need nothing but the binary and a data directory: no bun/node install, no node_modules, no concile/ source tree.

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 requires exclusive file access, so it's one binary process per data directory (unless you pass --database-url to point it at Postgres, in which case the usual single-writer advisory-lock rules from Postgres apply instead).
• No concile init scaffolder. You bring your own concile/ directory. concile build doesn't generate one.

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

This mirrors the 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

A windows-x64 target automatically appends .exe to --outfile if you didn't already include it.

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 aren't mutually exclusive: you can run concile serve --allow-deploy in a container and use concile deploy against it for day-to-day shipping, falling back to rebuilding the image only when you 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.