> 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/installation/rpm/rpm-single-node/install.md).

# Install

Install the package, configure the deployment, and run the initialisation that builds every tier.

## What this builds, and how long it takes

<table><thead><tr><th width="130.79998779296875"></th><th></th></tr></thead><tbody><tr><td><strong>You get</strong></td><td>A single host running the complete OpenIAM platform — application services, database, message broker, cache, graph and search tiers</td></tr><tr><td><strong>Time</strong></td><td>60–90 minutes, most of it unattended</td></tr><tr><td><strong>Hosts</strong></td><td>One</td></tr><tr><td><strong>Downtime</strong></td><td>One host restart, scheduled by the installation</td></tr><tr><td><strong>Reversible</strong></td><td>The package can be removed. Configuration files, the service account and host settings remain</td></tr></tbody></table>

## Before you start

**Must exist**

* A host meeting [*What you need*](/installation/what-you-need.md).
* `tar` installed. The package requires it and the installation extracts several archives:

  <pre class="language-bash" data-overflow="wrap"><code class="lang-bash">dnf install -y tar
  </code></pre>
* `jq` installed, or let the installation add it. It is used by the status and health tooling.
* The OpenIAM package on the host. If the host is air-gapped, have the four components from [*Obtain the software*](/installation/obtain-the-software.md) ready to copy — they go into `/usr/local/openiam`, which is created in step 1.
* `root`, or full `sudo`.

**Must be decided**

* Environment: non-production or production.
* Database: a local MariaDB installed for you, or your own remote server. For remote, read [*Use a remote database*](/installation/rpm/rpm-single-node/use-a-remote-database.md) first.
* Database engine: MariaDB or MySQL, PostgreSQL, Microsoft SQL Server, or Oracle Database. **Fixed after installation.**
* Whether to install the bundled monitoring stack.

**Decide where OpenIAM will live**

OpenIAM installs into `/usr/local/openiam`, which is on the root filesystem, and the installation checks free space on `/`. If your host keeps its capacity on a separate partition — a dedicated `/opt`, a mounted data volume, or an LVM volume provisioned for applications — follow [*Install on a separate partition*](/installation/rpm/rpm-single-node/separate-partition.md). It is a two-command step inserted between installing the package and running the initialisation.

**Decide this now.** Once the deployment is initialised, paths are recorded throughout and relocating it is no longer a matter of moving a directory.

**Confirm the host is ready for a first installation**

{% code overflow="wrap" %}

```bash
ls /usr/local/openiam/initialized
```

{% endcode %}

Expected: `No such file or directory`. If the file exists, this host has already been initialised.

## Set these first

{% code overflow="wrap" %}

```bash
export OPENIAM_VERSION=<your release, for example 2026.8.1>
```

{% endcode %}

***

## Build it

### 1. Install the package

> **Plan for one restart.**
>
> OpenIAM runs with raised file-descriptor limits. The package sets them and restarts the host once, one minute after installation, so they take effect before the platform starts. You will see:
>
> ```
> The server will be restarted in 1 min to apply ulimit settings ...
> ```
>
> Schedule this step inside your change window. To cancel the restart, run `shutdown -c` within that minute.

{% code overflow="wrap" %}

```bash
yum install -y "./openiam-$OPENIAM_VERSION.noarch.x86_64.rpm"
```

{% endcode %}

**What it does:** unpacks the platform into `/usr/local/openiam`, creates the `openiam` service account, sets the file-descriptor limits, and schedules the restart.

**What you should see:** the package transaction summary, followed by the restart notice.

**How long:** 1–2 minutes, then the restart.

### 2. Confirm the limits are in effect

After the host is back:

{% code overflow="wrap" %}

```bash
ulimit -Hn
```

{% endcode %}

**Expected: `65536`.**

### 3. Relocate the install directory, if it is not staying on the root filesystem

If OpenIAM is going on a different partition, do it now — before the initialisation. See [*Install on a separate partition*](/installation/rpm/rpm-single-node/separate-partition.md), then return here.

### 4. Stage the components, if the host is air-gapped

`/usr/local/openiam` now exists. Follow [*Obtain the software*](/installation/obtain-the-software.md) and confirm all four components are in place.

### 5. Configure the deployment

