Skip to main content

Deployment

Deployment is the core workflow of Miren — it takes your application code, builds a container image, and runs it on your server.

How Deployment Works​

When you run miren deploy, Miren:

  1. Uploads your files — sends your source code to the server (after your first deploy, only changed files are transferred)
  2. Detects and builds on the server — the server inspects your source code to detect the language, framework, and services, then builds a container image using the detected stack (or your Dockerfile)
  3. Activates the new version — rolls out the new version, replacing the previous one

Every deployment is tracked with a unique version ID, its current status, and the git commit it came from. You can inspect, roll back, or redeploy any previous version at any time.

Deploying from a Project Directory​

The most common workflow — run miren deploy from the root of your project:

cd ~/myapp
miren deploy

You can also deploy from a different directory with -d:

miren deploy -d path/to/app

Miren reads the app name from .miren/app.toml. If you haven't set up your project yet, Miren offers to run miren init for you, which creates an app.toml with the app name derived from your directory name. If this is the first deploy of the app, Miren creates it automatically on the server.

Confirmation Prompt​

If your cluster config includes multiple clusters, Miren asks you to confirm which cluster to deploy to. Skip the prompt with --force:

miren deploy --force

The prompt is also skipped automatically when only one cluster is configured or when stdin is not a terminal (e.g., in CI).

Build Detection​

Miren automatically detects how to build your application. It inspects your project files and identifies the language, framework, package manager, and entry points. See Languages for details on supported stacks.

Use --analyze to see what Miren detects without actually building or deploying:

miren deploy --analyze

You'll see the detected stack, services, entrypoint, and what files and frameworks influenced the result. Handy when a build isn't doing what you expect.

If a build fails, Miren displays the build errors and the deployment is marked as failed in history (visible via miren app history).

Use --explain (or -x) to watch each build step as it runs. This is the default in non-interactive environments; in interactive terminals, Miren shows a compact progress UI instead.

Deploy-Time Environment Variables​

Set environment variables at deploy time with -e and -s. They're applied to the app before the new version activates.

# Regular variables
miren deploy -e RELEASE_SHA=abc123 -e LOG_LEVEL=debug

# Sensitive variables (masked in output)
miren deploy -s DATABASE_URL=postgres://user:pass@host/db

# Read value from a file
miren deploy -s API_KEY=@secrets/api-key.txt

# Prompt for the value (sensitive vars mask input)
miren deploy -s SECRET_KEY

Redeploying an Existing Version​

Skip the build entirely and redeploy a previously built version:

miren deploy --version myapp-vCVkjR6u7744AsMebwMjGU

Useful for rolling forward to a known-good version without waiting for a new build.

Find version IDs with miren app history (see Deployment History below).

Rollback​

miren rollback provides an interactive way to revert to a previous version:

miren rollback -a myapp

This presents a picker showing your recent successful deployments:

ColumnDescription
VERSIONThe version ID
STATUSDeployment status (active, succeeded)
WHENRelative timestamp
GIT SHAShort commit hash
BRANCHGit branch at the time of deploy

Select a version and Miren redeploys it immediately. The currently active version is excluded from the list since rolling back to the current version would be a no-op.

Rollback creates a new deployment record — it doesn't erase history.

Deployment History​

View the history of deployments for an app:

miren app history -a myapp

Output​

STATUS  VERSION                              WHEN     DEPLOYED BY
✓       myapp-vCVkjR6u7744AsMebwMjGU         2m ago   paul@miren.dev
✓       myapp-vCVkjJSe4fydvxEHfhsKfA         1h ago   paul@miren.dev
✗       myapp-vCVmuoeQCzjoNN9hGsu14c         3h ago   paul@miren.dev
↩       myapp-vCVkjTGJhRddyZDVq9CmnN         1d ago   paul@miren.dev

Status icons:

  • ✓ — active (currently running) or succeeded
  • ✗ — failed
  • ↩ — rolled back
  • ⟳ — in progress
  • ⊘ — cancelled

You can filter by status, show full git provenance with --detailed, or get JSON output for scripting. See the miren app history reference for all options.

Cancelling a Deployment​

Cancel an in-progress deployment by its deployment ID:

miren deploy cancel -d <deployment-id>

Get the deployment ID from miren app history --detailed. If a CLI session is watching that deployment, it'll detect the cancellation and exit cleanly.

Only one deployment can run per app at a time. If you attempt to deploy while another is in progress, Miren tells you who started it and when. You can wait for it to finish or cancel it and start a new one.

Git Provenance​

Miren automatically captures git metadata (commit, branch, author, dirty state) from your working directory at deploy time. This information appears in miren app history --detailed and in the miren rollback picker. No configuration is needed — if you deploy from a git repo, provenance is captured automatically.

Next Steps​