Installation and Upgrade

This guide covers installing and upgrading Rumi Admin.

Prerequisites

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

• Disk Space: At least 1GB free for installation

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

• A running Rumi Agent instance (for system management and telemetry)

Rumi Admin bundles its own Node.js runtime and Grafana instance. No external dependencies are required.

Quick Start

Standard Installation

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

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

Installation with Custom Location

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

Installation Options

Option	Description
--install-dir=DIR	Installation directory (default: $HOME/rumi)
--force	Skip confirmation prompts
--verbose	Enable verbose output
--download-only	Download distribution only (no installation)

Specific Version Installation

To install a specific version instead of latest:

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

Directory Structure

After installation, the following structure is created:

<install-dir>/
└── rumi-admin/
    ├── current -> releases/<version>/     # Symlink to active version
    ├── data/                              # Persistent data
    │   ├── ecosystem.json                 # Configuration (bootstrapped)
    │   └── grafana/
    │       └── conf/
    │           └── server.ini             # Grafana configuration
    └── releases/
        └── <version>/                     # Release directory
            ├── app/                       # Application code
            ├── nodejs/                    # Bundled Node.js runtime
            ├── server                     # Server executable
            ├── start.sh                   # Start script
            ├── stop.sh                    # Stop script
            ├── setenv.sh                  # Environment configuration
            └── ecosystem.json             # Default configuration template

Key Directories

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

Configuration

Automatic Configuration Bootstrap

On first startup, Rumi Admin automatically bootstraps configuration files from the release directory to the data directory:

• ecosystem.json — Main configuration file

• grafana/conf/server.ini — Grafana server configuration

These files are only copied if they don't already exist, preserving your customizations across upgrades.

ecosystem.json

The ecosystem.json file is the central configuration file. It is located in the data directory (data/ecosystem.json) and controls:

{
  "apps": [{
    "name": "Rumi Admin Webserver",
    "script": "./app/index.js",
    "args": [8001],
    "instances": 4,
    "max_memory_restart": "256M"
  }],
  "agents": [{
    "name": "Local Agent",
    "url": "http://localhost:7778/rumi-agent",
    "access": "proxy"
  }],
  "proxy": { "port": 8000 },
  "ldap": { "enabled": false },
  "okta": { "enabled": false, "token": "", "domain": "" }
}

Section	Description
apps	Node.js application settings (port, clustering, memory limits)
agents	Default Rumi Agent connections
proxy	Proxy port configuration
ldap	LDAP authentication settings (optional)
okta	Okta SSO settings (optional)

See the Admin Configuration Reference for the full configuration format.

Environment Variables

Variable	Description
RUMI_ADMIN_DATA_DIR	Override the default data directory location

Starting and Stopping

Start Rumi Admin

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

Options:

• --verbose — Show detailed output

• --foreground or -f — Run in foreground mode (for Docker)

Stop Rumi Admin

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

Startup Sequence

On startup, Rumi Admin:

1. Sources setenv.sh to configure the environment

2. Bootstraps ecosystem.json and server.ini if not present

3. Spawns a Grafana child process

4. Waits for Grafana to become ready

5. Starts the Node.js HTTP server on the configured port

6. Creates a Grafana API key for internal access

7. Creates the default InfluxDB data source

8. Loads the pre-built dashboards

Upgrading

Standard Upgrade

To upgrade to the latest version:

# Stop the current server
~/rumi/rumi-admin/current/stop.sh

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

# Start the new version
~/rumi/rumi-admin/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

Rollback to Previous Version

If you need to rollback to a previous version:

# Stop the server
~/rumi/rumi-admin/current/stop.sh

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

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

Checking Installed Version

ls -la ~/rumi/rumi-admin/current

Listing All Installed Versions

ls ~/rumi/rumi-admin/releases/

Docker Deployment

Rumi Admin can be deployed as a Docker container.

Building the Docker Image

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

Running the Container

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

Docker Configuration

Setting	Value
Base image	Ubuntu 22.04
Exposed port	8001
Data volume	/home/rumi/rumi-admin/data
Health check	curl http://localhost:8001

The container uses the --foreground flag to keep the process in the foreground for Docker's process management.

Verifying the Installation

After starting Rumi Admin, open a browser and navigate to http://localhost:8001. You should see the Rumi Admin dashboard.

To verify from the command line:

curl http://localhost:8001

Troubleshooting

Server Won't Start

1. Check if the server is already running by accessing http://localhost:8001

2. Check for port conflicts:

   lsof -i :8001

3. Review the logs in current/logs/install.log

Configuration Not Applied

Ensure you're editing the configuration in the data/ directory, not in the releases/ directory. The release directory contains only templates.

Grafana Not Starting

Check that the Grafana configuration (data/grafana/conf/server.ini) is valid. If corrupted, you can delete it and restart — a fresh copy will be bootstrapped from the release.