Skip to content
carameldocs · 0.23.0
Browse documentation
Guides / Production

From local to live.

Build the release artifact, set the variables a compiled application needs, and run its process roles under the contract any deploy tool can rely on.

ContractValue
Release0.15.0
NeedsA committed application tree, a container engine such as Docker Desktop for the build, and a Linux host with PostgreSQL for the run
You will haveA linux/amd64 artifact that holds bin/SHARD and public/, migrated, serving on a Unix socket and answering GET /health
StatusThe build, the role script, migrate, serve --no-workers, GET /health and SIGTERM run in scripts/check frappe-project-build when a container engine runs; jobs unknown and the proxy are not run by a check
Proved byfrappe build · APP migrate · curl --unix-socket

A compiled application promises any deploy tool the behaviour below, as ADR 0032 ↗ records. SHARD is the application’s name in shard.yml, such as bookshelf; APP below stands for the unpacked bin/SHARD, such as /srv/bookshelf/bin/bookshelf.

Stage 1 · Build

Build the artifact

Terminal · inside the application
frappe build

Expect: Prints the path of .caramel/build/SHARD-YYYYmmddTHHMMSSZ-SHA7-linux-amd64.tar.gz as its only line of output. The archive holds bin/SHARD and public/. Beside it sit SHARD-….tar.gz.sha256, which sha256sum -c or shasum -a 256 -c verifies, and SHARD-….tar.gz.sbom.json, a CycloneDX 1.5 bill of materials naming the application at its commit, the Crystal version, each shard with its version and commit, and the musl, gc, gmp, OpenSSL, pcre2 and zlib versions linked into the binary, with the image digest under properties.

frappe build publishes app/assets into public/, then compiles the committed tree with crystal build --release --static in the pinned crystallang/crystal:1.22.1-alpine image for linux/amd64, keeping debug info. Alpine’s gmp-static is installed first, so an application that uses BigDecimal links GMP into the binary. It needs a container engine, such as Docker Desktop, for this build only. CARAMEL_BUILD_IMAGE, set where frappe build runs, replaces the image, for example with one carrying a patched OpenSSL; it must name the image by digest, such as crystallang/crystal:1.22.1-alpine@sha256:…, so the build stays reproducible, and the SBOM records which digest built the artifact.

ConditionOutcome
frappe build with uncommitted changes in the working treerefuses to build
frappe build when publishing app/assets into public/ leaves changesrefuses to build
CARAMEL_BUILD_IMAGE without a @sha256: digestexits 1 with CARAMEL_BUILD_IMAGE must name an image by digest

Serve public files

serve reads public/ from CARAMEL_ROOT when it is set, so the binary runs from wherever the artifact is unpacked.

ConditionOutcome
CARAMEL_ROOT that is not an absolute pathexits 1 with CARAMEL_ROOT must be an absolute path
CARAMEL_ROOT with no public/ inside itexits 1 with CARAMEL_ROOT has no public directory

Embed the files the binary reads

The artifact holds bin/SHARD and public/ and nothing else: no source tree and no Node or other runtime. The compiler expands __DIR__ when it builds, so in the binary it names a path inside the build container, such as /work/source/src.

ConditionOutcome
File.read, File.open or Dir.glob of a path built from __DIR__raises File::NotFoundError in the release, and an action that reaches it answers 500; it works from a source checkout, so specs pass
{{ read_file("#{__DIR__}/file") }} of a committed fileembeds the file in the binary when it compiles; a change to the file needs a new build
A file a browser fetches, under app/assetsis published to public/assets/ and served at /assets/

frappe lint reports a File or Dir reader called with __DIR__ among its arguments as Caramel/SourceTreeRead; a path stored in a constant or a local first is not reported.

Caramel installs no external runtime on the server, and frappe build neither packs nor checks one. A feature that shells out to Node or a browser needs its host to provide it.

Stage 2 · Run

Set the environment

With CARAMEL_ENV unset the binary runs as production. These variables are read when a process starts:

VariableMeaning
DATABASE_URLThe runtime role’s connection, for serve, work, seed and jobs; a missing one exits 1 with Missing database configuration: DATABASE_URL
MIGRATION_DATABASE_URLThe migration role’s connection, for migrate
APP_ORIGINThe public origin, such as https://bookshelf.example; serve exits 1 with APP_ORIGIN is required without it
APP_SECRETThe secret that signs sessions and tokens; serve exits 1 with APP_SECRET is required without it
APP_SECRET_PREVIOUSThe secrets APP_SECRET replaced, comma-separated, each at least 32 bytes; sessions and CSRF tokens they signed still read, so a rotation signs no one out. Unset it once the session window has passed
CARAMEL_SOCKETThe Unix socket path serve listens on, in a directory only its owner can enter; serve exits 1 with CARAMEL_SOCKET is required; use frappe dev without it, and with CARAMEL_SOCKET must be in a private owned directory when the directory is open
CARAMEL_SOCKET_GROUPA group that may enter the socket’s directory instead, for a proxy that runs as another user; the socket is then mode 0660
CARAMEL_ROOTThe absolute path of the unpacked artifact, holding public/
CARAMEL_SHUTDOWN_TIMEOUTWhole seconds from 1 to 3600, default 25, that serve and work give requests and jobs in flight after their first signal; another value exits 1 with CARAMEL_SHUTDOWN_TIMEOUT must be a whole number of seconds from 1 to 3600

