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

# Installation and Upgrade

This guide covers installing and upgrading Rumi Monitor.

## Overview

Rumi Monitor provides pre-built Grafana dashboards for visualizing telemetry data collected by the Rumi Agent. There are two deployment options:

* **Bundled with Rumi Admin** (Recommended) — Grafana runs as a child process of Rumi Admin
* **Standalone Grafana** — Use your own Grafana installation with imported Rumi dashboards

## Prerequisites

### Bundled Deployment (via Rumi Admin)

No additional prerequisites — Grafana is included in the Rumi Admin distribution.

### Standalone Deployment

* Grafana 9.x or later
* InfluxDB with telemetry data from the Rumi Agent
* Network access from Grafana to the InfluxDB instance

## Bundled Deployment with Rumi Admin

When using Rumi Admin, Grafana is automatically started as a child process. The canned Rumi dashboards are loaded during the Admin startup sequence.

### Installation

Follow the [Admin Installation Guide](/rumi-management/guides/admin/installation-and-upgrade.md) to install Rumi Admin. Monitor capabilities are included automatically.

### Startup Sequence

On startup, Rumi Admin:

1. Spawns Grafana as a child process
2. Waits for Grafana to become ready
3. Creates a Grafana API key for internal access
4. Creates the default InfluxDB data source
5. Loads the pre-built dashboards

### Grafana Configuration

The bundled Grafana configuration is stored in:

```
<rumi-admin>/data/grafana/conf/server.ini
```

This file is automatically bootstrapped on first startup. You can customize Grafana settings by editing this file and restarting Rumi Admin.

### Accessing Dashboards

After starting Rumi Admin, access the dashboards at:

```
http://localhost:8001
```

The Rumi Admin UI provides navigation to all Monitor dashboards.

## Docker Deployment

When deploying Rumi Admin via Docker, Monitor is included automatically.

### Running the Container

```bash
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`                         |
| Grafana config | `/home/rumi/rumi-admin/data/grafana/conf/server.ini` |

The Grafana data and configuration persist in the mounted data volume across container restarts.

See the [Admin Installation Guide](/rumi-management/guides/admin/installation-and-upgrade.md#docker-deployment) for complete Docker deployment instructions.

## Standalone Grafana Deployment

To use Rumi Monitor with a standalone Grafana installation:

### Install Grafana

Install Grafana following the [official Grafana documentation](https://grafana.com/docs/grafana/latest/setup-grafana/installation/).

### Configure the InfluxDB Data Source

1. In Grafana, navigate to **Configuration** > **Data Sources**.
2. Click **Add data source** and select **InfluxDB**.
3. Configure the connection:

| Setting          | Value                      |
| ---------------- | -------------------------- |
| URL              | `http://<agent-host>:8086` |
| Database         | `rumi`                     |
| Retention policy | `rumi_heartbeat_rp`        |

4. Click **Save & Test** to verify the connection.

### Import the Dashboards

The canned dashboards are provided as JSON files:

| Dashboard         | File              | Description                               |
| ----------------- | ----------------- | ----------------------------------------- |
| Home              | `home.json`       | Overview and navigation                   |
| Container Stats   | `xvm-stats.json`  | Per-container CPU, memory, GC, threads    |
| Application Stats | `app-stats.json`  | Per-application store, messaging, latency |
| Host Stats        | `host-stats.json` | Per-host disk, CPU, memory                |

To import a dashboard:

1. Navigate to **Dashboards** > **Import**.
2. Upload the JSON file or paste its contents.
3. Select the InfluxDB data source.
4. Click **Import**.

{% hint style="info" %}
Dashboard JSON files are included in the Rumi Admin distribution under the `app/` directory.
{% endhint %}

### Data Source Binding

The dashboards expect an InfluxDB data source. If your data source name differs from the default, update the data source bindings during import or edit the dashboard settings after import.

## Upgrade

### Bundled Deployment

Upgrading Rumi Admin automatically upgrades the bundled Grafana and dashboards.

1. Stop Rumi Admin:

   ```bash
   ~/rumi/rumi-admin/current/stop.sh
   ```
2. Run the Admin installer:

   ```bash
   curl -fsSL https://downloads.n5corp.com/rumi/admin/latest/install.sh | bash
   ```
3. Start the new version:

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

Your Grafana configuration in `data/grafana/conf/server.ini` is preserved across upgrades.

### Standalone Deployment

To upgrade Rumi Monitor dashboards in a standalone Grafana:

1. Export any customizations you've made to existing dashboards.
2. Delete or update the existing dashboards.
3. Import the updated dashboard JSON files from the new Rumi Admin distribution.
4. Re-apply customizations if needed.

{% hint style="info" %}
If you've modified canned dashboards, consider saving your customizations as separate dashboards to avoid losing changes during upgrades.
{% endhint %}

## Troubleshooting

### Dashboards Not Loading (Bundled)

1. Verify Rumi Admin is running:

   ```bash
   curl http://localhost:8001
   ```
2. Check the Grafana configuration file exists:

   ```bash
   ls ~/rumi/rumi-admin/data/grafana/conf/server.ini
   ```
3. If the configuration is corrupted, delete it and restart Admin to regenerate:

   ```bash
   rm ~/rumi/rumi-admin/data/grafana/conf/server.ini
   ~/rumi/rumi-admin/current/start.sh
   ```

### No Data in Dashboards

1. Verify the Rumi Agent is running and collecting heartbeats:

   ```bash
   curl http://localhost:7778/rumi-agent/ping
   ```
2. Check that InfluxDB contains data:

   ```bash
   curl -G 'http://localhost:8086/query' --data-urlencode "db=rumi" --data-urlencode "q=SHOW MEASUREMENTS"
   ```
3. Verify the data source configuration in Grafana points to the correct InfluxDB instance.

### Data Source Connection Failed (Standalone)

1. Verify InfluxDB is accessible from the Grafana host:

   ```bash
   curl http://<influxdb-host>:8086/ping
   ```
2. Check the database name and retention policy are correct.
3. If using authentication, verify the credentials.