# melee

> Hosting for small, single-purpose, mostly-idle Ruby apps: each one is compiled to a native binary, kept asleep until someone asks for it, and woken in about two milliseconds.

This is the whole manual, in reading order. The markdown here is the canonical form; the same pages are
published as a site built with `mise run docs`. `reference/` pages live with the library they document, in
`stdlib/docs/`, and `reference/llms.txt` is a narrower index of just those, for writing app code.

Start with [melee](index.md).

## Understanding melee

- [What melee is](introduction.md): A place to put the small Ruby apps that are not worth a server: compiled to native binaries, kept asleep, woken on demand, and isolated from each other by the Linux kernel.
- [How a request reaches your app](how-it-works.md): From the browser to your route block and back: one supervisor, one warm process per app, and one short-lived child process per request.
- [If you know Rails or Sinatra](from-rails.md): What carries over, what is spelled differently, and the four habits that will not work here.

## Tutorial

- [Build and deploy an app](tutorial/index.md): A shared notes board, from an empty directory to a deployed URL, in six steps.
- [1. A new app](tutorial/new-app.md): `melee new`, the nine files it writes, and the development server.
- [2. Routes and templates](tutorial/routes-and-templates.md): A route that returns a page, a layout that wraps it, a partial it reuses, and why `<%=` and `<%==` are different.
- [3. A database](tutorial/database.md): Migrations are `.sql` files, queries take `?` binds, and rows come back as Hashes keyed by column name.
- [4. Forms, sessions and a login](tutorial/forms-and-sessions.md): A signed cookie, a `before` filter, and what CSRF is actually stopping.
- [5. Work that happens on its own](tutorial/durable-object.md): A durable object: state that outlives a request, and a timer that fires when nobody is visiting.
- [6. Deploying it](tutorial/deploying.md): `melee check` compiles it, `melee push` ships it, and `melee env` is where the secret goes.

## Guides

- [Background jobs and scheduled work](guides/background-jobs.md): There is no job queue and no thread. There is one durable object with one timer, and it is enough for more than it sounds like.
- [Structuring a larger app](guides/structure.md): `app.rb` for routes, `lib/` for everything else, plain top-level methods for helpers, and `case` wherever you would have reached for metaprogramming.
- [Logging people in](guides/authentication.md): A signed cookie, a constant-time compare, and three patterns that cover most small apps. There is no user system in the box.
- [Talking to other services](guides/outbound-http.md): `HTTP.get` and `HTTP.post`, with timeouts that matter more than usual, and no way to make two calls at once.
- [Static files and assets](guides/assets.md): Put files in `public/`. There is no asset pipeline, no fingerprinting, and no file uploads.
- [Working with the database](guides/data.md): One SQLite file per app, on the local disk, with one writer at a time. Migrations are files; rows are Hashes keyed by String.
- [Testing an app](guides/testing.md): There is no test framework. There is a script that runs your code under CRuby and under the compiler and fails if the two disagree.
- [When something breaks](guides/debugging.md): There are no backtraces in a deployed app. The log line and the route name have to be enough, so write them as you go.

## Reference

- [API reference](reference/reference.md): Every method an app may call, with its signature. Generated from `stdlib/sig/*.rbs`.
- [The app](reference/app.md): The shape of an app directory, the routes in `app.rb`, filters, and the life of one request.
- [Reading the request](reference/request.md): Every helper that reads the request being served: `params`, `session`, headers, cookies, bodies.
- [Writing the response](reference/response.md): What a route may return, and the helpers that build it: `render`, `redirect`, `halt`, `json`, `status`.
- [Templates](reference/templates.md): `.erb` files compiled to Ruby at build time, with their locals declared on line one.
- [Database](reference/database.md): The app's SQLite database: queries, binds, transactions, migrations as files, and the one-writer rule.
- [Durable objects](reference/objects.md): Named, long-lived objects with their own SQLite database and one timer, hosted by the app's worker.
- [Outbound HTTP](reference/http.md): `HTTP.get` and `HTTP.post`: the only way an app talks to another server.
- [Logging](reference/logging.md): Structured events with `log.debug/info/warn/error`, where the lines go, and what a 500 records.
- [Security](reference/security.md): What is on by default — escaping, CSRF, signed sessions, TLS — and the four helpers you call yourself.
- [The Ruby that compiles](reference/dialect.md): The Ruby that compiles: what the whole-program compiler forbids, and the workaround for each.
- [Working on an app](reference/dev.md): The commands you use while writing an app: `melee new`, `dev`, `check`, `push`, `logs`, `env`.

## Limits

- [What melee cannot do](limitations.md): The honest list: what the process model rules out permanently, what is simply not built yet, and when you should use something else.

## Operating melee

- [What a server needs](operating/requirements.md): 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.
- [Running melee-server](operating/running.md): One process, two ports, one directory. Every flag, what it defaults to, and the two it refuses to start without.
- [Deploys and releases](operating/deploys.md): A push is source. The server compiles it, writes a new release directory, swaps a symlink, and stops the old process. Nothing is atomic-er than a `rename`.
- [Keeping it safe](operating/security.md): What the sandbox actually stops, what it does not, and the four things you have to do yourself.
- [Logs, backups and upgrades](operating/day-to-day.md): One NDJSON file per app that nothing rotates, a home directory nothing backs up, and an upgrade path you have to think about because the compiler is pinned.
- [Standing up a real server](operating/production.md): The recipe actually run against a Hetzner CPX12 (1 vCPU, 2 GB, x86_64), Debian 13, on 2026-09-15: get the code there, install, start, push from a laptop, check it, back it up, and know what to do when it breaks. Where a step has not been fully verified yet, that is said plainly rather than papered over.

## Appendix

- [Where the rest of the documentation lives](appendix/repo-docs.md): This manual is for people using melee. The repository holds a second set of documents, written for the people building it.