> For the complete documentation index, see [llms.txt](https://docs.rumi.systems/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rumi.systems/rumi-management/guides/controller/deploying-with-scripts.md).

# Deploying with Scripts

This guide explains how to write and execute deployment scripts using the Rumi Controller.

## Overview

Deployment scripts automate the provisioning, launching, and lifecycle management of Rumi systems. Scripts are typically packaged inside a XAR and define the sequence of operations needed to bring a system from initial deployment to a running state.

## Writing Scripts

Scripts are composed of commands that target containers within a system. Each command specifies an operation and the containers it applies to.

### Command Syntax

Commands can target all containers or specific containers by name:

```
provision all containers
launch the <containerName> container
start the <containerName> container
```

{% hint style="info" %}
The `xvm` and `xvms` keywords are still accepted in scripts for backward compatibility.
{% endhint %}

### Common Script Patterns

A typical deployment script follows this sequence:

1. **Provision** all containers on their target hosts.
2. **Launch** each container's JVM process.
3. **Start** the microservices within each container.

A teardown script reverses this:

1. **Stop** the microservices.
2. **Shutdown** the container JVM processes.
3. **Cleanup** provisioned files.

### Script Parameters

Scripts support parameterized values for environment-specific configuration. Parameters are resolved at execution time, allowing the same script to adapt to different environments (development, staging, production).

## Executing Scripts

### Via the Controller (Standalone)

When using the Controller standalone, scripts are executed from the command line against a specified system.

### Via the Agent REST API

Scripts can be executed remotely through the Agent's REST API:

```
POST /rumi-agent/invoke/script
```

The request body specifies the system name and script to execute. See the [REST API Reference](/rumi-management/reference/agent/rest-api.md) for details.

### Via the Admin UI

The Admin dashboard provides a visual interface for selecting and executing scripts. See [Executing Scripts (Admin)](/rumi-management/guides/admin/executing-scripts.md).

## Monitoring Execution

Script execution is tracked by the Agent with a UUID. The execution status can be queried to monitor progress:

* **Pending** — Queued for execution.
* **Running** — Currently executing.
* **Success** — Completed successfully.
* **Aborted** — Cancelled or failed.

## Cancelling Execution

A running script can be cancelled via the Agent:

```
POST /rumi-agent/invoke/cancel?uuid=<executionUUID>
```

See the [Script Commands Reference](/rumi-management/reference/controller/script-commands.md) for the complete list of available commands and their options.