> 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/provisioning-and-launching.md).

# Provisioning and Launching

This guide covers the provisioning of target hosts and launching of containers using the Rumi Controller.

## Provisioning

Provisioning prepares a target host to run a Rumi container. The process copies the Rumi distribution and configuration files to the host and sets up the required directory structure.

### What Provisioning Does

When a container is provisioned:

1. The Rumi distribution is copied to the target host via SCP.
2. A provisioning directory is created at `.rumi/provisioning/<system>/<container>/`.
3. The container's configuration files are localized:
   * DDL model (deployment descriptor)
   * JVM parameters
   * XCS (extended configuration)
   * Environment variables
4. The `rucprep` preparation script is executed on the target host via SSH.

### Local vs. Remote Provisioning

For containers targeting the local machine (host = `.`), provisioning bypasses SSH and SCP, executing operations directly on the filesystem.

For remote hosts, the Controller uses SSH for command execution and SCP for file transfer. See [Configuring Remote Hosts](/rumi-management/guides/controller/configuring-remote-hosts.md) for SSH setup.

### NUMA Node Assignment

On NUMA-aware hardware, containers can be assigned to specific NUMA nodes for CPU pinning. The NUMA node is specified when launching the container:

```
launch the <containerName> container on numa node <numaNode>
```

This ensures the container's JVM process and its threads are bound to the specified NUMA node's CPUs and memory, reducing cross-node memory access latency.

## Launching

Launching starts the container JVM process on the target host.

### What Launching Does

1. The `ruclaunch` script is executed on the target host (via SSH for remote hosts).
2. A JVM process is started with the container's configured JVM parameters.
3. The Rumi runtime is initialized within the JVM.
4. The container connects to the Rumi messaging bus.

### Launch Timeout

The Controller waits for the container to become available after launching. The timeout is configurable:

| Property                                         | Description                                    | Default      |
| ------------------------------------------------ | ---------------------------------------------- | ------------ |
| `nv.controller.containerlaunchtimeout`           | Maximum time to wait for a container to launch | Configurable |
| `nv.controller.containerconnecthandshaketimeout` | Timeout for the initial connection handshake   | 15 seconds   |
| `nv.controller.containerconnectretryinterval`    | Interval between connection retry attempts     | 1 second     |

{% hint style="info" %}
The legacy property names (`nv.controller.xvmlaunchtimeout`, etc.) are still accepted for backward compatibility.
{% endhint %}

## Starting

After launching, the container's microservices are started:

```
start the <containerName> container
```

This sends a start command to the container over Rumi messaging, causing the microservice engines (AEP processors) to begin processing messages.

## Full Lifecycle Example

A typical deployment sequence:

```
provision all containers
launch the processor-1 container
launch the processor-2 container
start the processor-1 container
start the processor-2 container
```

And teardown:

```
stop the processor-1 container
stop the processor-2 container
shutdown the processor-1 container
shutdown the processor-2 container
cleanup all containers
```

{% hint style="info" %}
The `xvm` and `xvms` keywords are still accepted in scripts for backward compatibility (e.g., `launch the processor-1 xvm`).
{% endhint %}