miabi

module

v1.10.27 Latest Latest Go to latest Published: Nov 11, 2026 License: AGPL-3.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/miabi-io/miabi

Links

Open Source Insights

README ¶

Miabi

The open-source, self-hosted PaaS for shipping apps, not infrastructure.
Docker Compose isn't enough. Kubernetes is overkill. Miabi is the middle.

Quick Start · Live Demo · Features · Comparison · Architecture · Docs . Examples

Miabi dashboard

Miabi is a developer-first PaaS for deploying and operating containerized applications on your own infrastructure. Push an app — from a Git repo, a Docker image, or a marketplace template — and Miabi handles build, deploy, domains, TLS, databases, scaling, backups, monitoring, and analytics. One web console, one binary, no Docker commands and no Kubernetes cluster.

It runs wherever you already have a server — a VPS, a dedicated server, bare metal, a homelab, or a cloud VM — and everything stays there: the control plane, the data, and the runtime are yours to own, move, and inspect. There is no managed service in the middle and no vendor to leave.

The name. Miabi is Tshiluba (Kasai, DR Congo 🇨🇩) for the muabi trees, traditionally associated with blessing and growth. It joins the same family as its siblings Goma Gateway and Posta.

Quick Start

Requirements: a Linux host with a reachable Docker socket, a domain pointing at it, and ports 80/443 free. PostgreSQL and Redis are brought up as part of the stack.

curl -fsSL https://get.miabi.io | sudo MIABI_DOMAIN=miabi.example.com \
  MIABI_ADMIN_EMAIL=you@example.com bash

The script installs Docker if missing, installs the miabi CLI, brings up the stack, and prints the admin password. From there:

sudo miabi system status
sudo miabi system restart
sudo miabi upgrade
sudo miabi system uninstall

Other install paths — CLI, no root, Docker Compose

Install the CLI and run the same converge yourself:

sudo miabi setup --domain miabi.example.com --admin-email you@example.com

Or use no binary at all. The Miabi image is an installer too, which is the path to take when you don't have root:

docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /etc/miabi:/etc/miabi \
  miabi/miabi:latest install --domain miabi.example.com --admin-email you@example.com

install, upgrade, restart, status, and uninstall on the image are the same commands as miabi setup / miabi upgrade / miabi system … — one implementation, two front-ends, so neither can drift from the other. Either way the converge is idempotent: re-run it and only what changed is recreated.

Prefer to drive Compose yourself? examples/compose/ brings up the same stack.

Full options, the /etc/miabi/miabi.yaml manifest, the built-in registry, and custom gateway config are in the installation docs.

Why Miabi

Docker Compose isn't enough for production: no rolling updates, no rollback, no TLS, no multi-tenancy. Kubernetes is overkill: a service mesh just for canary, Argo CD or Flux just for GitOps, and a platform team to keep it running.

Miabi sits in the middle — production deployment strategies on plain Docker, with the pieces you actually need built in rather than assembled.

Three things set it apart from other self-hosted PaaS options:

Multi-tenancy from day one. Most self-hosted PaaS tools assume one operator and one set of apps. Miabi is built around workspaces: every app, database, domain, volume, registry image, secret, backup, and deployment belongs to one. That makes it workable for shared hosting providers, agencies running client apps, SaaS platforms, internal developer platforms, and universities — not just single-tenant homelabs.

Deployment strategies without a mesh. Rolling and canary deployments with weighted traffic splitting, rollbacks, and zero-downtime updates, on Docker, because routing already flows through Goma Gateway.

Analytics with zero instrumentation. Every request already passes through the gateway, so every app gets HTTP traffic, latency, and privacy-first web analytics with no JS snippet, no SDK, and no code change.

Everything in the console is also in the REST API, the CLI, and the Terraform provider. Run it on a VPS, dedicated server, bare metal, homelab, or cloud. No vendor lock-in, no managed control plane.

Features

Applications & deployments

Deploy from a Git repo (build), a Docker image (pull), or a marketplace template
Buildpack builds with no Dockerfile required, with configurable memory and time limits
Releases with one-click rollback and full deployment history
Zero-downtime updates, canary aliases, and weighted traffic splitting
Env vars, a workspace secret vault, and per-app resource limits
Jobs — one-off commands in an app's runtime context
Stacks (compose-style app groups) and Environments (dev → staging → prod)
Per-app timeline of lifecycle events
Built-in container registry, multi-tenant and namespaced per workspace, with local or S3/MinIO storage and an optional garbage collector:
```
docker login <registry> -u <workspace-name> -p <api-token>
```

