Skip to main content

Choosing a setup

Miabi runs the same way on a single VPS and across several regions, for one developer or for thousands of users. What changes between those setups is not the product but two decisions you make about it:

  1. Where it runs — one server, a cluster of servers, or several clusters in different places.
  2. Who uses it — one team, many teams, students, paying customers, or several organizations.

The two are independent: any answer from the first list works with any answer from the second. A university can run on one large server; a two-person startup can run in three regions. Pick one of each, then read the matching pages.

Where it runs

SetupFits when
One serverEverything fits on one machine and a short outage during maintenance is acceptable
One cluster, several serversApps need replicas, or must keep running when a server fails, and the servers share one site
Several clusters as regionsServers are in different regions, providers or offices, or some sit behind NAT
Highly available apps with replicated storageStateful apps and databases must survive a node failure with their data
A homelabMachines at home, with a VPS in front for public apps

Who uses it

UsersFits when
Teams and companiesAn internal platform: workspaces per team or environment, SSO, GitOps, and production kept apart from staging
Universities and trainingA workspace per student or course, sign-in through the university, plans that keep a class within the hardware
Hosting providers and agenciesPlans sold as products, customers isolated from each other, white-label branding
Several organizations on one instanceSeveral companies or faculties, each with its own users, identity provider and optionally its own servers

The building blocks​

Every setup on these pages is a combination of the same few pieces.

PieceWhat it isRead more
Control planeThe miabi server, with PostgreSQL and Redis. One per install. It holds the configuration and drives every nodeArchitecture
NodeA server running Docker. The control-plane host is the first one; others join by running the agent, which dials outNodes
ClusterA group of nodes that share private networking and a gateway. Either a single node or a Docker SwarmMulti-node & clusters
LocationA cluster as tenants see it. Every app, database and volume is created in oneLocations
GatewayGoma Gateway: TLS, routing and middlewares at the edge of each clusterRequest lifecycle
WorkspaceThe unit of isolation: apps, databases, domains, secrets, members and its own network and encryption keyWorkspaces
OrganizationA tenant realm owning workspaces, users, an SSO provider and optionally its own clustersOrganizations
PlanQuotas, capabilities and placement for the workspaces on itPlans & quotas
Storage classA disk or a shared filesystem that volumes can be created on, by nameStorage classes

They connect in one place: a workspace's resources are placed in a location. Everything about "where" hangs below the location; everything about "who" hangs above the workspace.

Organizations and plans govern workspaces; a workspace places its apps, databases and volumes in a location, which is a cluster driven by the control plane

Which topology?​

Start at the top and stop at the first answer that fits. You can always move further down later: every step adds nodes or clusters to an existing install, and none of them rebuilds what is already there.

Decision flow: one server if everything fits and downtime is acceptable; otherwise one cluster, replicated storage when stateful apps must survive a node failure, or several clusters when servers are in different places

One serverOne clusterSeveral clustersReplicated storage
Servers12 or more, one siteAny number, any site3 or more per cluster
Replicas and rolling updatesRolling updates✓✓ per cluster✓
An app survives a node failure—Stateless appsStateless apps, within its cluster✓ including its data
Regions, providers, on-premises sites——✓Per cluster
Nodes behind NAT——✓ as single-node clusters—
Extra software to run———A replicated filesystem

Growing without migrating​

Nodes, clusters, locations and workspace_id scoping exist from the first install. Going from one server to many, or from one cluster to several, adds rows; it never rewrites the ones you have, and your workspaces, domains and manifests keep working as they are.

Growth path from one server to one cluster, several clusters and replicated storage, each step adding nodes without migrating

Combining the two​

Some common combinations, each covered by one page from each column:

You are…Where it runsWho uses it
A developer with side projectsOne serverOne personal workspace
A homelab, with a VPS for public appsA VPS control plane, home machines as nodesHomelab
A startup with staging and productionOne cluster, or two clusters to keep production apartTeams and companies
A company running internal tools and customer appsOne cluster, so a server can fail without an outageTeams and companies
A company with on-premises sites and a cloud regionSeveral clusters, one per site; on-premises nodes can sit behind NATTeams and companies
A university courseOne large server or one clusterUniversities and training
A hosting providerSeveral clusters, with node pools per tierHosting providers
A group of companiesSeveral clusters, some dedicated to one companySeveral organizations
Editions

Everything on these pages works in the free Community edition unless it is marked Enterprise. The Enterprise parts are mostly about governing many tenants: extra organizations, plan placement, node pools, per-workspace overrides and branding. See Community vs Enterprise.