Repository navigation
The Production Image
Every Caligrafy project has a production image: the Dockerfile at its root. Caligrafy Cloud, Coolify and any
host that builds from a Dockerfile use it as it is. This page says what is in it, what is left out, what runs when it
starts, and what the container needs from the host. Since 2.4.0.
Since 2.26.0 the image starts with docker/production/start.sh: it sizes Apache to the container (PHP_PROCESSES), turns keep-alive off, keeps database connections, preloads the framework, compiles the views, keeps public answers in memory and can run the async server (ASYNC=on). Every setting is on performance and deployment.
docker/Dockerfileis another file: the development image ofdocker-compose.yaml(thedev-boxandschedulercontainers).
/caligrafy-quill:deploy
The deploy skill checks that the project is ready for the image (the Dockerfile, composer.lock, no .env in git,
safe create_db.sql scripts, a built SPA) and says what to fix. It deploys nothing.
Check before you say OK: docker build -t myapp . finishes, and git ls-files lists no .env, .env.php or
.env.production.
Build and run the image on your computer, with a production-like .env of your own:
docker build -t bookshelf .
docker run --rm -p 8090:80 -v "$(pwd)/.env.production:/var/www/html/.env:ro" bookshelfThe container's log starts with the deploy step,
then Apache's. A .env.production whose database cannot be reached prints
FAIL Database: not reachable after 60 s: check the DB_* settings and
caligrafer deploy: the database is not prepared (see above), and the site starts anyway.
| Layer | What the Dockerfile does |
|---|---|
| Base | php:8.5-apache |
| System | Debian packages over https, the libraries for gd, zip and intl, unzip and git; Apache's rewrite and headers modules |
| PHP | the extensions bcmath, exif, gd (FreeType, JPEG), intl, mysqli, pdo_mysql and zip; the production php.ini
|
| Sessions |
session.save_path = "/var/lib/php/sessions", a folder owned by www-data
|
| Libraries | Composer 2, then composer install --no-dev --no-interaction --prefer-dist --no-scripts --no-autoloader --no-plugins from composer.json and composer.lock alone, so a code change does not install them again |
| Code |
COPY . . (less what Dockerfile.dockerignore leaves out), composer dump-autoload --optimize --no-dev --no-plugins, public/uploads and backups/ created, public/uploads owned by www-data
|
| Port | 80 |
No Node.js and no npm: client apps are served as they are in the repository, a Vite app from its committed dist/.
Composer runs with --no-plugins (2.22.1), so no Composer plugin tries to run npm during the build.
Dockerfile.dockerignore keeps these out of the image:
| Left out | Why |
|---|---|
.env, .env.* (but .env.example) |
secrets: the host gives the settings |
.git, .github
|
history and CI |
vendor, **/node_modules
|
installed in the image, or not needed |
qa, tests, backups
|
development, tests and update backups |
claude-plugin, .claude, .claude-plugin, framework/design
|
tools for Claude Code and the design styles' sources |
*.log, .DS_Store
|
|
public/uploads/* (but its .gitignore) |
uploads live in a volume |
.caligrafy |
the Cloud sign-in and the marketplace listing |
php caligrafer.php deploy --wait ${CALIGRAFY_DEPLOY_WAIT:-60} || echo 'caligrafer deploy: the database is not prepared (see above)'; exec apache2-foreground-
php caligrafer.php deploy: the scheduled jobs line,.envcompiled to.env.php, then the database (it waits up toCALIGRAFY_DEPLOY_WAITseconds, 60 by default, for a database that starts at the same time). - Apache in the foreground, whatever the deploy step said: a database that is not ready does not keep the site down.
-
Its settings as a file at
/var/www/html/.env(G67): Caligrafy reads.env, and its values replace plain environment variables of the same name. Coolify mounts it as a file storage,docker runwith-v .env.production:/var/www/html/.env:ro, and Caligrafy Cloud writes it. Hosts that only offer environment variables (Railway, Render, DigitalOcean App Platform) are not supported yet. -
The production settings in that file:
APP_ROOT=(empty),APP_ENV=production,APP_DEBUG=false,APP_PROTOCOL=https, its ownAPP_KEYandAPI_KEY(php caligrafer.php generatekeys),DB_ACTIVATE=trueand the productionDB_*, and the keys of your services. The list and the reasons: Security: the production settings. - A MySQL database it can reach.
-
Two volumes (G70):
/var/lib/php/sessions(people stay signed in across deploys) and/var/www/html/public/uploads(uploads survive a deploy). -
HTTPS in front of it: a load balancer, Coolify's proxy, Caddy... The session cookie is
Securebehind a proxy that sendsX-Forwarded-Proto: https.
-
The build fails on Composer (G69):
composer.lockis missing or older thancomposer.json. Runcomposer updateand commit it. -
A Vite app is blank online: its
dist/is not committed. Runnpm run buildinpublic/<name>and commitdist/. -
Everyone is signed out after a deploy, uploads are gone (G70): no volume at
/var/lib/php/sessionsor/var/www/html/public/uploads. -
Settings given as environment variables are ignored (G67): give the container its
.envas a file. -
APP_ROOT=bookshelfonline: the site's links point to/bookshelf/....APP_ROOT=is empty in production. -
Pages are slow online:
APP_DEBUG=truein the production.env.
- Putting it online
- The deploy step
- Deploying to Caligrafy Cloud · your own server
- Security and upgrading
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)