Your first site

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.

This walks the whole path once: a PHP version, a web server, a project, a site, and a certificate your browser accepts. It assumes MixEngine is installed — Installing MixEngine if it is not — and it assumes nothing else.

1. Check the daemon

mix status

The first mix command starts the daemon if it is not already running, so this is also how you find out that the install worked. What comes back is the daemon's version, where its home directory is, and what it is supervising, which at this point is nothing.

2. Install a PHP

MixEngine ships no runtimes: it downloads the versions you ask for, and only those. See what is on offer, then take one:

mix runtime available --kind php
mix runtime install php 8.3.33

The version is exact rather than a range, deliberately — 8.3 would be asking MixEngine to choose between versions none of which are on the machine yet. mix runtime list shows what you now have.

3. Install and create a web server

A package is a program MixEngine knows how to run; a service is a running instance of one with its own configuration. Caddy is the default front end:

mix package available
mix package install caddy 2.11.4
mix service create caddy 2.11.4
mix service list

Versions move: take one from what mix package available actually lists rather than from this page. Caddy runs once for the whole home rather than once per site, which is why its service id has no @name on it — mariadb@main names an instance, caddy names the only one there is.

4. Register a project

A project is a directory MixEngine knows about. Go to the one you want to serve — make an empty one if you are just trying this out — and register it:

mkdir -p ~/code/blog && cd ~/code/blog
echo '<?php phpinfo();' > index.php
mix project create

With no arguments it takes the current directory and names the project after it, so this one is called blog.

5. Declare a site

mix site create --domain blog.test --kind php-fpm --https true

This is the step that asks for permission, and on a fresh machine it is the only one that does. MixEngine needs the name blog.test to reach your own machine, and it needs your browser to trust the certificate it is about to issue. It collects both — and the grant to listen on port 80 and 443, where that is privileged — and raises one prompt for all of them. If you want to see exactly what is being asked for before you agree, mix elevation status prints it; What MixEngine asks permission for explains each one.

Declining is a supported answer. The site is still created and still served over http://.

6. Open it

mix site list

Then open https://blog.test in a browser. You should get phpinfo() and a padlock with no warning behind it. If the padlock is not green, ask the server rather than guessing:

mix cert status

That opens a real TLS connection to your own front end for every site and reports the certificate it actually presented — which is the only thing a browser ever sees.

7. Add a database, if the project needs one

mix package install mariadb 12.3.2
mix service create mariadb@main 12.3.2
mix database create mariadb@main --name blog

The last command makes the database and an account that reaches it. Nothing prints the password: it goes into your operating system's own credential store, and what is printed is the address it was stored at. mix database open hands it to a desktop database client without it ever appearing in a shell history or an argument list.

What just happened

• MixEngine downloaded one PHP and one web server into its own directory. Nothing was installed system-wide, and no other version of anything on your machine was touched.
• It generated a certificate authority, asked once to have it trusted, and issued a 90-day certificate for blog.test — and it will reissue that certificate before it expires without being asked.
• It wrote the web server's configuration itself. That configuration is disposable: MixEngine regenerates it from what it knows, so there is no file for you to keep in sync.

Where to go next

• Projects and sites — the two nouns, and what each one owns.
• PHP, Node, Python and Ruby versions — how a directory chooses its own version.
• Servers, databases and caches — everything a project runs against.
• Names and the padlock — how blog.test resolves, and what signed it.
• What MixEngine asks permission for — every prompt, and what it changes.
• When something is wrong — mix doctor first.

This page as Markdown: https://mixnz.github.io/mixengine/en/getting-started.md