Installation and Upgrade

This guide covers installing and upgrading the Rumi Agent.

Prerequisites

• Operating System: macOS (x86_64 or ARM64) or Linux (x86_64 or ARM64)

• Java: JDK 11 or later

• Disk Space: At least 2GB free for installation and data

• Network: Access to downloads.n5corp.com (for remote installation)

For ARM64 macOS (Apple Silicon), the x86_64 distribution runs via Rosetta 2.

Quick Start

Standard Installation

curl -fsSL https://downloads.n5corp.com/rumi/agent/latest/install.sh | bash

This installs the latest version to ~/rumi/rumi-agent.

Installation with Custom Location

curl -fsSL https://downloads.n5corp.com/rumi/agent/latest/install.sh | bash -s -- \
    --install-dir=/opt/rumi

Installation with External Data Directory

curl -fsSL https://downloads.n5corp.com/rumi/agent/latest/install.sh | bash -s -- \
    --data-dir=/mnt/data/rumi-agent

Installation Options

Option	Description
--install-dir=DIR	Installation directory (default: $HOME/rumi)
--data-dir=DIR	External data directory for persistent data
--dist-type=TYPE	Distribution type: bundled (default) or standalone
--force	Skip confirmation prompts
--verbose	Enable verbose output
--from PATH	Install from a local distribution archive
--download-only	Download distribution only (no installation)

Distribution Types

• bundled — Includes InfluxDB for metrics storage (recommended for standalone deployments)

• standalone — Agent only, requires external InfluxDB

Specific Version Installation

To install a specific version instead of latest:

curl -fsSL https://downloads.n5corp.com/rumi/agent/1.2.3/install.sh | bash

Directory Structure

After installation, the following structure is created:

<install-dir>/
└── rumi-agent/
    ├── current -> releases/<version>/     # Symlink to active version
    ├── data/                              # Persistent data (or symlink)
    │   ├── agent/
    │   │   └── agent.conf                 # Agent configuration
    │   ├── controller/
    │   │   └── controller.conf            # Controller configuration
    │   └── influxdb/
    │       ├── influxdb.conf              # InfluxDB configuration
    │       └── influxd.pid                # InfluxDB process ID
    └── releases/
        └── <version>/                     # Release directory
            ├── agent/                     # Agent binaries and libraries
            ├── controller/                # Controller binaries
            ├── influxdb/                  # InfluxDB binaries (bundled only)
            ├── start.sh                   # Start script
            ├── stop.sh                    # Stop script
            └── setenv.sh                  # Environment configuration

Key Directories

Directory	Purpose
current/	Symlink pointing to the active release
data/	Persistent data that survives upgrades
releases/	All installed versions

Configuration

Configuration files are stored in the data/ directory and are preserved across upgrades.

Agent Configuration (data/agent/agent.conf)

Controls the agent's behavior:

• HTTP server port

• InfluxDB connection settings

• XVM heartbeat collection settings

• Controller integration

Controller Configuration (data/controller/controller.conf)

Controls the embedded Rumi Controller behavior.

InfluxDB Configuration (data/influxdb/influxdb.conf)

Time-series database configuration for metrics storage (bundled distribution only).

First-Time Configuration

On first startup, default configuration files are automatically copied from the release directory to the data directory. You can then customize these files as needed.

Starting and Stopping

Start the Agent

~/rumi/rumi-agent/current/start.sh

Or with a custom installation directory:

/opt/rumi/rumi-agent/current/start.sh

Stop the Agent

~/rumi/rumi-agent/current/stop.sh

Verify the Agent is Running

curl http://localhost:7778/rumi-agent/ping

A successful response indicates the agent is running.

Upgrading

Standard Upgrade

To upgrade to the latest version:

# Stop the current agent
~/rumi/rumi-agent/current/stop.sh

# Run the installer (detects existing installation)
curl -fsSL https://downloads.n5corp.com/rumi/agent/latest/install.sh | bash

# Start the new version
~/rumi/rumi-agent/current/start.sh

The installer automatically:

1. Detects the existing installation

2. Preserves your configuration in the data/ directory

3. Installs the new version in releases/

4. Updates the current symlink to point to the new version

Upgrade with Custom Data Directory

If you installed with --data-dir, specify the same directory during upgrade:

curl -fsSL https://downloads.n5corp.com/rumi/agent/latest/install.sh | bash -s -- \
    --data-dir=/mnt/data/rumi-agent

Rollback to Previous Version

If you need to rollback to a previous version:

# Stop the agent
~/rumi/rumi-agent/current/stop.sh

# Update the symlink manually
cd ~/rumi/rumi-agent
rm current
ln -s releases/<previous-version> current

# Start the previous version
~/rumi/rumi-agent/current/start.sh

Docker Deployment

The Agent can be deployed as a Docker container.

Building the Docker Image

docker build --build-arg VERSION=<version> -t rumi-agent:<version> .

Running the Container

docker run -d \
    --name rumi-agent \
    -p 7778:7778 \
    -v rumi-agent-data:/home/rumi/rumi-agent/data \
    rumi-agent:<version>

Docker Configuration

Setting	Value
Base image	Ubuntu 22.04
Java version	OpenJDK 8
Exposed port	7778
Data volume	/home/rumi/rumi-agent/data
Health check	curl http://localhost:7778/rumi-agent/ping

The container runs as the rumi user and includes SSH client support for remote provisioning operations.

Data Directory Management

Using an External Data Directory

The --data-dir option allows you to store persistent data on a separate volume:

• Using faster or larger storage for metrics data

• Separating data from application binaries

• Easier backup management

Migrating Data to External Directory

If you have an existing installation and want to migrate to external storage:

curl -fsSL https://downloads.n5corp.com/rumi/agent/latest/install.sh | bash -s -- \
    --data-dir=/mnt/newdisk/rumi-agent

When prompted, confirm that you want to migrate the existing data. The installer will copy all data to the new location and create a symlink.

With --force mode, the installer will not migrate data automatically. Use interactive mode for migrations.

Troubleshooting

Agent Won't Start

1. Check if the agent is already running:

   curl http://localhost:7778/rumi-agent/ping

2. Check for port conflicts:

   lsof -i :7778

3. Review the agent logs in the data directory.

InfluxDB Issues (Bundled Distribution)

1. Check if InfluxDB is running:

   cat ~/rumi/rumi-agent/data/influxdb/influxd.pid
   ps aux | grep influxd

2. Restart InfluxDB by stopping and starting the agent.

Upgrade Fails with Data Directory Mismatch

If you see an error about data directory mismatch during upgrade:

1. Verify the correct --data-dir value by checking the existing symlink:

   ls -la ~/rumi/rumi-agent/data

2. Use the same --data-dir value shown in the symlink target.

Checking Installed Version

ls -la ~/rumi/rumi-agent/current

Listing All Installed Versions

ls ~/rumi/rumi-agent/releases/