> 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/installation-and-upgrade.md).

# Installation and Upgrade

This guide covers installing and upgrading the Rumi Controller.

## Prerequisites

* **Operating System**: macOS (x86\_64) or Linux (x86\_64)
* **Java**: JDK 11 or later
* **Disk Space**: At least 500MB free for installation
* **SSH Access**: Required for remote provisioning to target hosts

## Installation Overview

The Controller is installed from a platform-specific distribution package. The distribution includes:

* Controller binaries and libraries
* Platform-specific native libraries
* An `install.sh` script for automated installation

### Supported Platforms

| Platform        | Distribution Name |
| --------------- | ----------------- |
| macOS (Intel)   | `osx-x86-64`      |
| Linux (x86\_64) | `linux-x86-64`    |

## Standard Installation

### Download the Distribution

Download the appropriate platform-specific distribution from the Rumi downloads server:

```bash
curl -fsSL https://downloads.n5corp.com/rumi/controller/<version>/rumi-controller-<version>-<platform>.tar.gz \
    -o rumi-controller.tar.gz
```

### Install the Distribution

Extract and run the installer:

```bash
# Create temporary directory
mkdir -p ~/.rumi.controller.tmp
cd ~/.rumi.controller.tmp

# Extract the distribution
tar xvf /path/to/rumi-controller.tar.gz

# Navigate to the extracted directory
cd *

# Make scripts executable
chmod +x $(find . -name "*.sh")

# Install to target directory
./install.sh -target ~/rumi/rumi-controller
```

### Clean Up

```bash
rm -rf ~/.rumi.controller.tmp
```

## Directory Structure

After installation, the following structure is created:

```
<target>/
├── bin/
│   ├── java/
│   │   └── lib/           # Java libraries
│   ├── <platform>/
│   │   └── lib/           # Platform-specific native libraries
│   └── xvm.sh             # Container launch script
├── conf/                  # Configuration files
│   └── controller.conf
├── resources/             # Application resources (created at deploy time)
├── systems/               # Deployed systems (created at runtime)
│   └── .archived/         # Archived systems
├── ext/                   # External libraries
└── logs/                  # Log output
```

### Key Directories

| Directory             | Purpose                                            |
| --------------------- | -------------------------------------------------- |
| `bin/java/lib/`       | Java libraries for the Controller and applications |
| `bin/<platform>/lib/` | Platform-specific native libraries                 |
| `conf/`               | Configuration files including `controller.conf`    |
| `systems/`            | Deployed systems (persistent data)                 |

## Configuration

The Controller reads its configuration from `controller.conf`. Key properties to configure at installation time:

| Property                    | Description                      | Default    |
| --------------------------- | -------------------------------- | ---------- |
| `nv.controller.systemsroot` | Directory for deployed systems   | `systems/` |
| `nv.controller.extroot`     | Directory for external libraries | `ext/`     |

See the [Controller Configuration Reference](/rumi-management/reference/controller/configuration.md) for the complete list of properties.

## Remote Provisioning

The Controller supports SSH-based remote provisioning to target hosts.

### Prerequisites for Remote Provisioning

* SSH key-based authentication configured
* SSH access to the target host
* Sufficient permissions on the target host

### Remote Installation

```bash
# Set variables
DISTRIBUTION=/path/to/rumi-controller.tar.gz
TARGET=/opt/rumi/rumi-controller
SSH_USER=user@target-host
SSH_KEY=~/.ssh/id_rsa
SSH_PORT=22

# Create temp directory on remote host
ssh -i $SSH_KEY -p $SSH_PORT $SSH_USER "rm -rf ~/.rumi.controller.tmp ; mkdir ~/.rumi.controller.tmp"

# Copy distribution to remote host
scp -i $SSH_KEY -P $SSH_PORT $DISTRIBUTION $SSH_USER:~/.rumi.controller.tmp/

# Extract on remote host
ssh -i $SSH_KEY -p $SSH_PORT $SSH_USER "tar xvf ~/.rumi.controller.tmp/*.tar.gz -C ~/.rumi.controller.tmp"

# Install on remote host
ssh -i $SSH_KEY -p $SSH_PORT $SSH_USER "bash -l -c \"~/.rumi.controller.tmp/*/install.sh -target $TARGET\""

# Clean up
ssh -i $SSH_KEY -p $SSH_PORT $SSH_USER "rm -rf ~/.rumi.controller.tmp"
```

## Starting Containers

Containers are launched using the `xvm.sh` script:

```bash
$INSTALLATION/bin/xvm.sh <container-name> wrapper.daemonize=true wrapper.logfile=$LOGDIR/container.<container-name>.log
```

### NUMA Affinity

For performance-critical deployments, you can pin containers to specific NUMA nodes:

```bash
numactl -m <numa-node> $INSTALLATION/bin/xvm.sh <container-name> wrapper.daemonize=true
```

{% hint style="info" %}
NUMA affinity is typically managed by the Rumi Agent when launching containers. Manual NUMA configuration is only needed for standalone deployments.
{% endhint %}

## Deploying Applications

After installation, deploy application JARs and resources:

```bash
# Deploy application JARs
cp /path/to/app/*.jar $INSTALLATION/bin/java/lib/

# Deploy resources (if any)
mkdir -p $INSTALLATION/resources
cp -r /path/to/resources/* $INSTALLATION/resources/

# Deploy native libraries (if any)
cp /path/to/native/* $INSTALLATION/bin/<platform>/lib/
```

## Upgrade

To upgrade the Controller:

1. **Stop any running containers** managed by the Controller.
2. **Back up persistent data**:

   ```bash
   cp -r $INSTALLATION/systems ~/backup/systems
   cp $INSTALLATION/conf/controller.conf ~/backup/
   ```
3. **Install the new version** to the same target directory. The installer will replace the binaries while preserving the `systems/` directory.
4. **Verify configuration**: Check `controller.conf` for any new or changed properties in the new version.
5. **Restart containers** using the Rumi Agent or manually.

{% hint style="info" %}
The `systems/` directory contains deployed application data and should be preserved across upgrades. Only the Controller libraries and binaries are replaced during upgrade.
{% endhint %}

## Rollback

To rollback to a previous version:

1. Stop all running containers.
2. Back up the current installation.
3. Install the previous version to the same target directory.
4. Restore any configuration changes if needed.
5. Restart containers.

## Verifying the Installation

After installation, verify the Controller is properly set up:

```bash
# Check the installation directory
ls -la ~/rumi/rumi-controller/bin/

# Verify the xvm.sh script exists
ls -la ~/rumi/rumi-controller/bin/xvm.sh

# Check Java libraries
ls ~/rumi/rumi-controller/bin/java/lib/
```

## Troubleshooting

### Container Won't Start

1. Check that Java is available in the path:

   ```bash
   java -version
   ```
2. Verify the xvm.sh script is executable:

   ```bash
   chmod +x $INSTALLATION/bin/xvm.sh
   ```
3. Review the container logs in the logs directory.

### Missing Native Libraries

If you see errors about missing native libraries:

1. Verify the platform-specific distribution was installed:

   ```bash
   ls $INSTALLATION/bin/<platform>/lib/
   ```
2. Ensure the distribution matches the host platform.

### SSH Provisioning Failures

1. Verify SSH key-based authentication works:

   ```bash
   ssh -i $SSH_KEY -p $SSH_PORT $SSH_USER "echo 'SSH OK'"
   ```
2. Check the target directory permissions on the remote host.
3. Ensure the remote host has sufficient disk space.