Repository navigation
Performance and Deployment
Since 2.26.0 the production image (Dockerfile) is tuned for the container it runs in, and a project can go further
with a response cache and, experimentally, an async server. Every setting below is a line of .env (or a variable of
the container's environment); nothing in the application's code changes.
docker/production/start.sh runs before Apache:
-
PHP processes:
PHP_PROCESSES. By default it follows the app: 2 per CPU the container may use (read from its cgroup quota, at least 4), or 6 per CPU (at least 16) when an AI key is set (OPEN_AI_KEY,GROQ_API_KEY,ANTHROPIC_API_KEY,AGENT_API_KEY,TOGETHER_API_KEY,FIREWORKS_API_KEY,OPENROUTER_API_KEY,WATSON_API_KEY). Apache's own default (up to 150) makes processes fight over a few CPUs; too few, and a page waits behind requests that wait on something else. -
Keep-alive off (
KEEP_ALIVE=onkeeps it). With a fixed number of processes, an idle open connection would hold one. The proxy in front (Caligrafy Cloud, Traefik, a load balancer) keeps the visitors' connections open. -
The response cache (
CACHE=offturns it off) and OPcache preloading (PRELOAD=off). -
php caligrafer.php deploy(framework tables, SQL scripts, migrations), thenphp caligrafer.php optimize(every Pug view compiled, the class map built) as the web server's user: the first visitor of a new container compiles nothing.
OPcache keeps the compiled code and stops checking the files for changes (docker/production/php.ini): a new version
is a new image.
A process answers one request at a time. A page that only computes is fastest with one process per CPU; a request that waits (the database, an AI service, an outside API) holds its process while it waits.
| Your app | PHP_PROCESSES |
|---|---|
| Pages and the database | leave it empty: 2 per CPU, at least 4 (database waits last milliseconds) |
| Calls an AI service (an AI key is set) | leave it empty: 6 per CPU, at least 16; more if more AI requests can wait at the same time (about 3 MB each when idle) |
| Calls another slow service (a payment API, an SMTP server) from its pages | set it: more than the requests that can wait at the same time |
Measured on 2 CPUs (HTML pages per second while other visitors wait 1 s on an outside call): 4 processes answer 8,051 pages a second when nothing waits, but 32 when 4 visitors wait at once; 8 processes answer 4,180, then 7,550 with 4 waiting, then 14 with 16 waiting. The async server answers AI calls without holding a page's process.
php caligrafer.php doctor warns when an app that has AI keys runs fewer than 16 processes, and when the database
allows fewer connections than the processes keep open.
DB_PERSISTENT (empty means on, for MySQL and PostgreSQL in a web server): each process keeps its database
connection between requests instead of opening one per request. Before it is reused, a transaction the last request
left open is rolled back and the session time zone is set again. The command line (tests, migrations, the queue)
never keeps one. Each process holds one connection: the database must allow PHP_PROCESSES connections plus the
command line and the queue (doctor checks it). DB_PERSISTENT=false connects on every request.
A capability or a page whose answer is the same for every visitor can say how long that answer may be shared:
#[Capability(name: 'list_books', description: 'The catalog', readOnly: true, public: true, cache: 30)]
class ListBooks extends Service { /* ... */ }Route::page('/about', 'Site/about', ['cache' => 300]);
Route::capabilities('/capabilities'); // GET /capabilities/list_books (a read-only capability may be called with GET)A GET or HEAD from a visitor with no session cookie and no token gets Cache-Control: public, max-age=30, and the
production image's Apache keeps the answer in memory: the next visitors get it without PHP. Never kept:
- an answer to a signed-in person or to a token (it is not marked);
- an answer that sets a cookie, such as a page with a form (its CSRF token starts a session):
HttpCache::guard()turns it intoCache-Control: private, no-storejust before the headers go out; - any answer other than a 200.
cache needs readOnly: true and public: true. Choose a few seconds for data that changes: a cached answer is not
cleared when the data changes, it expires.
php caligrafer.php add async # Workerman
php caligrafer.php async check # which capabilities may run there, and why the others may notWith ASYNC=on, the production image listens with the async server: processes that keep the application in memory
(ASYNC_WORKERS, one per CPU by default) answer the capabilities channel (GET /capabilities,
/capabilities/{name}), and every other request (pages, forms, sign-in, files) goes to Apache unchanged. A request
that brings the session cookie always goes to Apache.
A capability runs there only when its class uses no session, cookie or superglobal ($_SESSION, $_GET, $_SERVER...),
prints nothing, never calls exit, keeps no static state, is not webOnly and takes no file: async check names
what stops each one, and Apache answers the others as before. After each request, what it left in memory is
forgotten (the cache copies, a transaction, container instances). Its callers are tokens and visitors only.
Development: php caligrafer.php async start --listen http://0.0.0.0:8081 answers on its own port.
Since 2.26.1 a call of a capability by name (/capabilities/{name}, MCP, the JS client) reads the registry of
capabilities from a file kept next to the class map instead of building it on every request: it loads only the file of
the capability it calls. On 2 CPUs through Apache, a public read-only capability answered 2,816 calls a second on
2.26.0 and 4,948 on 2.26.1 (a plain route: about 6,900). Nothing to set: it follows the class map
(How the attribute is found).
The numbers of the benchmark (Docker, 2 CPUs and 1 GB for the app) are on the benchmark dashboard and in the release notes of 2.26.0.
Caligrafy: Describe it. Approve it. Ship it. Your idea turned into a complete app: every feature built once, for web pages, Vue apps, a REST API and AI agents, and online.
Why Caligrafy: the benefits, the measurements, and what it is not yet
-
Quickstart with Claude: describe it, approve it, ship it
or the Quickstart: the same three steps by hand, in 5 minutes
- How Caligrafy works: the ideas in 5 minutes
- Your first capability: build a feature, page included
-
Capabilities in depth
-
#[Capability]: every option - Scheduled jobs: capabilities on a timer
- Notifications: web push and email
- Background jobs: capabilities run later
- Migrations: database changes, in order
- The cache
-
Testing your app
- Dependency injection
- Validation rules
-
Web pages
- Views and page components
- Design styles: another look, one setting
- Declarative routes: every request, in one line
-
Route::page·Route::form·Route::auth·Route::webhook·Route::download·Route::redirect·Route::action·Route::snap· capability routes - How to export a list as CSV
- Controllers: moving one to a declared route · how to, step by step
- Forms and helpers
-
Vue apps
-
Mobile and tablet
-
REST API
-
AI agents
-
Snap Cards and the assistant
- Payments: Stripe and crypto
- Face detection and face login
- OpenAI: chat and images · Assistants
- Open models: Llama, Mistral...
- Chatbots with Watson
- Machine learning in the browser
- Metadata and social cards · search and analytics
-
Putting it online: the production image, the database at every start
-
API reference: every class and method
-
Routing ·
Route·AuthRoutes· pages ·Controller· capabilities -
Data ·
Model·Query· sign-in · jobs ·Notify· payments · AI -
Interfaces · Snap ·
Snap\Cards·Snap\Conversation· testing · tooling · helper functions
-
Routing ·
-
Caligrafer: every command
- Project · build · data · agents · jobs and tests · maintenance · deploy
- Installation, configuration and Caligrafer
- Routing · Request · Controllers · Views
- Vue: flow of information · routes · validations
- Security and upgrading
- Release notes: 2.26 · 2.25 · 2.24 · 2.23 · 2.22 · 2.21 · 2.20 · 2.19 · 2.18 · 2.17 · 2.16 · 2.15 · 2.14 · 2.13 · 2.12 · 2.11 · 2.10 · 2.9 · 2.8 · 2.7 · 2.6 · 2.5 · 2.4 · 2.3 · 2.1 · October 2026 · changelog
- Testing Caligrafy (contributors)