Repository navigation
The Deploy Step
The deploy step is php caligrafer.php deploy: what a project runs each time it starts in production, before
Apache serves it. The production image runs it
for you. It compiles the settings and brings the database up to date: the framework tables, your create_db.sql
scripts when they are new or changed, then your migrations. Since 2.4.0 (migrations 2.18.0, .env.php 2.19.0).
/caligrafy-quill:deploy
Before a deploy, the skill checks what the deploy step will run: every create_db.sql safe to run twice, the
migrations in order, the schedule file valid. After one, /caligrafy-quill:ship reads the start-up log.
Check before you say OK: the log of the start has only OK and SKIP lines, and no FAIL.
On a server without Docker (files copied to PHP and Apache), run it yourself after each copy:
php caligrafer.php deploy
php caligrafer.php deploy --wait 120 # wait up to 2 minutes for the databaseOn your computer, run it against a production-like settings file to see what it would do:
docker compose exec dev-box php caligrafer.php deploy --env .env.staging Caligrafy deploy
caligrafy-schedule {"version":1,"jobs":[]}
OK Settings: .env compiled to .env.php (read without parsing on every request)
OK Framework tables: tokens, audit log, job runs, jobs, cache, migrations, scripts
OK application/models/Auth/create_db.sql: up to date
OK application/models/Bookshelf/create_db.sql: changed: run again
OK Migrations: 1 run: 20261107232335_add_books_isbn.sql
--envreads the database settings of that file; theSettingsline always compiles the project's own.env.
From Caligrafy\Deployer::run():
-
The scheduled jobs line.
caligrafy-schedule <json>: the listing ofschedule list --json, which Caligrafy Cloud reads from the log to run the jobs. A schedule file with problems printscaligrafy-schedule-invalid <the problems>instead, and its jobs do not run. Without the file the list is empty. -
The settings.
.envcompiled to.env.php(Deployer::cacheEnv(), the same asenv cache): pages read the settings without parsing.envwhile.envkeeps that content. Without.env:SKIP Settings: no .env to compile. -
DB_ACTIVATE. Nottrue:SKIP Database: DB_ACTIVATE is not true: nothing to prepare, and it stops there with exit code0. -
The database. It tries to connect every 2 seconds until
--waitseconds have passed (60 by default; the image passesCALIGRAFY_DEPLOY_WAIT). Never reached:FAIL Database: not reachable after 60 s: check the DB_* settings, exit code1. -
The framework tables.
framework/settings/platform.sql(every tableCREATE TABLE IF NOT EXISTS: tokens, the audit log, job runs, notifications, jobs, the cache, migrations, Snap), andcaligrafy_scripts, which records the scripts that ran. -
The
create_db.sqlscripts. Everyapplication/models/<folder>/create_db.sql, in folder order:The script Line What happens never ran here OK <path>: runit runs, and its SHA-256 is recorded ran, and has not changed OK <path>: up to datenothing changed since it ran OK <path>: changed: run againit runs again, and the new SHA-256 is recorded changed, and drops, deletes or truncates WARN <path>: changed, but it drops or deletes data: not run (php caligrafer.php sql <path> runs it)nothing: run it by hand when you mean it "Drops or deletes" is
DROP TABLE,DROP DATABASE,DROP SCHEMA,DROP VIEW,DROP COLUMN,DELETE FROMorTRUNCATE, comments left aside (Deployer::destructive()). A statement that fails only because what it adds is already there (a duplicate column, key name or foreign key: MySQL errors 1060, 1061, 1826) is skipped, so a script keeps itsALTER TABLE ... ADDlines and runs again. Other files (seed.sql...) are never run. -
The migrations. When
application/migrationshas files, the ones that never ran, in order:OK Migrations: 1 run: <file>, orOK Migrations: up to date. A migration edited after it ran:WARN Migrations: <file>: changed after it ran, not run again (write a new migration for the change).
Any SQL error in steps 5 to 7 prints FAIL Database: <the error> (a migration names its file and statement) and the
exit code is 1. The image starts Apache anyway, after caligrafer deploy: the database is not prepared (see above).
Because a changed script runs again on the next start, each create_db.sql must be safe to run twice:
CREATE TABLE IF NOT EXISTS `books` (
`id` INT UNSIGNED NOT NULL AUTO_INCREMENT,
`title` VARCHAR(255) NOT NULL,
PRIMARY KEY (`id`)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4;
-- added later: skipped once the column is there
ALTER TABLE `books` ADD COLUMN `isbn` VARCHAR(20) NULL;For a change to a table that holds data, prefer a migration: it runs once, in order, and says so.
-
A script that drops its table first (G68): it ran once; changed, it is never run again (
WARN), and run by hand it deletes the data. UseCREATE TABLE IF NOT EXISTSand added statements. -
caligrafer deploy: the database is not prepared: the line above it says why: the database is not reachable (theDB_*settings, or a longer--wait), or a SQL error that names the statement. -
Host ... is not allowed to connect(G71): the database was created but its user was not, often a MySQL killed for lack of memory while it initialized. Give it more memory, and recreate its volume while it holds no data. -
A setting changed on your own server is ignored:
.env.phpwas compiled from the old.env, and is used only while.envhas that content; an edited.envis read again. Restart the container, or runenv cache. -
Scheduled jobs do not run on Cloud: the log has
caligrafy-schedule-invalid: runphp caligrafer.php schedule listto see the problems.
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)