Edit `/usr/local/openiam/env.conf`. [*Settings*](/installation/settings.md) documents everything this procedure uses; set these now:

<table><thead><tr><th width="207.60000610351562">Setting</th><th>Value</th></tr></thead><tbody><tr><td><code>INTERNET_AVAILABLE</code></td><td><code>false</code> for an air-gapped host</td></tr><tr><td><code>FLYWAY_DATABASE_TYPE</code></td><td><code>mysql</code>, <code>postgres</code>, <code>mssql</code> or <code>oracle</code>. <strong>Fixed after installation.</strong> The initialisation also asks — type your choice at the prompt rather than accepting the default</td></tr><tr><td><code>VAULT_JKS_PASSWORD</code></td><td>Set your own value before installing</td></tr><tr><td><code>SEARCH_ENGINE</code></td><td><code>OS</code> for OpenSearch, <code>ES</code> for Elasticsearch</td></tr></tbody></table>

On a single-node deployment, leave the cluster host lists at their defaults.

Treat this file as sensitive — it holds credentials for the deployment.

### 6. Run the initialisation

**Run it inside a terminal multiplexer.** The initialisation takes most of an hour, and a dropped SSH session ends it:

{% code overflow="wrap" %}

```bash
dnf install -y screen
screen -S openiam-install
```

{% endcode %}

Detach with **Ctrl+A** then **D**; reattach later with `screen -r openiam-install`.

{% code overflow="wrap" %}

```bash
openiam-cli init
```

{% endcode %}

The initialisation asks you a series of questions, in five groups. Between them it runs unattended, so the whole thing takes most of an hour with perhaps ten minutes of your attention.

**What it asks, in order:**

**Group 1 — the shape of the deployment**, at the very start:

1. **Environment** — `1` for non-production, `2` for production. The host is checked against the requirements for your selection.
2. **Internet access** — `y` or `n`.
3. **Install MariaDB locally?** — `y` installs and secures a local MariaDB, taking you through `mariadb-secure-installation`; set and record a root password when prompted. Answer `n` for a remote database.

**Group 2 — the credentials the platform will use**, once the secret store is up. This block is marked `CRITICAL SECTION` and is the most important part of the run:

4. **A username and password for each of the eight schemas**, then **a password for the message broker, the cache and the cache's failover watchers**, then **the search tier's username and password**. Each prompt offers a default. **Type your own values** — these become the live credentials the platform authenticates with for the life of the deployment, and they are written into the secret store, not into a file you can edit later.

   Your typing is not echoed. The installation then prints the collected values for you to confirm before it proceeds; **treat that screen as sensitive** and answer `y` only once it is right.
5. **Enable TLS for the cache?** — `y` or `n`.

**Group 3 — the database**, immediately after:

6. **Create the schemas and their accounts?** — answer `y` if the schemas do not exist yet. It then asks for a database super-user name and password, which it uses once and does not store.
7. **Is this a managed database service?** — `y` for a cloud database such as RDS or Azure Database.
8. **Engine, baseline version, the eight schema names, and a host and port for each schema.** The defaults are recommended. **The host and port are asked once per schema — eight times** — so on a single database server you supply the same answer eight times. See [*Use a remote database*](/installation/rpm/rpm-single-node/use-a-remote-database.md).

**Group 4 — the reverse proxy**, once the infrastructure tiers are built:

9. **Install the OpenIAM reverse proxy module?** — answer `y`. This installs Apache `httpd` with `mod_openiam`, which is how users reach the platform, and opens ports 80 and 443. Answer `n` only if you are terminating traffic at a proxy you run yourself and have read [*Configure the reverse proxy*](/installation/rpm/rpm-single-node/configure-the-reverse-proxy.md) first.

**Group 5 — monitoring**, last:

10. **Install the Prometheus and Grafana monitoring stack?** — `y` or `n`. Optional, and it requires OpenSearch as the search tier. Installing it restarts the search tier once, mid-run.

**Set the credentials in group 2 rather than accepting the defaults.** It is the one part of the installation that is materially harder to change afterwards, and the one a security review will ask about first.

### Record what the installation gives you

Two things come out of the run and are needed later. **Capture both before you move on.**

**The secret store's unseal keys and root token.** They are what opens the store if it is ever sealed — after an unclean host restart, or on a restore. They are not held anywhere you can re-derive them from.

