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

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

{% hint style="info" %}
Rumi Admin bundles its own Node.js runtime and Grafana instance. No external dependencies are required.
{% endhint %}

## Quick Start

### Standard Installation

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

```bash
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:

```bash
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:

```json
{
  "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](/rumi-management/reference/admin/configuration.md) 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

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

Options:

* `--verbose` — Show detailed output
* `--foreground` or `-f` — Run in foreground mode (for Docker)

### Stop Rumi Admin

```bash
~/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:

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

```bash
# 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

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

### Listing All Installed Versions

```bash
ls ~/rumi/rumi-admin/releases/
```

## Docker Deployment

Rumi Admin can be deployed as a Docker container.

### Building the Docker Image

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

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

```bash
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:

   ```bash
   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.