Servers, databases and caches

This handbook covers MixLab through the mix command line. If you would rather work in a graphical interface, you already have one: every installer places the MixLab window beside the command line. Both drive the same MixEngine underneath, so everything in this handbook still applies.

Two words, kept apart the way MixLab keeps them apart.

A package is a program MixLab knows how to run, such as Caddy, MariaDB or Redis. Installing one puts a copy of it in MixLab's own directory and does nothing else.

A service is a running instance of a package: a port, a data directory, a generated configuration, a log, and a state. mariadb@main and mariadb@legacy are two services of one package, with different ports, different data and possibly different versions.

What is on offer

Nothing arrives by itself. A fresh MixLab has no web server until you install one, and "default" above means the one this project recommends when there is a choice, not the one that is already there.

Installing and creating

mix package available
mix package install mariadb 12.3.2
mix service create mariadb@main 12.3.2

The part of a service id before the @ is the package it is an instance of, which is why mix service create needs no separate argument for it. The part after the @ is yours: it is what tells two of them apart, and MixEngine attaches no meaning to the words. Caddy runs once for a whole MixEngine home, so its service is simply caddy with no @ at all.

The name does not have to say which version a service runs. mix service list shows the version beside each id, and so does MixLab, so mysql@main is enough.

The id cannot be changed afterwards, because it is also the name of the generated configuration directory, the log directory, the socket and the address the password is stored at. To rename a service, create the new one and delete the old one; the data is kept.

Useful flags on mix service create:

Who gets 3306

MariaDB and MySQL want the same port, and so do two instances of either. The rule is one rule: first created, first served. The first to ask for 3306 gets it; the next gets the first free port above. MixLab reports the port it chose, because a port you did not pick is one you have to be told about.

A port you name explicitly is taken at your word, with no allocation at all.

One data directory, one service

mix service create refuses a --data-dir another service already holds, and names who holds it. Two servers over one set of files corrupt them, and that cost lands on your data rather than on a start that fails.

Running them

mix service list
mix service status mariadb@main
mix service start mariadb@main
mix service stop mariadb@main
mix service logs mariadb@main --follow

mix service status requires an id where start and the rest take an optional one: a status with no subject is a list typed wrongly, and answering it as a list would hide that.

Deleting a service takes the row and the configuration generated from it, and never the data, because that is somebody's databases. The answer names the directory that was left, so nobody has to go looking:

mix service delete mariadb@legacy

From the tray

MixLab has an icon in the tray (Windows), the menu bar (macOS) or the system tray (Linux), whichever modules you use. With MixEngine on, a click on Windows and macOS slides a panel into the corner of the screen, beside the taskbar or under the menu bar. On Linux a click opens a short menu, and Open control panel opens the same panel as a small window, because Linux does not tell an application about clicks on its icon. Without MixEngine there is no panel, and a click brings MixLab's window back.

The panel's header has Open MixLab and a power button that quits MixLab. Below it, the MixEngine card shows CPU and memory and ends with Stop MixEngine, which asks you to confirm first. Then come your services with Start and Stop, Stop all, and your sites (a click opens one).

On Windows and macOS a right click on the icon opens Open MixLab and Quit MixLab.

Closing MixLab's window only hides it, so terminal sessions and database connections stay open. To quit, use the icon's menu, the power button in the panel, or ⌘Q on macOS. Quitting MixLab leaves MixEngine running.

To have the icon after you log in, turn on Open MixLab in the tray when I log in in Settings → General. This is a separate switch from Start MixEngine when I log in (mix autostart), and you can turn on either one or both.

On GNOME the icon needs the AppIndicator and KStatusNotifierItem Support extension. Ubuntu includes it; Fedora and plain GNOME do not. Without it there is no icon, closing the window quits MixLab as before, and the login switch opens the window instead.

On a Linux server nobody logs in to, turn on Also start at boot, before anyone logs in under Settings → MixEngine, or run mix autostart enable --at-boot. MixEngine then comes back after a reboot by itself. It does this through your account's systemd linger, which needs no administrator on most systems; if yours refuses, run sudo loginctl enable-linger $USER once. A service starts along with it only if its own autostart is on, which mix service list shows.

Updating a server to a newer patch

mix package available lists servers one row per line too, and names an update above the table the same way runtimes do.

mix package upgrade mariadb 11.4.5 --dry-run
mix package upgrade mariadb 11.4.5