**The initial administrator account** for the console. You sign in with it and change its password in [*First sign-in*](/installation/rpm/rpm-single-node/first-sign-in.md).

Both appear in the run output and in the installation log:

{% code overflow="wrap" %}

```bash
grep -iE 'unseal|root token|administrator' /usr/local/openiam/init.log
```

{% endcode %}

Put them wherever your organisation keeps break-glass credentials, then **treat `init.log` as sensitive** — it records the configuration of the deployment. Copy it somewhere appropriate and remove it from the host.

**What it does:** configures the secret store, the graph tier and its storage, the search tier, the message broker, the cache, the database schemas and the reverse proxy, then starts the platform. The last step configures the interface router and waits for all six interface services to report healthy before starting it, so the closing minutes of the run are normal waiting rather than a stall.

**What you should see:** configuration output for each tier in turn, ending with the platform starting.

Two things worth recognising as you watch it:

* **A `CRITICAL SECTION` banner** marks the points where the installation needs your input. Between them it runs unattended.
* **While the graph storage tier starts**, the output includes Java messages about the cluster not yet having nodes. The installation waits for the tier and continues once it reports `UN 127.0.0.1 … Cassandra is ready to use`.

**How long:** 45–75 minutes.

**Do not paste the confirmation screens into a ticket or a chat.** The installation echoes the values you entered, including credentials, so you can check them before it proceeds.

### 7. Verify the deployment

Go to [*Start and verify*](/installation/rpm/rpm-single-node/start-and-verify.md) and work through the checks. Keep the output with your build record.

***

## Verify it

{% code overflow="wrap" %}

```bash
rpm -q openiam
ls /usr/local/openiam/initialized
pgrep -c -u openiam java
```

{% endcode %}

**Expected:** the package installed, the marker file present, and twenty or more processes.

**This is a smoke test, not the verification.** Go to [*Start and verify*](/installation/rpm/rpm-single-node/start-and-verify.md) and work through it — the installation's own closing output is not sufficient evidence on its own.

***

## If it goes wrong

| What you see                                             | What it means                                                      | What to do                                                                                     |
| -------------------------------------------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| A message that free disk space or available RAM is short | The host is below the requirement for the environment you selected | Provision to [*What you need*](/installation/what-you-need.md) and run again                   |
| `Disable the swap and run openiam-cli init again`        | A swap device is active                                            | `swapoff -a`, remove the entry from `/etc/fstab`, run again                                    |
| `OpenIAM is already initialized`                         | This host has been initialised before                              | Reinstall the package for a clean host                                                         |
| A message asking you to download a component manually    | A component was not retrieved                                      | Stop, place the file at the path in the message, and start again                               |
| Package errors during an air-gapped installation         | The dependency repository does not match the host's EL version     | Confirm it matches `PLATFORM_ID`, replace it, and restart the procedure                        |
| Your package repositories are set aside afterwards       | An air-gapped run did not reach its final step                     | Restore them with the command in [*Obtain the software*](/installation/obtain-the-software.md) |

[*Troubleshoot*](/installation/rpm/rpm-single-node/troubleshoot.md) covers start-up and runtime issues.

## What this procedure does not cover

* **Firewall rules beyond the platform's own.** The installation opens ports 80 and 443 when you install the reverse proxy and firewalld is active — those are the only ports users need. Rules for your database server or connector targets are yours to add.
* **TLS certificates for the user interfaces.** The deployment starts behind the bundled proxy on HTTP; configure TLS as part of your hardening.
* **Tuning.** The deployment starts with default sizing. Cache, batch, pool and rate-limit properties are on [Configuration tuning reference](/installation/tuning.md); sizing for your expected load is not documented yet — ask OpenIAM support.
* **Application configuration.** Managed systems, roles, policies and campaigns are the [Administration Guide](/administration-guide/admin.md).

## Related

* [*Start and verify*](/installation/rpm/rpm-single-node/start-and-verify.md)
* [*Configure*](/installation/rpm/rpm-single-node/configure.md)
* [*Use a remote database*](/installation/rpm/rpm-single-node/use-a-remote-database.md)
* [*Ports*](/installation/rpm/rpm-single-node/ports.md)

*Applies to OpenIAM 2026.8.1.*


---

# 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/installation/rpm/rpm-single-node/install.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.