Clean-room back end for the official Firebase SDK

A self-hosted backend that speaks the official Firebase SDKs. One Go binary and PostgreSQL. Your apps keep the official SDKs; a few platforms need a small helper (see SDK packages).

Quick start · Status · Docs · SDK packages · Contributing

Aruma is a self-hosted replacement for Firebase. It is one Go binary with PostgreSQL and an embedded Next.js dashboard. It serves Firebase Auth, Realtime Database, Cloud Storage, Security Rules and the Document Database (Firestore-compatible) to the official Firebase SDKs, so for Auth, Realtime Database and Firestore on supported setups you change a config file and not your application code. Storage on iOS uses a patched build of the Storage SDK, Flutter Storage needs one helper call (fromArumaUrl), and servers that verify ID tokens use Aruma's admin libraries. See SDK packages.

It is for developers and teams who use Firebase and want to run the backend themselves, on a small VPS or on their own servers, with their data in a PostgreSQL they control.

Behavior is checked against real Firebase and the official emulators, and the official Firebase test suites run against Aruma. Differences we know of are documented in known differences.

Aruma is pre-1.0. The latest release is v0.4.0. Part of the Document Database's verification has not run yet; the changelog lists it.

With Docker (Aruma and PostgreSQL 18, nothing else to install):

git clone --branch v0.4.0 https://github.com/arumadev/aruma.git && cd aruma printf 'ARUMA_MASTER_KEY=%s\nPOSTGRES_PASSWORD=%s\n' "$(openssl rand -base64 32)" "$(openssl rand -hex 24)" > .env docker compose up -d docker compose logs aruma | grep code # the one-time setup code

Open http://localhost:8080, enter the setup code to create your first account, then create a project and an app and copy the config file. Keep .env: every key Aruma uses is derived from ARUMA_MASTER_KEY.

Without Docker, download the archive for your system from Releases (Linux, macOS and Windows, amd64 and arm64) and point it at your PostgreSQL 18, or build from source with Go 1.27.3 and Node 24 (make dashboard && make dev).

Getting started goes on from here: the three ways to install, running on a server, creating a project and an app, and signing a user in from a web app. Settings are in configuration.

Your app keeps the official SDK and takes the config file from Aruma. Where a platform has Google's hosts compiled in, a small package under sdk/ points the SDK at your server with one line of build or manifest configuration. The packages and what each one does are in SDK packages.

flowchart LR subgraph Apps["Your apps, official Firebase SDKs"] W[Web] I[iOS] A[Android] F[Flutter] N[Admin: Node, Go] end Apps -- "same SDK, new config" --> E subgraph Aruma["Aruma, one Go binary"] E[Single entry point] --> Auth E --> RTDB[Realtime Database] E --> Storage[Cloud Storage] E --> Docs[Document Database] E --> Console[Dashboard and Management API] end Auth --> PG[(PostgreSQL)] RTDB --> PG Storage --> PG Docs --> PG Console --> PG

Loading

Every project's data is reached through its project number, directly or through a project-scoped parent such as a Realtime Database id. A CI test fails any SQL query on a project table that neither filters by project nor carries a reviewed scope annotation. Aruma does not use PostgreSQL row-level security. See architecture.

Cloud Functions. Aruma does not serve Cloud Functions. If an app signs in with Aruma Auth and calls a function with httpsCallable, the SDK sends the user's Aruma ID token to Google. Do not use callable functions in such an app. See known differences.

Every Aruma server ships with a dashboard, embedded in the same binary. Create projects and apps, manage users, edit rules, browse data and files, and download the config files your apps need.

Getting started

Documentation index

Guides: web Auth, Admin Auth, Realtime Database, Cloud Storage, security rules, Firestore, Firestore migration, mobile apps, operations

Reference: configuration, compatibility, known differences, console API

Architecture, security, testing, benchmarks

Changelog

To report a vulnerability, read SECURITY.md.

Issues and pull requests are welcome. Start with CONTRIBUTING.md.

Apache License 2.0, see LICENSE and NOTICE. Firebase is a trademark of Google LLC. Aruma is not affiliated with Google and is not endorsed by it.