Skip to main content
A Monk deployment is defined by files in your repository: a MANIFEST, the Monk YAML templates it loads, and the Dockerfiles for your own services. Your coding agent writes them, Monk deploys them, and you approve the plan.

​
The MANIFEST and templates

The MANIFEST sits at the root of your repository and tells Monk what to load and run. Its directives include: The templates describe each runnable: its containers, its services and ports, its volumes for stateful data, its connections to other runnables, and, for web-facing services, its ingress routes. Supporting services such as PostgreSQL or Redis normally come from Monk packages and aren’t written by hand. Variants such as staging or production use Monk’s inherits, so a variant only overrides what differs from its base. Your coding agent writes these files when it configures the project, and Monk’s analyzer checks them. Because they live in your repository, you can review them and keep them under version control like any other code.

​
The plan and the approval screen

Before a deploy that would change anything, Monk shows the plan in the local dashboard. The plan includes:
  • the workloads that will be created, changed or removed
  • warnings from the plan
  • the cost impact, where it can be estimated
  • a picture of what the deploy will build
You approve or decline. Monk also asks for approval before it deploys to a cluster it doesn’t know about yet. To see the plan without deploying, ask for a plan:

​
Where a deploy runs

A deploy runs locally on your machine’s orchestrator or on a cluster in your cloud account. See Clusters and clouds. With environments, the selected environment decides which entry and which images are used. A deploy counts as successful once its workloads have started. Readiness checks can take longer to pass. Monk checks workload status afterwards, and it can also wait for readiness and report a deploy as failed if a service never becomes ready.

​
Redeploying

When you change code, ask Monk to deploy again. It rebuilds the images that changed and updates the workloads. Each redeploy goes through the same plan review.
To deploy on every push, set up CI/CD.

​
Rolling back

Your deployment is defined by files in git, so a rollback means redeploying an earlier commit. Check out the commit, or revert the change, and ask Monk to deploy. With CI/CD, push the revert. Monk doesn’t keep a separate release history of its own. Data is the exception. Rolling back code doesn’t roll back a database. See Backup and restore.

​
Workload controls

Monk can also act on individual workloads:
  • Status and logs. Workload state and readiness, plus a bounded tail of the logs. See Logs and debugging.
  • Stop. Takes a workload offline but keeps its state, so it can start again later.
  • Delete and purge. Removes a workload. Purge also removes its stored state. Both ask for approval.
  • Custom actions. Some packages declare their own operations, such as taking or restoring a database snapshot. Monk lists them, and you approve each run. You can choose to always allow a specific action in a workspace, and you can withdraw that later.

​
Orchestrator upgrades

The orchestrator (monkd) on your cluster nodes can be upgraded on one node, on the whole cluster one node at a time, or on your local machine. If you don’t name a version, the upgrade installs the latest release. Each targeted node’s monkd restarts during the upgrade.

Start a new app

The first deployment, step by step

Deploy an existing app

New infrastructure alongside what already runs

CI/CD

Deploy on every push with GitHub Actions

Watcher and recovery

What happens when a workload fails