Blueprints

This handbook covers MixEngine through the mix command line. If you would rather work in a graphical interface, download the MixDB app at https://lab.mixnz.com/#mixdb. MixDB drives the same MixEngine, so everything in this handbook still applies.

A blueprint is a written record of what a project is made of: which PHP it wants, which services it uses, what its site looks like, and optionally a command that scaffolds a fresh copy. It is how you set the same environment up twice — on a second machine, for a colleague, or for the next project of the same shape.

Capturing one

cd ~/code/blog
mix blueprint capture blog-stack --description "PHP 8.3, MariaDB, Redis"
mix blueprint list

The name is what it is filed under — lower-case letters, digits and hyphens.

What a blueprint carries is the shape, not the contents. It records that the project uses a MariaDB and which version; it does not record your data, and it never contains a password. Applying one gives you the same environment, not a copy of your work.

Applying one

mix blueprint apply blog-stack --project shop --dry-run
mix blueprint apply blog-stack --project shop

Run the dry run first. It prints the plan and changes nothing: which runtimes would be installed, which services would be created, what the site would be called, and — where there is one — the scaffold command that would be executed. Nothing about an apply is hidden from that plan.

--path says where the new project goes; it defaults to a directory named after the project, under where you are.

Answering the version questions

A blueprint asking for PHP 8.3 on a machine that has 8.2 is a question, not a failure. Two flags answer it up front for every such question in the plan:

Importing somebody else's

mix blueprint import ./blog-stack.toml

A blueprint from elsewhere may carry a detached signature — mix looks for <file>.minisig beside it, or takes --signature. And here is the rule that matters:

What arrives without a signature the gallery vouches for is untrusted for good. Nothing raises that afterwards. Importing it again with a signature does not launder it; the trust state is decided once, at import, and every listing that names the blueprint shows it.

That state is not decoration. It decides how loudly the blueprint's [scaffold] command has to be agreed to before it runs.

The scaffold command, and why it is asked about

A blueprint may carry a command to run once in the new project — composer create-project …, or the equivalent for whatever framework it is for. That is somebody else's program running on your machine, so MixEngine prints the exact command and asks before running it, and it asks differently depending on where the blueprint came from.

Two flags skip the question, and neither covers the other:

A script that runs somebody's unsigned command should say so on the line that does it. That is the entire reason there are two flags rather than one, and the command is printed before it starts in both cases.

Watching an apply

An apply is a job. It may install runtimes, create services and run a scaffold, so it can take a while:

mix job list
mix job status <id>
mix job logs <id>
mix job wait <id>

mix job logs is where the scaffold command's own output goes — that is the one thing an apply runs that prints anything of its own. The lines live for as long as the daemon keeps the job, so it is what to read while one runs rather than a record to come back to next week.

If the apply needs an administrator — a new domain that needs routing, say — it asks once at the end. --grant spends that prompt without asking first.

This page as Markdown: https://mixnz.github.io/mixengine/en/blueprints.md