Each instance of the old version is stopped, moved to the new one and started again, one at a time. Its data directory, port, password and settings stay as they were. If an instance does not start on the new version, it goes back to the old one and is started again, and the update ends as failed with the reason. The old version is removed once every instance has moved; --keep keeps it.

An update stays inside its line, where the data format does not change. MySQL 8.0 cannot go back, though: once a newer 8.0 patch has opened the data, an older one cannot, and the plan says so before you agree.

Updating Caddy or Nginx restarts it, so your sites do not answer for a moment. On Linux the new program needs permission to answer on ports 80 and 443, and MixLab asks for it before it stops anything.

Which web server your sites go through

One of Caddy and Nginx is your front end at a time: every site in the home is reached through it, and mix service front-end says which one it is.

mix service front-end

Changing it is one command, and it is a real operation rather than a setting: the server you are on is stopped, its row goes, every site is rendered for the new one, and that one is started.

mix package install nginx 1.27.3
mix service set-front-end nginx

No site is reachable while that happens, so mix tells you what is about to happen and asks before it starts. Pass --yes in a script.

On Linux the new server needs permission to answer on ports 80 and 443, and that permission belongs to the program rather than to MixLab, so moving to a different program means asking for it again, and a prompt may appear. If nobody allows it, nothing changes: you stay on the server you were on, MixLab says so, and mix elevation grant followed by the same command finishes the job. macOS and Windows need no second permission.

Two things do not travel with the switch, and MixLab names them rather than dropping them quietly: settings you had overridden (an nginx.conf setting means nothing to Caddy), and any limits or idle policy you had set on the old server. The old server's data directory is left exactly where it was.

Databases and accounts

Making a database is one command, and it starts the server if it is not running:

mix database create mariadb@main --name blog
mix database create mariadb@main --name shop --user shop_app

Nothing prints the password by default. It is generated and put into your operating system's own credential store (Credential Manager on Windows, the Keychain on macOS, the Secret Service on Linux), and what is printed is the address it was stored at, as the store's own name and key. That is what lets a client tell you "stored in your credential store as …" without anybody hardcoding MixLab's naming.

When a project needs the password itself, most often for a .env file, mix database credentials prints it, and --password on create lets you choose it instead of letting MixLab generate one:

mix database credentials mariadb@main --user blog
mix database create mariadb@main --name shop --user shop-app --password

Without a value, --password prompts and reads one line from standard input, so it also works piped: echo secret | mix database create … --password. Choosing a password for an account you already made changes what is stored, and the server is realigned to it the same way it already is when a password drifts. An account already on the server that MixLab holds no credential for is still refused, even with the correct password.

To open the database in a desktop client:

mix database client mariadb@main   # what is installed, and where this system looked
mix database open mariadb@main     # open it

client reads only: it starts nothing and opens nothing, and "no client installed" is an answer rather than a failure: it names where MixLab looked and where to get one.

open starts the instance if it is stopped, reads the password from the credential store at that moment, and hands it to the client in that process's own environment. It is never printed, never put in an argument, and so never in your shell history.

What a service may take, and when it stops

mix service limits mariadb@main
mix service limits mariadb@main set --memory 512 --cpu 50
mix service idle mariadb@main --after 30m

limits with no subcommand reads; set replaces; clear removes. set replaces every field, not only the ones you name. set --cpu 50 clears a memory ceiling that was there, so it prints all three fields of the result, and a cleared limit is on your screen rather than a surprise. What your operating system will actually enforce differs, and the answer says which of the two you have: a hard ceiling is a wall: at it, the service is killed or its next allocation fails. An advisory one is a watched line the service may cross, after which MixLab warns and, where the recipe permits, restarts.

idle says when a service is stopped for being unused, and what is currently holding it open. Nothing is stopped for being idle unless you ask: a site that is up stays up. To save battery, turn on Save battery in MixLab's Settings, or run mix service save-resources --on; a PHP pool nobody used for half an hour, or a database or cache for an hour, is then paused, and the next request that needs it starts it again. That first load can take a second. mix service idle gives one service its own time either way, and --after 0 means never.

The web server itself is never stopped for being idle, and it starts with MixEngine.

The generated configuration

MixLab writes the configuration for every service it runs, out of what it knows. Those files are disposable: they are regenerated and never read back, so there is nothing there for you to edit and nothing to keep in sync. If a setting you need has no flag, that is a gap in MixLab rather than an invitation to edit the file.

This page as Markdown: https://mixnz.github.io/mixlab/en/services.md