> 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/concepts/deployment-lifecycle.md).

# Deployment Lifecycle

This page describes the key concepts in the Rumi Management deployment model: systems, XARs, and containers.

## Systems

A **system** is the top-level organizational unit in Rumi Management. It represents a complete deployment of a Rumi application, consisting of:

* One or more **containers** that host Rumi microservices.
* A **DDL model** (deployment descriptor) that defines the application topology — microservices, messaging channels, and container assignments.
* **Deployment scripts** that automate the provisioning, launching, and lifecycle management of the system's containers.
* **Configuration files** — localized JVM parameters, DDL overrides, and environment configuration per container.

Systems are stored in the Controller's `systems/` directory, with one subdirectory per system. Each system directory contains the exploded contents of the XAR that was deployed into it.

### System Lifecycle

| State           | Description                                                          |
| --------------- | -------------------------------------------------------------------- |
| **Deployed**    | XAR has been unpacked and the system is ready for provisioning       |
| **Provisioned** | Containers have been set up on their target hosts                    |
| **Running**     | Containers are launched and microservices are started                |
| **Archived**    | System has been moved to the `.archived/` subdirectory for retention |

Systems can be archived and later restored. Archived systems are retained but not active.

## XARs

A **XAR** (Rumi Archive) is the packaging format for Rumi applications. It is analogous to a WAR or EAR in the Java ecosystem. A XAR bundles together everything needed to deploy a system:

* The **DDL model** defining the application topology.
* Compiled **application code** (microservice JARs and dependencies).
* **Deployment scripts** for automated provisioning and lifecycle management.
* **Configuration** files for environment-specific settings.

XARs are built using the `nvx-rumi-xar-maven-plugin` as part of the application's Maven build. They are deployed to the Controller (or Agent) by unpacking them into the `systems/` directory.

### XAR Deployment

When a XAR is deployed:

1. The XAR archive is uploaded to the Agent (via the REST API) or placed in the Controller's filesystem.
2. The XAR is unpacked into a system directory under `systems/`.
3. The system becomes available for provisioning and script execution.

## Containers

A **container** is a JVM process that hosts one or more Rumi microservices. Each container is defined in the DDL model and has:

* A **name** that uniquely identifies it within the system.
* A **target host** where it runs (specified by hostname or IP, with SSH credentials for remote access).
* **JVM parameters** for memory, GC, and runtime tuning.
* **NUMA node** assignment for CPU pinning on NUMA-aware hardware.
* **Configuration overrides** — localized DDL, XCS (extended configuration), and environment variables.

### Container Provisioning

Provisioning prepares a target host to run a container:

1. The Rumi distribution is copied to the target host via SCP.
2. The directory structure is set up under a provisioning directory (`.rumi/provisioning/<system>/<container>/`).
3. Configuration files are localized for the specific container and host.

For containers running on the local machine, SSH is bypassed and the operations execute directly.

### Container Lifecycle

The Controller manages container lifecycle through a sequence of commands:

```
provision → launch → start → [running] → stop → shutdown → cleanup
```

| Command       | Description                                                           |
| ------------- | --------------------------------------------------------------------- |
| **provision** | Copies distribution and configuration to the target host              |
| **launch**    | Starts the container JVM process (optionally on a specific NUMA node) |
| **start**     | Starts the microservices within the container                         |
| **stop**      | Gracefully stops the microservices                                    |
| **shutdown**  | Terminates the container JVM process                                  |
| **cleanup**   | Removes provisioned files from the target host                        |

## Relationship Between Concepts

```
XAR (archive)
 └── unpacked into → System
                       ├── DDL Model (topology)
                       ├── Scripts (deployment automation)
                       └── Containers
                            ├── Container A → Host 1
                            ├── Container B → Host 2
                            └── Container C → Host 1
```

A single XAR produces a single system. A system contains one or more containers. Containers can be distributed across multiple hosts or co-located on the same host. The DDL model defines which microservices run in which containers and how they communicate.