> 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/agent/installation-and-upgrade.md). # 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 ```bash 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 ```bash curl -fsSL https://downloads.n5corp.com/rumi/agent/latest/install.sh | bash -s -- \ --install-dir=/opt/rumi ``` ### Installation with External Data Directory ```bash 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: ```bash curl -fsSL https://downloads.n5corp.com/rumi/agent/1.2.3/install.sh | bash ``` ## Directory Structure After installation, the following structure is created: ``` / └── rumi-agent/ ├── current -> releases// # 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/ └── / # 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 ```bash ~/rumi/rumi-agent/current/start.sh ``` Or with a custom installation directory: ```bash /opt/rumi/rumi-agent/current/start.sh ``` ### Stop the Agent ```bash ~/rumi/rumi-agent/current/stop.sh ``` ### Verify the Agent is Running ```bash curl http://localhost:7778/rumi-agent/ping ``` A successful response indicates the agent is running. ## Upgrading ### Standard Upgrade To upgrade to the latest version: ```bash # 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: ```bash 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: ```bash # Stop the agent ~/rumi/rumi-agent/current/stop.sh # Update the symlink manually cd ~/rumi/rumi-agent rm current ln -s releases/ 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 ```bash docker build --build-arg VERSION= -t rumi-agent: . ``` ### Running the Container ```bash docker run -d \ --name rumi-agent \ -p 7778:7778 \ -v rumi-agent-data:/home/rumi/rumi-agent/data \ rumi-agent: ``` ### 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: ```bash 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. {% hint style="info" %} With `--force` mode, the installer will not migrate data automatically. Use interactive mode for migrations. {% endhint %} ## Troubleshooting ### Agent Won't Start 1. Check if the agent is already running: ```bash curl http://localhost:7778/rumi-agent/ping ``` 2. Check for port conflicts: ```bash lsof -i :7778 ``` 3. Review the agent logs in the data directory. ### InfluxDB Issues (Bundled Distribution) 1. Check if InfluxDB is running: ```bash 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: ```bash ls -la ~/rumi/rumi-agent/data ``` 2. Use the same `--data-dir` value shown in the symlink target. ### Checking Installed Version ```bash ls -la ~/rumi/rumi-agent/current ``` ### Listing All Installed Versions ```bash ls ~/rumi/rumi-agent/releases/ ```