Skip to content
dominicfollettPublic

About

Deploy small stateful apps to a single Linux box

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

Repository files navigation

conclave

Deploy small stateful apps to a single Linux box — a Raspberry Pi, a mini PC, a cheap VM — as one portable file that carries the code and its live database together.

BUILDING WITH CLAUDE

The problem this solves

Normally your code and your production data live in different worlds. Code flows one way, laptop to server. Data accumulates on the server, and you guard it and never pull it back. So when you want to test a change against real data, you invent a ritual: seed scripts, anonymised dumps, a staging database that drifted out of date months ago.

For a small app — a personal tool, a family thing, a side project with one SQLite file — that ritual costs more than the app does.

conclave inverts it. The unit you move around is a bundle: the app's code and its live state, in a single file that round-trips.

edit on laptop → load onto server (it runs) → eject (data comes back)
      ↑                                                    ↓
      └──────────────── open on laptop ←───────────────────┘

Because the data comes back with the code, production data simply is your dev fixture. Always current, no seeding ceremony. You test a migration once, against exactly the rows it will hit.

What's inside a bundle

A .conclave file is a system-container export containing:

  • the container's root filesystem — sealed; you don't edit this
  • /app — a git repo with your code. The commit history travels inside the bundle, so a bundle handed to you is a repo you can git log
  • /data — the live state, typically one SQLite file
  • /etc/conclave/manifest.yaml — a short manifest declaring the port to expose, resource limits, and a hook to run before capture

Two ways of remembering history, one physical artifact: git for code, retained bundles for state.

The commands

server (on the Linux box)
  conclave server              run the runner daemon

client (on your laptop)
  conclave connect <host>      pair with a server
  conclave ls                  list apps on the paired server
  conclave load <bundle>       import and start a bundle on the server
  conclave eject <name>        capture an app to a local bundle, then remove it
  conclave backup <name>       capture an app, but keep it serving
  conclave open <bundle>       explode a bundle into ./<name>/ for editing
  conclave pack <name>         splice ./<name>/ back into its bundle

One binary does both roles, so it's one download on each machine.

open and pack work directly on the tarball, which means your laptop never needs a container runtime installed — only the server does.

Design commitments

A few rules the implementation is held to, because they're what make this safe to point at real data:

  • Ejecting never destroys the only copy. Capture, retain the last few bundles on the host, stream to the laptop, and only then remove the instance.
  • One editable copy at a time. If it's ejected to your laptop, the server isn't still serving it.
  • Capture is stop-then-export, with a hook that runs first so a database can flush cleanly. No live checkpointing.
  • State lives strictly under /data, code strictly under /app.

Status

Early — not usable yet. The groundwork is done and the core premise is proven end to end by hand, but the commands above are still stubs.

Area State
Manifest parsing, CLI scaffold done
Development host (Incus in a local VM) done
Round-trip validated manually done — code and state survive export → delete → import, and a laptop-side edit plus a migration redeploy cleanly
Export format recorded + test fixture done
Runner daemon, client commands not started

If you're reading this hoping to deploy something today, come back later.

The design brief, build plan, and host runbooks are kept outside the repository while the shape of things is still moving.

Requirements

  • A Linux box running Incus — a Pi 5, an x86 mini PC, or a small cloud VM all work. Currently developed against 7.2.
  • Go 1.22+ to build.
  • Your laptop needs neither Incus nor Linux; macOS is fine.

Bundles are architecture-locked — an arm64 bundle won't start on an amd64 host — so pick one architecture and stay on it.

Repository tour

cmd/conclave/        the single binary, subcommand dispatch
internal/manifest/   conclave.yaml parsing and validation
internal/bundle/     bundle surgery (open/pack) — today, just its test fixture
conclave.yaml        the canonical manifest schema, annotated

The bundle fixture under internal/bundle/testdata/ is worth a look if you're curious about the format: it mirrors a real container export structurally — including the symlink, hardlink and odd ownership that break naive archive surgery — while being small enough to read. make-sample.py regenerates it byte-identically.

Prior art

Sandstorm grains, balena, and Fly Machines all circle this idea. conclave is the deliberately small version: one box, one binary, no orchestration, no separate state store. The tight coupling between code and state is the point, not an oversight.

License

Apache-2.0. See LICENSE.

About

Deploy small stateful apps to a single Linux box

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages