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:

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:

# 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

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

# 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:

$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:

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

NUMA affinity is typically managed by the Rumi Agent when launching containers. Manual NUMA configuration is only needed for standalone deployments.

Deploying Applications

After installation, deploy application JARs and resources:

# 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:

   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.

The systems/ directory contains deployed application data and should be preserved across upgrades. Only the Controller libraries and binaries are replaced during upgrade.

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:

# 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:

   java -version

2. Verify the xvm.sh script is executable:

   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:

   ls $INSTALLATION/bin/<platform>/lib/

2. Ensure the distribution matches the host platform.

SSH Provisioning Failures

1. Verify SSH key-based authentication works:

   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.