What a server needs

A Linux machine, root, Ruby, a built Spinel compiler and a checkout of melee. There is no package to install, and that is the biggest thing standing between melee and other people running it.

Be clear about the stage first. melee has only ever been operated by the person who built it. There is a working server, a working deploy, and a real sandbox; there is no installer, no systemd unit, no TLS and no backups. Everything on this page is true and none of it is a product.

The machine


OS	Linux. The sandbox is seccomp, Landlock, namespaces and cgroups v2 — all Linux. `melee-server` runs on macOS but applies no sandbox whatever the flags, so macOS is for development only.
Kernel	Linux 6.7 or newer, and cgroups v2. melee asks for Landlock ABI v4 as a hard requirement, so an older kernel makes the server refuse to sandbox rather than sandbox weakly. A current Ubuntu or Debian is fine.
Privileges	root, if you want the sandbox to be worth anything: only root can give each app a uid of its own, and only root can set cgroup limits. The server refuses to start as root without `--app-uid-range`.
Architecture	x86-64 or arm64.
Disk	Small. Each release is a binary of a couple of megabytes plus the source; the databases are yours.
Memory	Each app is capped at 128 MB by default and idle apps are stopped, so the server’s own footprint plus a few tens of megabytes per active app.

What has to be on it

Ruby 4.0, with the sqlite3 gem. The build step (stdlib/bin/melee-build) is a CRuby script that the server shells out to on every deploy. Not needed to serve — only to build.

The gem is easy to miss and the failure is silent: the build step checks each migration by running it against a scratch database, and without sqlite3 that check is skipped, not failed. A server missing it builds happily and a migration with a typo first fails when the app next opens its database. gem install sqlite3.

The Spinel compiler, built from the commit melee is pinned to. It is a git submodule; you build it with make deps && make inside it. This is the part with no shortcut: there is no release binary to download.

A C compiler and libssl. Spinel emits C and links it; the app binary depends on libc, libm and libssl.

A checkout of the melee repository, because the server needs the standard library sources (--stdlib) and the build script. This is the honest core of the packaging problem: the server is not self-contained.

The two melee binaries, melee-server and melee, built with cargo build --release.

Getting them

From a checkout, with mise for the toolchains:

git clone --recurse-submodules <the melee repository>
cd melee
mise run setup          # tools, the Spinel submodule, the sqlite3 gem, a Spinel build
mise run build          # melee-server and the melee CLI into supervisor/target/release

mise run setup is written for a development machine. On a server you want the same three things: the toolchains, a built vendor/spinel/bin/spin, and cargo build --release.

What the CLI needs, on your own machine

melee runs where you write the app, not on the server. It needs to find the standard library, which it does through MELEE_STDLIB, a walk up from the app directory inside a checkout, or its own binary’s location. Outside a checkout, none of those work.

melee dev additionally needs Ruby and the sqlite3 gem: it runs the app under CRuby and never invokes the compiler. melee check needs a built Spinel on top of that, because it compiles the app locally.

melee push, melee logs, melee env and the rest only need the binary and network access to the control API.

What is missing, specifically

These are P-03 and P-06 in the project’s own TASKS.md — packaging, and a deployment recipe. Until they exist:

there is no versioning story between the CLI, the standard library and the Spinel pin, and a mismatch is a miscompile rather than an error;
there is no service unit, so keeping the server running across reboots is yours to arrange;
there is no TLS anywhere, so the control API’s token and every melee env value cross the network in the clear unless you put something in front.

Running melee-server — the flags and what they mean.

Keyboard shortcuts