Domains, networking & TLS

Domains with DNS-verified ownership, routed through Goma Gateway with workspace-owned middlewares
Automatic TLS — HTTP-01 ACME by default, managed wildcard / DNS-01 certs via a connected DNS provider (auto-renewed), and uploaded custom certs (encrypted)
Workspace-isolated Docker networks carved from a managed address pool, so a busy multi-tenant host never exhausts Docker's small default pool
Configurable CIDR for the shared proxy network, per-node edge gateways, and on-demand port forwarding to managed databases

Data, storage & backups

Databases — PostgreSQL, MySQL, MariaDB, Redis, libSQL, and MongoDB, with managed credentials and in-place version upgrades
Volumes — workspace-owned Docker volumes, node-local by default, or shared (RWX) storage a replicated app can mount across nodes: NFS, CIFS/SMB, or a host-path bind to operator-managed storage under /mnt/* (privileged workspaces)
Backups — scheduled and manual database backup/restore plus volume archives, to local, MinIO, or S3

Multi-node & clustering

Nodes — add remote Docker hosts; the node agent dials the control plane over an outbound WebSocket tunnel, so it works behind NAT and firewalls
Cluster mode — optional, auto-detected Docker Swarm with encrypted overlay networks
Replicated service apps — in cluster mode apps deploy as replicated Swarm services by default (opt out per app); stateful apps with node-local storage stay pinned automatically
Multiple clusters & locations — one control plane drives many clusters: the default cluster, standalone nodes connected over their agent tunnel, and remote Docker Swarms in other regions. Workspaces pick a location, and apps, databases and volumes are placed inside it
Cluster ingress — each cluster is served by its own gateway (the central gateway, a node's own edge gateway, or a remote swarm's ingress node) with DNS pointing at it; traffic reaches a clustered app's tasks wherever the scheduler placed them, and the app detail view shows the real nodes replicas run on
Node pools — group nodes by tier; Enterprise plan placement keeps each plan's workspaces on its locations and pool
Image distribution — built images are pushed to the internal registry so any node can pull them, making multi-node deploys and rollbacks of Git-built apps work across the cluster
Housekeeping to reconcile drift and reclaim disk, and Docker import to adopt pre-existing containers, volumes, and networks

CI/CD & GitOps

Pipelines — pipeline-as-code CI/CD
Build runners — dedicated build machines that keep build load off app-hosting nodes; a co-located runner ships for single-node and homelab use, and an optional "builds require a runner" guarantee keeps builds off production nodes entirely
GitOps — declarative, pull-based reconciliation from miabi.io/v1 manifests, plus an imperative one-shot apply with dry-run, diff, and prune. No separate controller to run: no Argo CD, no Flux
Git push deploy, stored Git and registry credentials, signed webhooks, and notifications
Examples — complete CI/CD and GitOps for Node.js, Go, Python, PHP, Laravel, Java and Spring Boot apps: tests, Dockerfiles, pipelines, and manifests that deploy as-is
REST + OpenAPI everywhere, plus a CLI and an official Terraform / OpenTofu provider

Identity, teams & access

Auth — registration, login with email or username, password reset, JWT sessions with Redis-backed revocation, API tokens, and 2FA (TOTP)
SSO & directory — OAuth 2.0 / OIDC (GitHub, Google, generic OIDC), attachable to an organization so a customer's people land in the customer's realm. Enterprise adds SAML 2.0, SCIM provisioning, and LDAP / Active Directory sign-in on the normal login form, with directory groups mapped onto platform-admin and per-workspace roles
Workspaces & teams — members and invitations; each workspace has a unique name handle (its URL and docker login namespace) plus a display name, and each user a unique username
Organizations — tenant realms that own workspaces and the accounts in them, each with an owner, a workspace cap, its own SSO provider (accounts registered through it land in that realm), and optionally its own dedicated locations: nodes nobody else can place on.
RBAC — Owner · Admin · Developer · Viewer, enforced in middleware and by workspace_id scoping. Enterprise adds custom roles and per-resource policies (a role on a single app, domain, or database)
Container security profiles — an optional non-root "restricted" profile runs app and job containers as a platform UID with no-new-privileges; outbound webhooks are SSRF-guarded
Plans & quotas, per-workspace encryption keys (keyring/DEK), key rotation, and crypto-shred on delete

Monitoring, analytics & operations

Container CPU/memory/disk metrics and workspace health with retained history, Prometheus integration, and health endpoints
Analytics — requests/sec, status mix, bandwidth, top routes; p50/p95/p99 latency with a gateway-vs-upstream split ("is my app slow, or the gateway?"), error rate, and Apdex; unique visitors, top pages, referrers, countries, and device families. Cookieless, no consent banner, IPs never stored, unique visitors via HyperLogLog sketches rather than per-person rows
Log storage — deployment, pipeline, job, and backup logs externalized from Postgres to a shared filesystem store with a bounded DB tail, retention, size caps, and full-log download; live tailing unchanged
Append-only audit log of every mutating action, with optional SIEM streaming over syslog or webhook (Enterprise)
Admin platform — nodes and clusters, organizations, users, plans, settings, OAuth providers, SSO, license, and SIEM

Marketplace

Official, versioned templates: WordPress, Ghost, Nextcloud, n8n, Gitea, Forgejo, Umami, NGINX, pgAdmin, phpMyAdmin, mongo-express, libSQL, Posta, PostgreSQL, MySQL, Redis, and MongoDB.

Screenshots

Deploy an application	Canary deployment
GitOps	Analytics
Nodes & cluster	Managed databases

More screenshots — pipelines, domains, backups, monitoring, marketplace, admin

CI/CD pipelines	Domains, routes & TLS
Backups	Monitoring
Marketplace	Platform admin
Application overview	HTTP traffic analytics

How Miabi compares

All four projects are self-hosted, open source, and deploy from Git or a Docker image with automatic HTTPS. The table covers only where they differ.

Feature	Miabi	Coolify	Dokploy	CapRover
Multi-tenancy & workspace isolation	✅	❌	❌	❌
Organizations, teams & RBAC	✅	Limited	❌	❌
Shared hosting	✅	❌	❌	❌
Canary deployments	✅	❌	❌	❌
Zero-downtime deployments	✅	Limited	Limited	Limited
Built-in CI/CD pipelines	✅	❌	❌	❌
GitOps (no extra controller)	✅	❌	❌	❌
Declarative manifests (`miabi apply`)	✅	❌	❌	❌
Built-in container registry	✅	❌	❌	❌
Secret vault (references, rotation redeploys apps)	✅	Partial	Partial	❌
Sealed secrets (encrypted, safe to commit to Git)	✅	❌	❌	❌
Built-in analytics (privacy-first)	✅	❌	❌	❌
Audit logs	✅	❌	❌	❌
OpenAPI-documented REST API	✅	❌	Partial	Limited
Official CLI	✅	❌	❌	❌
Terraform provider	✅	❌	❌	❌
Multi-node deployments	✅	Partial	Partial	Partial
Multiple clusters & regions	✅	❌	❌	❌
Live migration between locations (app, volumes & databases, near-zero downtime)	✅ (Enterprise)	❌	❌	❌
Docker import (adopt existing containers)	✅	❌	❌	❌
Scheduled backups	✅	Partial	Partial	❌
Portable workspace backups (whole workspace, encrypted, restore anywhere)	✅	❌	❌	❌
Workspace migration to another install, with data	✅	❌	❌	❌
SAML / LDAP	✅ (Enterprise)	❌	❌	❌

Compiled from each project's public documentation. These projects move fast — if something here is out of date, please open a PR and we'll correct it.

Architecture

Browser / CLI / API clients
        │
        ▼
Goma Gateway (routing, TLS/ACME)
        │
        ▼
Miabi control plane (single Go binary: REST API + embedded Vue console)
        │
        ├─ asynq worker ── deploys, provisioning, backups
        ├─ PostgreSQL (GORM) · Redis (cache/queue)
        │
        ▼
Clusters (Docker Engine, optional Swarm per cluster)
        ├─ default cluster ── local socket, plus its Swarm members
        ├─ standalone nodes ── outbound agent tunnel, own edge gateway
        └─ remote Swarm clusters ── managers via agent tunnel, own ingress gateway

Layer	Technology
Backend	Go 1.25+, Okapi framework, REST + OpenAPI
Frontend	Vue 3 + Pinia + Vite, built and statically served by the binary
Database	PostgreSQL (GORM)
Queue / cache	Redis + Asynq
Runtime	Docker Engine 25+ via the Moby SDK for Go (`moby/moby/client`), optional Swarm
Reverse proxy / TLS	Goma Gateway
Metrics	Prometheus

The console source lives in web/ and is embedded into the Go binary, so a deployment is a single image. The node agent is a separate module, github.com/miabi-io/agent: a thin Docker proxy that needs only an outbound connection and the local Docker socket.

Live Demo

Try Miabi without installing anything at https://demo.miabi.io (password for all accounts: MiabiDemo2026).

The demo is seeded with two independent customers across three workspaces, so the core idea is visible immediately: shared hosting on Docker with true workspace isolation and role-based access. Every app, database, domain, volume, and secret belongs to a workspace; one tenant can never see or reach another's resources; a member only sees what their role grants.

Sign in as	Workspaces	Role	Represents
`admin@acme.demo.miabi.io`	Acme Inc Prod · Acme Inc Dev	Owner	one org running prod and dev in separate, isolated workspaces
`dev@acme.demo.miabi.io`	Acme Inc Dev	Developer	a teammate scoped to a single workspace — can't see Acme Inc Prod
`admin@startup.demo.miabi.io`	Startup Prod	Owner	a different tenant — invisible to Acme

Switch workspaces from the picker to watch the console re-scope, then sign in as the other customer to confirm the isolation boundary.

[!IMPORTANT] These are workspace accounts, not the platform admin. They can't reach the admin platform (nodes/cluster, users, plans, settings, licensing). To explore platform-admin features, install Miabi — the first account you seed is the platform admin.

[!NOTE] Demo apps run under a restricted (non-root) security profile: each container runs as a dedicated unprivileged user. If you deploy an app, make sure its image can run as non-root, or it will fail to start.

Development

Building from source needs Go 1.25+, Node (for the console), a PostgreSQL and a Redis instance, and a reachable Docker socket.

git clone https://github.com/miabi-io/miabi.git
cd miabi

make run        # API server on :9000, worker embedded
make worker     # standalone background worker (optional)
make build-ui   # build the Vue console into the embedded assets
make test       # unit + integration tests

The OpenAPI spec is generated from code annotations in internal/routes/ and served at /docs and /openapi.json on any running instance.

Ecosystem

Miabi is part of a family of self-hosting tools by the same author:

Project	What it is
Okapi	The Go web framework Miabi is built on
Goma Gateway	Reverse proxy with TLS/ACME
cli	The official CLI
terraform-provider-miabi	Terraform / OpenTofu provider
agent	Outbound node agent for multi-node
runner	Dedicated build and pipeline runner
marketplace	Official app template catalog
examples	Example apps with complete CI/CD pipelines and GitOps manifests
Posta	Self-hosted email delivery and inbound
pg-bkup / mysql-bkup	Database backup tools

Support & contributing

Docs — https://docs.miabi.io
Questions & ideas — GitHub Discussions
Bugs & features — open an issue. External pull requests are not accepted at the moment; see CONTRIBUTING.md
Security — report vulnerabilities privately to security@miabi.io. Please don't file public issues for security problems

If Miabi is useful to you, starring the repo genuinely helps other people find it.

License

Path	License
Core	AGPL-3.0-or-later — LICENSE, NOTICE
`pkg/`	Apache-2.0 — `pkg/LICENSE`
`internal/enterprise/`	Miabi Enterprise License — LICENSE.md

The reusable packages under pkg/ are the importable half of the project (pkg/stack is the host installer and lifecycle engine the CLI drives), so embedding them carries no AGPL obligation — nothing under pkg/ depends on AGPL-licensed code.

Enterprise features are built with the enterprise tag and require a valid commercial license. LICENSING.md has the full breakdown.

Miabi's code is open source. Its name is not. The Miabi name and logos are not covered by these licenses.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
healthprobe command Command healthprobe is the HTTP healthcheck copied into app containers, for images without a shell, curl or wget.	Command healthprobe is the HTTP healthcheck copied into app containers, for images without a shell, curl or wget.
miabi command
mwdocsgen command Command mwdocsgen generates the middleware reference docs from the catalog; a test asserts they match.	Command mwdocsgen generates the middleware reference docs from the catalog; a test asserts they match.
schemagen command Command schemagen generates the miabi.io/v1 JSON Schema from the manifest parser's types so they cannot drift.	Command schemagen generates the miabi.io/v1 JSON Schema from the manifest parser's types so they cannot drift.
internal
acme Package acme issues TLS certificates via ACME DNS-01 using caller-supplied solver funcs.	Package acme issues TLS certificates via ACME DNS-01 using caller-supplied solver funcs.
components Package components lists the independently versioned parts of Miabi for the About page.	Package components lists the independently versioned parts of Miabi for the About page.
config
cron Package cron is a recurring-task scheduler keyed by "kind:id" strings so sources share one loop without collisions.	Package cron is a recurring-task scheduler keyed by "kind:id" strings so sources share one loop without collisions.
datavolume Package datavolume refuses to start a workload whose volume is gone, since Docker would silently create an empty one.	Package datavolume refuses to start a workload whose volume is gone, since Docker would silently create an empty one.
dbenvelope Package dbenvelope seals per-set data keys under the backup passphrase so the passphrase is cheaply rotatable.	Package dbenvelope seals per-set data keys under the backup passphrase so the passphrase is cheaply rotatable.
declarative Package declarative is the miabi.io/v1 resource model shared by apply, GitOps, Terraform and marketplace templates.	Package declarative is the miabi.io/v1 resource model shared by apply, GitOps, Terraform and marketplace templates.
dns Package dns wraps libdns behind one Provider interface; Miabi only manages the records it owns.	Package dns wraps libdns behind one Provider interface; Miabi only manages the records it owns.
dnscatalog Package dnscatalog is the single source of truth for supported DNS hosts: validation, secrets, API enum and UI form.	Package dnscatalog is the single source of truth for supported DNS hosts: validation, secrets, API enum and UI form.
dnscatalog/gen command Command gen prints the docs' supported-providers table so it cannot drift from the catalog.	Command gen prints the docs' supported-providers table so it cannot drift from the catalog.
docker Package docker is the sole adapter over the Docker SDK, keeping SDK types out of the rest of the codebase.	Package docker is the sole adapter over the Docker SDK, keeping SDK types out of the rest of the codebase.
dotenv
dr Package dr holds disaster-recovery primitives and depends on nothing else in Miabi: restore runs on a bare host.	Package dr holds disaster-recovery primitives and depends on nothing else in Miabi: restore runs on a bare host.
drift Package drift is the shared vocabulary for divergence between Miabi's records and what Docker runs.	Package drift is the shared vocabulary for divergence between Miabi's records and what Docker runs.
dto
enterprise
enterprise/license
error_handlers
handlers
healthprobe Package healthprobe embeds the probe binary; without bin/ (make build-probe) builds fall back to a shell probe.	Package healthprobe embeds the probe binary; without bin/ (make build-probe) builds fall back to a shell probe.
hostmount Package hostmount defines the allow-listed host bind mounts; sources are server-owned, never client-supplied.	Package hostmount defines the allow-listed host bind mounts; sources are server-owned, never client-supplied.
hoststats Package hoststats re-exports pkg/hoststats and adds the control-plane-only helper-container sampler.	Package hoststats re-exports pkg/hoststats and adds the control-plane-only helper-container sampler.
leader Package leader elects the process that runs singleton work; it is not multi-replica HA.	Package leader elects the process that runs singleton work; it is not multi-replica HA.
logstore Package logstore externalizes finished logs to gzipped objects; a nil *Store is a no-op.	Package logstore externalizes finished logs to gzipped objects; a nil *Store is a no-op.
metrics
middlewares
models
mwcatalog Package mwcatalog is the source of truth for curated Goma middleware types exposed as security policies.	Package mwcatalog is the source of truth for curated Goma middleware types exposed as security policies.
netguard Package netguard checks the resolved IP at dial time so DNS rebinding cannot reach internal addresses.	Package netguard checks the resolved IP at dial time so DNS rebinding cannot reach internal addresses.
nodes
proxy Package proxy abstracts Goma Gateway; TLS termination, ACME issuance and renewal are owned by Goma.	Package proxy abstracts Goma Gateway; TLS termination, ACME issuance and renewal are owned by Goma.
routes
runners Package runners keeps runner tunnels only to lease jobs and stream logs; runners use their own Docker/BuildKit.	Package runners keeps runner tunnels only to lease jobs and stream logs; runners use their own Docker/BuildKit.
services/account Package account runs account-wide actions over a user's owned workspaces; each workspace has exactly one owner.	Package account runs account-wide actions over a user's owned workspaces; each workspace has exactly one owner.