Sbarbase documentation
Sbarbase develops operations for many Supabase projects on one server, including tested backup, restore and upgrade workflows. The docs are split by what you need right now. Start with why if you are new, or with status if you want to know what works.
Four sections, one purpose each, and the engineering notebook underneath.
Words used throughout: a client (called an organization in the code) owns projects; each project has environments such as production and staging. "Your server" is what the code calls the installation. The environment is the unit of isolation, move and restore. Unfamiliar terms are in the glossary.
Explain: why it works this way
Read these to understand the design. Each page has the same shape: what it is, why, how we built it, limits, and where to go deeper.
- Why Sbarbase: the problem, the existing alternatives and what is different here.
- Architecture: the request path and what is shared versus separate.
- Hierarchy: clients, projects and environments, and why ownership is separate from placement.
- Isolation and trust: what is a shared failure boundary and who is trusted.
- Threat model: assets, attackers, trust boundaries, the check behind each mitigation and the known gaps.
- Recovery: fence, export, restore, verify, switch.
- Provisioning: why a crash never causes work to run twice.
Guides: how to do something
- Install with Docker: the main install, from a bare Ubuntu 26.04 machine to a running console, as rehearsed in a local VM.
- Quickstart: the install without Docker, from an empty server to a supabase-js call, as rehearsed in a local VM.
- Choosing a server: what to buy, and what the free options really give you.
- Local lab: run the stack on your own machine for evaluation.
- Operator setup: create the first operator and client.
- Server deployment: the server runbook and its known gaps.
- Realtime: database changes, broadcast and presence per environment.
- Move from Supabase: copy a Supabase project, users and files into a new environment with one command.
- Database access: a PostgreSQL connection string per environment for migrations, psql and ORMs.
- AI agents and the API: access tokens, the MCP endpoint and the Supabase-compatible API, so Claude Code, Cursor or Codex can deploy here.
- API keys: publishable keys for apps, secret keys (
service_role) for servers and agents. - Signing key: rotate an environment's JWT signing key when it may have leaked.
- Edge Functions: deploy a Supabase functions folder to an environment and call it with supabase-js.
- Logs and metrics: requests, errors, response times and service logs per environment.
- Sign-in settings: site URL, redirect addresses and OAuth providers (Google, GitHub, Apple and others) per environment.
- Supabase Studio: open the original Studio for one environment, behind the console login, through an SSH tunnel or on its own public address.
- Backup and restore: the current operator workflow, including scheduled backups and bounded offsite recovery.
- Pausing writes: stopping application writes to one environment before work whose way back restores a backup.
- Upgrades: updates from the console, opt-in automatic updates and the command line, with an automatic way back.
- The sbarbase command: status, backups, restore, environments, keys, upgrade, Studio and logs from one command.
Reference: facts to look up
- Status: the single place for what works and every number, with dates and commands.
- Project layout: repository folders and the current documentation entry points.
- Glossary: every internal term in one or two sentences.
- Configuration: files, flags and environment variables an operator touches.
- API: management and gateway routes.
- Deployment readiness: the itemised server readiness matrix.
- Console design: the console's Supabase design tokens, navigation and server snapshot.
Decisions
- Decision register: each choice, the alternative and the conditions for reconsidering it.
Engineering notebook
docs/engineering holds the detailed notes written while building each mechanism: designs, crash tests, reviews, plans and the chronological checkpoints. They are precise and dated, and some are superseded by later notes. Read them when an explain page links you there or before changing that subsystem. Notes for coding agents continuing the work are in engineering/handoff.
Also kept here: evidence (JSON written by live probes, cited by status), diagrams and the console design record.
Current direction
The active work is the upstream currency plan, and a real server runs main (status). The project goal, October product plan and execution method guide current development. The native placement contract separates experimental dedicated placement from the existing shared topology. The evidence ledger records scoped passes and refusals, including local packets that are not distributed with the repository. A source publication is not production release acceptance.