Install and start - MATE Docs

Requirements#

Docker Desktop or Docker Engine with Compose v2.
Free ports 3000 (web), 8000 (API), 8080 (Keycloak).
~3 GB for images, plus room for your data.

Python, Node, uv, and pnpm are only needed for host development (Contributing).

Quick start#

Clone and enter the repository.

Terminal

git clone https://github.com/Process-Science-Community/MATE.git mate
cd mate

2
Create the environment file, then rotate its two secrets before the stack is reachable by anyone else.
Terminal
```
cp .env.example .env
```
3
Build and start everything.
Terminal
```
make up
```
Open http://localhost:3000 and sign in as admin@flows-funds.local with flowsfunds. Keycloak forces a password change on first login.
Add users in the Keycloak console at http://localhost:8080/admin (admin / admin), realm flows-funds.

First boot#

Stage	What happens	Time
Images build	API, web, Keycloak	3–8 min
Databases start	`app-db`, `keycloak-db`	seconds
Realm import	Keycloak imports the realm on an empty database	~30 s
API boots	Migrations run, then the loader builds one virtual environment per bundled module	up to 10 min
Web boots	Next.js starts and bundles module frontends	~1 min

The API health check deliberately allows ten minutes for this. Later boots hash each module's dependency block, skip what is unchanged, and start in seconds.

Running modes#

Command	What you get
`make up`	Base compose file: production-style images, detached. The default.
`make up-dev`	Base plus `compose.dev.yml`: hot reload inside Docker.
`make dev`	Host dev servers (API + web) with the fastest reload. Needs `uv`, `pnpm`, Python 3.12.
Prod overlay	`docker-compose.prod.yml`: Caddy with TLS, one public origin, no public app ports. See Deployment.

Daily operations#

Terminal

make down                     # stop (keeps volumes and data)
make up                       # start again, reusing module environments
docker compose logs -f api    # follow the API log (also: web, keycloak)

make clean wipes event logs, module results, the metadata database, and the Keycloak volume. This cannot be undone.