Motherbase
Quick start
Browse documentation

Motherbase installs a Platform Console and lets that Console provision isolated project stacks. The supported entry point is ./setup.sh; deploy/README.md explicitly treats the files under deploy/ as implementation and maintenance helpers.

Topologies

TopologySelected byProject Compose fileRouting
Local multi-project./setup.sh, then choose Localdeploy/docker-compose.dev-multi.ymlHTTP at <name>.localhost
Production multi-project./setup.sh, then choose VPS, or use DOMAIN=... ./setup.sh --yes --proddeploy/docker-compose.prod.ymlHTTPS at <name>.<base-domain>
Root development stackdocker compose up in the repository rootdocker-compose.ymlLoopback ports only, no proxy

Local mode starts deploy/traefik/docker-compose.dev.yml and deploy/console/docker-compose.dev.yml. Production starts deploy/traefik/docker-compose.yml and deploy/console/docker-compose.yml. In both modes, the Console creates projects afterwards; setup.sh does not create a default project.

Note

The root docker-compose.yml is a single-stack development convenience, not a supported production topology: setup.sh never starts it. Use the Console-managed production topology for a normal installation. See Docker topology.

Host requirements

The checks in setup.sh require:

  • Bash, because the setup must be executed as ./setup.sh and refuses to be sourced.
  • A working Docker daemon and either docker compose or the legacy docker-compose command.
  • Access to /var/run/docker.sock; only the internal orchestration daemon receives the socket in the Console stacks.
  • Host ports 80 and 443 in VPS mode. The script opens them through active ufw, or inserts iptables accept rules when available.
  • Outbound HTTPS access to pull images, resolve their immutable repository digests, query https://ifconfig.me, and complete ACME challenges.

If Docker is absent on Linux, setup.sh runs the installer from https://get.docker.com. On macOS and other systems it stops and asks you to install Docker manually. No Node.js installation is required for setup.sh: deploy/deps.Dockerfile builds with node:22-bookworm-slim. A manual host build is separate and is guarded by scripts/check-node-version.cjs, which requires Node 22.12.0 or newer.

The repository does not enforce a CPU, RAM, disk, or Linux-distribution minimum. Production project defaults in apps/server/console/lib/manifest.ts limit API and Postgres to 0.5 CPU and 512M each, and MinIO to 0.25 CPU and 256M.

DNS

For DOMAIN=example.com, create one wildcard record pointing to the VPS:

Type: A
Name: *
Value: <VPS_IP>

The generated project defaults in apps/server/console/lib/manifest.ts use:

console.example.com
<name>.example.com
<name>-storage.example.com
<name>-minio.example.com

*.example.com does not cover the apex example.com. If CONSOLE_DOMAIN is outside DOMAIN, setup.sh prints and checks a second explicit record. A custom project domain outside the wildcard also needs its own DNS record.

When the base domain already contains at least two dots, for example test.example.com, setup.sh treats the resulting project hosts as deep subdomains and offers the GoDaddy DNS-01 configuration. See Traefik and TLS.

What is installed where

LocationContentsPersistence
Repository root .envLocal project environment, or the VPS install marker with BASE_HOST, CONSOLE_DOMAIN, and ACME_EMAILKept on normal reruns; removed by reset
deploy/console/.envConsole credentials, orchestration bearer, image references, domain suffix, and resolverMode 600; kept and repaired on normal reruns
deploy/traefik/.envACME email, pinned proxy images, optional dashboard and DNS-01 valuesKept on normal reruns
/srv/projects/<name>/.env.prodOne production project's generated configuration and secretsMode 600; kept by stop/update, deleted by project destruction
/srv/projects/<name>/manifest.jsonNon-secret project manifestKept by stop/update, deleted by project destruction
console_projects volumeLocal-mode Console project directory mounted at /srv/projectsKept by normal recreation
Per-project db_data and minio_data volumesPostgreSQL and MinIO dataKept by stop/update; deleted by destroy/reset
Per-project api_backups and api_data volumesProduction SQL dumps and assistant SQLite dataKept by stop/update; deleted by destroy/reset
deploy/traefik/acme/Traefik ACME state, including acme.jsonBind-mounted into the production Traefik container
traefik_proxyExternal Docker network shared by Traefik, Console, APIs, and MinIOCreated by setup when missing
Warning

Project Destroy, ./setup.sh --reset, and ./deploy/reset.sh remove Docker volumes. A normal stop, restart, setup rerun, or project update does not.

Next steps