> 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.rumi.systems/rumi-management/concepts/deployment-lifecycle.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.