> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.eyelevel.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.eyelevel.ai/_mcp/server.

## Installing GroundX On-Prem on OpenShift

Install [GroundX On-Prem](https://github.com/eyelevelai/groundx-on-prem) on OpenShift, Red Hat's container platform. This free, open source deployment includes the components needed to run retrieval augmented generation (RAG) in a controlled environment.

This guide adapts the [AWS EKS installation guide](https://docs.eyelevel.ai/documentation/ground-x-on-prem/ground-x-on-prem-on-aws) for OpenShift.

See [Choose Your GroundX Path](/documentation/get-started/choose-your-ground-x-path) to compare deployment options, including managing an on-prem instance with GroundX Agent Harness.

---

**⚠️ Warning ⚠️**

**Resources created by this guide may incur charges. OpenShift experience is recommended.**

---

### Prerequisites

Before starting, ensure you have:

1. A running OpenShift cluster, on-premises or in a cloud provider.
2. Node Feature Discovery and the NVIDIA GPU Operator installed ([link](https://docs.nvidia.com/datacenter/cloud-native/openshift/latest/index.html))

### 1) Defining the Infrastructure

Clone the repository:

```
git clone https://github.com/eyelevelai/groundx-on-prem.git
```

Create the configuration file:

```
cd groundx-on-prem/
cp operator/env.tfvars.example-openshift operator/env.tfvars
```

`operator/env.tfvars` defines the Terraform resources. The copied example uses the default OpenShift configuration. Edit it to suit your deployment.

### 2) Update admin information in env.tfvars

For security, we strongly recommend changing these values in `operator/env.tfvars`:

* `admin.api_key`: Set a random UUID, generated with `bin/uuid`. This is the admin API key used for inter-service communication.
* `admin.username`: Set a random UUID, generated with `bin/uuid`. This is the admin user ID used for inter-service communication.
* `admin.email`: Set the admin account email address.

### 3) Update Persistent Volume Class Definition in env.tfvars

Many GroundX pods require persistent volumes (PVs). Define a storage class in the OpenShift cluster for these pods.

Set `cluster.pv` in `operator/env.tfvars` to use that storage class. The default is:

```
name = "eyelevel-pv"
type = "ocs-storagecluster-ceph-rbd"
```

### 4) Label Nodes

GroundX pods can use 1 to 5 node groups, depending on how you allocate resources for the 5 pod classes. By default, `cluster.nodes` in `env.tfvars` assigns a separate node group to each class:

```
nodes            = {
      cpu_memory     = "eyelevel-cpu-memory"
      cpu_only       = "eyelevel-cpu-only"
      gpu_layout     = "eyelevel-gpu-layout"
      gpu_ranker     = "eyelevel-gpu-ranker"
      gpu_summary    = "eyelevel-gpu-summary"
    }
```

The GPU node groups and resource needs in a default installation are:

* gpu_layout
  * 0.5 vCPU
  * 2 GB RAM
  * 8 GB of GPU memory
  * \~10 GB hard disk space
* gpu_ranker
  * 1.5 vCPU
  * 4 GB RAM
  * 8 GB of GPU memory
  * \~10 GB hard disk space
* gpu_summary
  * 1 vCPU
  * 4 GB RAM
  * 40 GB of GPU memory
  * \~40 GB hard disk space

The CPU node groups and resource needs in a default installation are:

* cpu_memory
  * 3.2 vCPU
  * 2.5 GB RAM
  * \~10 GB hard disk space
* cpu_only
  * 3.5 vCPU
  * 7 GB RAM
  * \~120 GB hard disk space

To use 1 node group with enough resources for all 5 pod classes, set the labels in `cluster.nodes` within `env.tfvars` to:

```
nodes            = {
      cpu_memory     = "eyelevel-node"
      cpu_only       = "eyelevel-node"
      gpu_layout     = "eyelevel-node"
      gpu_ranker     = "eyelevel-node"
      gpu_summary    = "eyelevel-node"
    }
```

To use separate CPU and GPU node groups with enough resources for all 5 pod classes, set the labels to:

```
nodes            = {
      cpu_memory     = "eyelevel-cpu"
      cpu_only       = "eyelevel-cpu"
      gpu_layout     = "eyelevel-gpu"
      gpu_ranker     = "eyelevel-gpu"
      gpu_summary    = "eyelevel-gpu"
    }
```

### 5) Deploying GroundX

Deploy GroundX with the saved configuration:

```
./operator/setup
```

This deploys GroundX On-Prem to the configured OpenShift cluster.

### 6) Setting Up A Client To Talk TO GroundX On-Prem

Run `kubectl -n eyelevel get route` to find the API endpoint for the SDK. Use the address associated with the GroundX load balancer.

Example address:

```
EXTERNAL-IP
groundx-service-eyelevel.apps.ocp.psdc.lan
```

Configure the SDK with that API endpoint and the `admin.api_key` from step 2:

**`Python`**

```python title="Python"
from groundx import GroundX

external_ip = "groundx-service-eyelevel.apps.ocp.psdc.lan"
api_key="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

client = GroundX(api_key=api_key, base_url=f"http://{external_ip}/api")
```

**`TypeScript`**

```typescript title="TypeScript"
import { GroundXClient } from "groundx";

const externalIp = "groundx-service-eyelevel.apps.ocp.psdc.lan";
const apiKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

const client = new GroundXClient({ apiKey: apiKey, environment: `http://${externalIp}/api` });
```

The client works similarly to a client connected to [hosted GroundX](https://dashboard.eyelevel.ai/auth/login). See the [API Documentation](https://documentation.eyelevel.ai/docs/welcome) for endpoint details and tutorials.

## Protected file prerequisites

Follow [File Access and Sharing](/documentation/fundamentals/file-access-and-sharing) using the deployment's local API, file gateway, and signing endpoints. Before ingesting protected files, verify:

* Private storage origins.
* Compatible API, processor, and gateway images.
* Policy, cache, and database readiness.
* Protection for existing files.

Test each advertised storage backend and TLS certificate trust path at pinned versions. S3 compatibility alone does not establish vendor support. Verify local MCP transport authentication; do not assume it uses hosted OAuth.