Apps and deployments

Apps vs deployments

An app is the long-lived resource: a name, a Git URL, a port, an automatically assigned hostname (<name>.<apps-domain>), and scaling settings. Apps belong to a project.
A deployment (also called a job) is one build-and-run of the app. Each mikrom app deploy creates a new deployment; the previous ones are kept in the history so you can roll back.

Create an app once, then deploy it many times:

mikrom app create --name my-app --git-url https://github.com/user/repo.git
mikrom app deploy  --name my-app --watch

The build

mikrom-builder turns the repo into an OCI image:

If the repository root has a Dockerfile, it is built with Docker.
Otherwise the build is detected automatically with Railpack (over BuildKit).

Port

The app has a port (default 8080) that the router forwards to. The builder also inspects the image: an EXPOSE in your Dockerfile is respected, and the exposed port is detected from the built image when possible. Set it explicitly with the API PATCH /v1/apps/{name} ({"port": <n>}) if detection is wrong.

Deployment resources

mikrom app deploy accepts:

Flag	Values	Default
`--cpu`	`1`, `2`, `3`, `4`	`1`
`--memory`	`512M`, `1G`, `2G`, `4G`	`512M`
`--hypervisor`	`firecracker`, `cloud-hypervisor`	scheduler chooses
`--watch`	stream progress until done	off

Lifecycle of a running deployment

Commands under mikrom deployment act on a single live job (--app <name> --job-id <id>):

Command	Effect
`deployment list`	All live jobs across every app
`deployment status`	Detailed status of one job
`deployment logs`	Stream that job’s logs
`deployment pause`	Suspend CPU for the microVM
`deployment resume`	Resume a paused microVM
`deployment stop`	Kill the instance
`deployment delete`	Remove the record from history

Activate and roll back

The active deployment is the one receiving traffic. Switch to any deployment in the history:

mikrom app deployments --name my-app
mikrom app activate --app my-app --deployment-id <id>

Scaling

Every app scales to zero automatically after inactivity and wakes on the next request. On top of that:

# fixed replicas (0–3), disables autoscaling
mikrom app scale --name my-app --replicas 2

# autoscaling on CPU / memory thresholds
mikrom app scale --name my-app --auto true --min 1 --max 3 --cpu 70 --mem 80

Flag	Meaning
`--replicas`	Desired fixed replicas, `0`–`3`
`--auto true\|false`	Enable/disable autoscaling
`--min` / `--max`	Autoscaling bounds (`min` 0–3, `max` 1–3)
`--cpu` / `--mem`	Threshold percentages that trigger scale-up

Health checks

An app can define a health_check_path (set at creation via the API). The router uses health to decide when a deployment is ready to receive traffic and when to shift traffic during an activate.

Deploy on push (GitHub)

Link the app to a GitHub repository (via the dashboard’s GitHub App flow, or the github_installation_id / github_repo_id fields on POST /v1/apps). Mikrom then deploys on push. For a manual webhook, read the per-app secret:

mikrom app secret --name my-app       # GitHub webhook secret

and point a repository webhook at POST /v1/webhooks/github/{app-name}.