Self-hosting overview
Deploy BuildBase on your own infrastructure, with your end users' data in your own database.
What is Self-Hosted?
Self-hosted mode lets you run the BuildBase platform on your own infrastructure - your cloud, your data center, or on-premises. You host three services (tenant server, client app, and auth portal) while we manage the central server that handles licensing, organization management, and admin authentication.
How It Works
BuildBase uses a split architecture:
- Central Server - Managed by BuildBase. Handles organization management, admin authentication (Google OAuth), installation licensing, and ES256 key management. You never host this.
- Tenant Server - Hosted by you. Stores and processes all your organization's data - users, emails, workflows, subscriptions, and more.
- Client App - Hosted by you. The web dashboard your team uses to manage content and data.
- Auth Portal - Hosted by you. The authentication pages for your app users (login, signup, password reset).
Your end users' accounts and application data stay in your own MongoDB. The installation stays connected to BuildBase: the central server signs your team in to the console, manages your organizations, receives a status check-in every five minutes and is told about plan changes. Visitor IP addresses are sent to IPinfo for location lookups unless IP_INFO_MODE is set to disabled, and uploaded files go to a Google Cloud Storage bucket you own.
Licensing and the connection to BuildBase
The installation's ID and API key are its licence. What each state does:
| State | Your end users | Your team in the console |
|---|---|---|
No INSTALLATION_ID or INSTALLATION_API_KEY | The tenant server does not start, and says which variable is missing | - |
| Wrong or regenerated key | Unaffected | The server cannot check in or read its organizations from BuildBase, and the installation shows as disconnected. It logs [CentralAPI] central refused ... once, and once more when accepted again. Put the current key in .env.selfhost and restart |
| BuildBase cannot be reached | Unaffected: sign-in, sessions and your app keep working | Existing sessions keep working; signing in again waits for BuildBase |
| Self-hosting plan lapsed | Unaffected | Opening the organization can be refused, with a message saying to renew |
Installations
An Installation is a self-hosted server instance - one Docker Compose stack running on your infrastructure. Each installation:
- Gets a unique API key for secure communication with the central server
- Can serve multiple organizations (e.g. different teams, projects, or clients)
- Has its own database, Redis, and server configuration
You can create multiple installations for different purposes:
- By region - EU Production, US Production
- By environment - Production, Staging
- Multiple orgs on one server - simplicity for smaller deployments
- Dedicated per org - maximum isolation and throughput
Installations are managed from the BuildBase Dashboard under Account, then Installations.
Your installation allowance
How many installations you can run, and how many organizations each can hold, depends on the self-hosting plan on your own account. Self-hosting is licensed per installation, and the allowance belongs to you, not to an organization.
The Installations page shows it as "n of N installations, up to M organizations on each". Creating one past it is refused. Self-host is priced per installation, and is arranged by talking to us. At the limit, the page links to Account > Billing to change your plan, or says to contact support where no plan sells more.
On an installation's page you can:
- Assign an organization, or Detach one. Assigning moves it off any other installation. If the two installations use different MongoDB databases, the organization starts on the new one without its data until you migrate it. On the same MongoDB and Redis, the move needs no migration.
- Reattach a detached organization. A self-hosted organization on no installation runs nowhere. The console will not open it, and its users reach it again only once it is attached. The Installations page lists it under Detached organizations with a Reattach button.
- Regenerate the API key. The old key keeps working for a grace period of up to 60 minutes, while you update
.env.selfhost. The new key is shown once. - Test connection to the server URL, and see the connection state and the version the installation last reported.
- Delete the installation. Its key stops working at once and its organizations are unassigned. Their data is not deleted.
BuildBase can set a minimum version for the tenant server, the server you run. If your installation reports an older image, or none, the console won't open its organizations until you pull the newer image and restart. It names the version to update to. Only the console checks this: your installation keeps serving your end users meanwhile.
Requirements
| Requirement | Details |
|---|---|
| Server | Linux (Ubuntu 20.04+ recommended), 2 GB RAM, 2 vCPU minimum |
| CPU architecture | x86-64 (amd64) or 64-bit ARM (arm64) |
| Docker | Docker Engine 20+ and Docker Compose v2 |
| Database | MongoDB 7+ (included in quick start, or bring your own) |
| Redis | Redis 7+ (included in quick start) |
| Network | Public IP or domain name with ports 80/443 for production |
| Enterprise SSO (optional) | A public HTTPS SERVER_URL, so WorkOS can send the browser back to the sign-in callback, and outbound HTTPS to api.workos.com. No inbound connection from WorkOS is needed. A company's log streams sent by BuildBase need outbound access to its own SIEM (an HTTPS endpoint, Datadog's logs intake, or a Splunk HTTP Event Collector); a self-hosted server may also send to a private address over HTTP. With company audit logs on, the trail goes to api.workos.com too, and a WorkOS log stream is sent by WorkOS from its own addresses, never from your server. Any ingress or load balancer you put in front of the server must forward the allowed-company-ids request header unchanged: a company's proxy adds it to keep its network to its own accounts. |
Docker Images
Three official images are published on Docker Hub:
| Image | Description |
|---|---|
buildbaseapp/tenant-server | Backend API server |
buildbaseapp/client | Web dashboard (Next.js) |
buildbaseapp/auth | Auth portal (login/signup) |
Supported architectures
All images are published as multi-arch manifests for linux/amd64 and linux/arm64, built on Node.js 22 Alpine. docker pull selects the correct variant automatically - no extra configuration is needed on either architecture.
arm64 covers Apple Silicon Macs, AWS Graviton, Ampere-based cloud instances, and Raspberry Pi 4/5 running a 64-bit OS.
32-bit ARM (linux/arm/v7) is not supported. MongoDB 7 does not publish 32-bit ARM builds, so the stack cannot run on 32-bit hosts.
What You Control vs. What We Control
| You Control | We Control |
|---|---|
| Tenant server, client, auth hosting | Central server hosting |
| Your MongoDB and Redis | Installation API key provisioning |
| Your data, backups, security | Organization management & licensing |
| Custom domains, SSL, network | ES256 signing keys |
| Scaling, replicas, load balancing | Admin authentication (Google OAuth) |
| Environment variables, secrets | Platform updates & security patches |
Getting Started
- Create a self-hosted organization in the dashboard
- Follow the Quick Start guide to deploy in minutes
- For production, see the Production guide
Prefer to start from a repo? The self-hosted starter is this Compose stack, ready to clone. The buildbase-selfhost Claude skill walks you through deploying and running it.