> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/getting-started-guide/install-openiam-rpm.md).

# Install OpenIAM from RPM

Install the full OpenIAM stack on a single Linux VM with the RPM installer.

**Goal:** the full OpenIAM stack installed and initialized on the Linux host.\
**Time:** 60–90 minutes, much of it waiting on downloads and service startup.\
**Prerequisites:** [Prepare your lab](/getting-started-guide/prepare-your-lab.md) complete; RPM downloaded and checksum-verified in `/usr/src`.

## Before you start: two things the installer will do to you

{% hint style="warning" %}

1. **It reboots the server.** Installing the RPM schedules a reboot in 1 minute (to apply ulimit settings). Don't panic; don't fight it. `shutdown -c` cancels it if you must, but rebooting is the supported path.
2. **It refuses to run twice — after success.** `openiam-cli init` marks the host initialized only when it completes. If init *fails or is aborted partway* (resource check, download error, database step), fix the cause and simply run `openiam-cli init` again — it skips already-downloaded artifacts. Only a *completed* init can't be re-run; to redo one of those, use the reset procedure at the bottom of this page.
   {% endhint %}

{% stepper %}
{% step %}
**Install the package**

{% code overflow="wrap" %}

```bash
cd /usr/src
sudo rpm -i openiam-2026.7.1.noarch.x86_64.rpm
```

{% endcode %}

This unpacks the stack to `/usr/local/openiam`, installs the `openiam-cli` command, creates the `openiam` OS user, raises file-descriptor limits — and schedules the reboot. Let the machine reboot, then log back in.
{% endstep %}

{% step %}
**Run the initializer**

{% code overflow="wrap" %}

```bash
sudo openiam-cli init
```

{% endcode %}

Everything is logged to `/usr/local/openiam/init.log`. The prompts, in order:

| Prompt                                 | Answer for this guide                                                                                                                                      |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Environment type                       | `1` (Non-Production / Dev — 80 GB disk, 48 GB RAM minimums are enforced here)                                                                              |
| Does this box have Internet access?    | `y`                                                                                                                                                        |
| Install MariaDB RDBMS locally?         | `y` for the MariaDB golden path (see below for PostgreSQL)                                                                                                 |
| `mariadb-secure-installation`          | Runs interactively: set a root password, remove anonymous users, disallow remote root, remove the test DB, reload privileges. **Record the root password** |
| Enable TLS for Redis?                  | `n` for the POC                                                                                                                                            |
| Database/Flyway section                | See step 3                                                                                                                                                 |
| Install OpenIAM reverse proxy module?  | `y` — this installs Apache httpd + `mod_openiam` and opens ports 80/443 in firewalld                                                                       |
| Install Prometheus+Grafana monitoring? | `y` (optional but cheap; Grafana on :3000, default admin/admin)                                                                                            |

The initializer downloads the dependency repo, backend and frontend binaries, and the LDAP connector for your OS release (it detects el9 from `/etc/os-release`), then initializes Vault, Cassandra/JanusGraph, OpenSearch, RabbitMQ, and Redis before the database section.
{% endstep %}

{% step %}
**Database section (Flyway)**

The installer asks for the seven OpenIAM schema names (accept defaults: `openiam`, `activiti`, `groovy`, `auditlog`, `batchtasks`, `pbac`, `certification`), the database type, host and port, and whether to initialize the schema and users.

**MariaDB (golden path):** database type `mysql`, host `localhost`, port `3306`, answer `y` to "initialize OpenIAM Schema and Users", and supply the root password from step 2. Schema creation runs automatically. Review the validation summary and confirm with `y`.

**PostgreSQL (variant):** the installer never installs PostgreSQL — provision it yourself first (local or remote server, reachable from this host, with a superuser). Then: database type `postgres`, your host and port (`5432`), `y` to initialize. For PostgreSQL the installer **writes the init SQL to `/tmp/init.sql` and asks you to run it manually** against your server:

{% code overflow="wrap" %}

```bash
psql -h <pg-host> -U postgres -f /tmp/init.sql
rm /tmp/init.sql   # it contains secrets — remove it after initialization
```

{% endcode %}

Re-run init after the schema exists (a failed database stage does not mark the host initialized, so init runs again cleanly). The installer also asks whether the database is a managed service like AWS RDS — those need `log_bin_trust_function_creators = 1` set on the instance; answer `y` there if so.
{% endstep %}

{% step %}
**First start**

At the end, init enables the systemd timers, starts the stack, and configures nginx. First startup takes **10–15 minutes** — services come up in dependency order.

One architecture note so later pages make sense: there are **two web layers**. Apache httpd with `mod_openiam` (installed by the reverse-proxy step) is the public entry point on ports 80/443; behind it, an internal nginx on port 8080 fronts the individual UI applications. You configure certificates on Apache ([next page](/getting-started-guide/enable-https.md)); you never touch nginx directly.

{% code overflow="wrap" %}

```bash
openiam-cli status        # per-service health
openiam-cli log           # follow the startup log (Ctrl-C to stop)
curl -k -I -L http://127.0.0.1/idp/login   # expect HTTP 200 when the stack is up
```

{% endcode %}

Useful commands from here on: `openiam-cli start | stop | status | log [service]`.
{% endstep %}
{% endstepper %}

## If it failed

| Symptom                                  | Likely cause                                                                                                      |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Init exits immediately citing RAM/disk   | VM below 48 GB RAM / 80 GB free on `/` — resize, re-run `openiam-cli init`                                        |
| Init exits citing swap                   | `swapoff -a` and remove swap from `/etc/fstab`, re-run                                                            |
| Downloads fail                           | No route to `download.openiam.com` — fix egress or use the [offline installation guide](https://docs.openiam.com) |
| `openiam-cli start` says not initialized | Init didn't complete — check `/usr/local/openiam/init.log` for the failing stage                                  |
| Services stuck starting                  | Check `infra.status` gating and per-service logs in `/usr/local/openiam/logs/`                                    |

## Starting over (uninstall / reset)

A *failed* init can simply be re-run (see the top of this page). Use this reset when init **completed** but you want different answers — or when you just want a guaranteed-clean slate:

{% code overflow="wrap" %}

```bash
sudo openiam-cli stop
sudo rpm -e openiam
sudo rm -rf /usr/local/openiam          # data and config are NOT removed by rpm -e
sudo userdel -r openiam 2>/dev/null
```

{% endcode %}

If you installed MariaDB locally and want a truly clean slate, also remove it and its data (`yum remove mariadb-server && rm -rf /var/lib/mysql`), and remove `/etc/httpd/conf.d/mod_openiam*.conf` if the proxy was installed. On a lab VM the fastest reset of all is a hypervisor snapshot taken right before `rpm -i` — take one now if you haven't.

## You know this worked when…

{% hint style="success" %}
`openiam-cli status` reports the backend services and UI apps healthy, and `curl -k -I -L http://127.0.0.1/idp/login` returns 200.
{% endhint %}

Next: [Enable HTTPS](/getting-started-guide/enable-https.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openiam.com/getting-started-guide/install-openiam-rpm.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.