Verified against Semitexa Ultimate 2026.10.19.0811

Upgrading

A Semitexa project upgrades with one command, run from the project directory while the stack is up:

bin/semitexa update --dry-run
bin/semitexa update
bin/semitexa server:restart

See it first

update --dry-run changes nothing. It prints:

  • every semitexa/* package that will move, from the version you have to the one the newest release pins;
  • what happens to each scaffold file (bin/semitexa, the docker-compose*.yml files, .env.default, the agent docs such as AGENTS.md and CLAUDE.md, the phpstan configs): already current, replaced, or left alone because you changed it;
  • the database schema changes and data patches that will run.

What update does

In this order, and it stops at the first stage that fails:

  1. Preflight. Read-only checks before anything is touched: the database answers, there is disk space, composer.json and composer.lock are readable, and var/ is writable. A failed check stops the update with nothing changed.
  2. Packages. Every semitexa/* package moves to the version the newest semitexa/ultimate release pins — the set that release was tested as. Composer runs inside the containers; if it fails, composer.json, composer.lock and vendor/ are put back as they were.
  3. Itself first. When the release brings a newer semitexa/update, the command stops after the package step and runs again on the new code, so the remaining stages are the new release's. You see this as a note in the output; it is not an error.
  4. Scaffold files. A file you never changed is replaced with the new release's version. A file you did change is left as it is. For the agent docs (AGENTS.md, CLAUDE.md and the like) the release's version is written next to it as <file>.new; any other changed file is only reported (manual_review) — see below.
  5. Database. Data patches and the schema sync for the new release, the same as orm:sync. A destructive schema change (a dropped column, a narrowed type) is refused unless you pass --allow-destructive.
  6. Health check. When SEMITEXA_UPDATE_HEALTHCHECK_URL is set, the update counts as successful only if that URL answers. Without it this stage is skipped.
  7. Journal. The run is recorded: bin/semitexa update:history lists past runs and their outcome.

Then server:restart, so the workers load the new code.

The .new files

A .new file means: your file differs from the one this release ships — because you changed it, the release changed it, or both. An edited agent doc therefore gets a fresh .new on every update, whether or not the release touched it. Compare the two and carry over what you need — for example:

diff CLAUDE.md CLAUDE.md.new

Keep your file, take the new one (mv CLAUDE.md.new CLAUDE.md), or merge them by hand, then delete the .new. Nothing reads a .new file; it is only there for you.

Some files are only reported, not written as .new, when you changed them (the dry run says manual_review). bin/semitexa update --write-scaffold-candidates writes their .new files too.

Check the result

bin/semitexa self-test
bin/semitexa update:changelog
  • self-test should report no errors.
  • update:changelog shows which package versions changed.
  • Open the app: your own modules and pages are untouched by the upgrade; only semitexa/* packages and the scaffold files above are.

Why this matters

An upgrade a project cannot see coming, or that writes over the files it changed, is one that gets put off. One command that shows its plan, leaves your edits in place and records what it did keeps a project on the current release.

Have a product idea?One free MVP every month