The secret’s minimum length is on the security reference, and the database timeouts and Crema’s ops socket on the Crema reference.

Read the security limits →Read the Crema variables →

Run the process roles

A compiled application can serve HTTP or run Cold Brew with work, including queue selection, concurrency, and graceful completion of in-flight jobs. Run each web process as serve --no-workers, which keeps the PubSub broker and maintenance but runs no jobs or schedules, and run one work process.

Terminal · on the server
APP serve --no-workers

Expect: Prints TITLE is ready at APP_ORIGIN once the socket is bound, and serves until SIGTERM.

Read the serve and work flags →

Check readiness

Each process binds a socket path of its own, and the proxy moves to it once it is ready. A generated application routes GET /health to an action that touches no database; an application that removes the route has no readiness check.

Terminal · on the server
curl --unix-socket "$CARAMEL_SOCKET" -H "Host: bookshelf.example" http://localhost/health

Expect: Prints ok. The Host is the authority of APP_ORIGIN; another host answers 421.

Shut down gracefully

ConditionOutcome
The first SIGTERM or SIGINTstops serve accepting connections, stops claiming jobs and starting schedule blocks, ends every PubSub subscription so a server-sent events stream ends, and answers in-flight requests with Connection: close
Requests, jobs and schedule blocks in flightget CARAMEL_SHUTDOWN_TIMEOUT seconds, default 25; serve exits 0 when they finish or the time passes, and logs what was still running
A job cut off at that deadlinerolls back; the next maintenance pass, within a minute, finds its session gone and releases it, and a release does not count as an attempt
workstops the same way after its first signal
A second SIGTERM or SIGINTexits 1 at once
A request that arrives on a kept-alive connection after the last one in flight finishedis not guaranteed an answer, so a deploy moves the proxy first
A supervisor that stops serve or workmust allow CARAMEL_SHUTDOWN_TIMEOUT plus 5 s before it kills the process

Stage 3 · Cut over

Check for unknown jobs

Before cutover, check the new binary against the queue.

Terminal · on the server
APP jobs unknown

Expect: Prints nothing and exits 0 when every queued class is known; otherwise it prints each class the binary lacks, one per line, and exits 1.

Set up the database

Terminal · on the server
APP db roles DATABASE MIGRATION_ROLE RUNTIME_ROLE

Expect: Prints, without passwords, the psql script that creates a migration role that owns the database and a runtime role with DML through default privileges. It stops before any grant when either role already exists with SUPERUSER, CREATEDB, CREATEROLE, BYPASSRLS or REPLICATION, so run it with psql -v ON_ERROR_STOP=1; the role that runs it stays a member of both roles until you revoke them.

Connect with sslmode=verify-full, plus sslrootcert for a private CA, or through a Unix socket, directly or through a session-mode pooler, never a transaction-mode one. The application needs no superuser and no extension. Each connection sets a statement and a lock timeout when it opens. Read the timeout variables →

Cut over in order

  1. Run the new binary’s migrate while the old one serves.
  2. Stop the old workers.
  3. Move traffic to the new web process.
Terminal · on the server
APP migrate

Expect: Prints Applied N migrations. with MIGRATION_DATABASE_URL set, then a warning for each queued job class this binary lacks.

ConditionOutcome
serve, work or seed with a migration not yet appliedexits 1 with Pending migrations. Run frappe migrate first.
serve, work or seed of an older binary against a schema a newer one migratedstarts, after WARNING: the database holds migrations this binary lacks (v…); starting anyway on standard error
migrate or lint of an older binary against that schemaexits 1 with Applied migration N is missing from this application

Migrations never roll back: an old binary restarted after the new one’s migrate keeps serving until cutover, but going back across a migration means restoring the database.

Stage 4 · Limits

What does not compile

Nothing on this page is checked at compile time: the artifact is the application as frappe check passed it. Each refusal above happens when the command runs, before it binds a socket or writes a row.

Not covered yet

  • Caramel ships no command that provisions servers, installs a proxy or deploys.
  • Artifacts are linux/amd64 only; arm64 artifacts are deferred.
  • Assets are published as files under public/; embedded and fingerprinted assets are deferred.
  • The artifact carries no external runtime, such as Node.

Prove it

Check the artifact before cutover

On the build host:

Terminal · inside the application
frappe build

On the server, with the artifact unpacked at /srv/bookshelf and the variables above exported:

Terminal · on the server
/srv/bookshelf/bin/bookshelf migrate
/srv/bookshelf/bin/bookshelf jobs unknown
/srv/bookshelf/bin/bookshelf serve --no-workers &
curl --unix-socket "$CARAMEL_SOCKET" -H "Host: bookshelf.example" http://localhost/health

Passing: frappe build prints one artifact path. migrate prints Applied N migrations., jobs unknown prints nothing and exits 0, serve prints Bookshelf is ready at https://bookshelf.example, and curl prints ok. scripts/check frappe-project-build runs the build, the role script, migrate, serve --no-workers, GET /health and SIGTERM in a container when an engine is running, and prints SKIP: frappe build needs a running container engine otherwise.