# Preparations

The following section provides the information needed to prepare for a NVIDIA Run:ai installation.

## Software Artifacts

The following software artifacts should be used when installing the [control plane ](/self-hosted/2.23/getting-started/installation/install-using-helm/install-control-plane.md)and [cluster](/self-hosted/2.23/getting-started/installation/install-using-helm/helm-install.md).

### Kubernetes

<details>

<summary>Connected</summary>

You will receive a token from NVIDIA Run:ai to access the NVIDIA Run:ai container registry. Use the following command to create the required Kubernetes secret:

<pre class="language-bash"><code class="lang-bash"><strong>kubectl create secret docker-registry runai-reg-creds  \
</strong>--docker-server=https://runai.jfrog.io \
--docker-username=self-hosted-image-puller-prod \
--docker-password=&#x3C;TOKEN> \
--docker-email=support@run.ai \
--namespace=runai-backend
</code></pre>

</details>

<details>

<summary>Air-gapped</summary>

You will receive a token from NVIDIA Run:ai to access the NVIDIA Run:ai air-gapped installation package. Use the following commands with the token provided by NVIDIA Run:ai to download and extract the package.

**Download and Extract the Air-gapped Package**

1. Run the following command to browse all available air-gapped packages:

   ```bash
   curl -H "Authorization: Bearer <token>" "https://runai.jfrog.io/artifactory/api/storage/runai-airgapped-prod/?list"
   ```
2. Run the following command to download the desired package:

   ```bash
   curl -L -H "Authorization: Bearer <token>" -O "https://runai.jfrog.io/artifactory/runai-airgapped-prod/runai-airgapped-package-<VERSION>.tar.gz"
   ```
3. SSH into a node with `kubectl` access to the cluster and Docker installed.
4. Extract the NVIDIA Run:ai package and replace `<VERSION>` in the command below and run:

   ```bash
   tar xvf runai-airgapped-package-<VERSION>.tar.gz
   ```

**Upload Images**

NVIDIA Run:ai assumes the existence of a Docker registry within your organization for hosting container images. The installation requires the network address and port for this registry (referred to as `<REGISTRY_URL>`).

1. Upload images to a local Docker Registry. Set the Docker Registry address in the form of `NAME:PORT` (do not add `https`):

   ```bash
   export REGISTRY_URL=<DOCKER REGISTRY ADDRESS>
   ```
2. Run the following script. You must have at least 20GB of free disk space to run. If Docker is configured to [run as non-root](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user) then `sudo` is not required:

   ```bash
   sudo ./setup.sh
   ```

The script should create a file named `custom-env.yaml` which will be used during control plane installation.

</details>

### OpenShift

<details>

<summary>Connected</summary>

You will receive a token from NVIDIA Run:ai to access the NVIDIA Run:ai container registry. Use the following command to create the required Kubernetes secret:

```bash
oc create secret docker-registry runai-reg-creds  \
--docker-server=https://runai.jfrog.io \
--docker-username=self-hosted-image-puller-prod \
--docker-password=<TOKEN> \
--docker-email=support@run.ai \
--namespace=runai-backend
```

</details>

<details>

<summary>Air-gapped</summary>

You will receive a token from NVIDIA Run:ai to access the NVIDIA Run:ai air-gapped installation package. Use the following commands with the token provided by NVIDIA Run:ai to download and extract the package.

**Download and Extract the Air-gapped Package**

1. Run the following command to browse all available air-gapped packages:

   ```bash
   curl -H "Authorization: Bearer <token>" "https://runai.jfrog.io/artifactory/api/storage/runai-airgapped-prod/?list"
   ```
2. Run the following command to download the desired package:

   ```bash
   curl -L -H "Authorization: Bearer <token>" -O "https://runai.jfrog.io/artifactory/runai-airgapped-prod/runai-airgapped-package-<VERSION>.tar.gz"
   ```
3. SSH into a node with `oc` access to the cluster and Docker installed.
4. Extract the NVIDIA Run:ai package and replace `<VERSION>` in the command below and run:

   ```bash
   tar xvf runai-airgapped-package-<VERSION>.tar.gz
   ```

**Upload Images**

NVIDIA Run:ai assumes the existence of a Docker registry within your organization for hosting container images. The installation requires the network address and port for this registry (referred to as `<REGISTRY_URL>`).

1. Upload images to a local Docker Registry. Set the Docker Registry address in the form of `NAME:PORT` (do not add `https`):

   ```bash
   export REGISTRY_URL=<DOCKER REGISTRY ADDRESS>
   ```
2. Run the following script. You must have at least 20GB of free disk space to run. If Docker is configured to [run as non-root](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user) then `sudo` is not required:

   ```bash
   sudo ./setup.sh
   ```

The script should create a file named `custom-env.yaml` which will be used by the control plane installation.

</details>

## Private Docker Registry (Optional)

<details>

<summary>Kubernetes</summary>

To access the organization's docker registry it is required to set the registry's credentials (imagePullSecret).

Create the secret named `runai-reg-creds` based on your existing credentials. For more information, see [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/).

</details>

<details>

<summary>OpenShift</summary>

To access the organization's docker registry it is required to set the registry's credentials (imagePullSecret).

Create the secret named `runai-reg-creds` in the `runai-backend` namespace based on your existing credentials. The configuration will be copied over to the `runai` namespace at cluster install. For more information, see [Allowing pods to reference images from other secured registries](https://docs.openshift.com/container-platform/latest/openshift_images/managing_images/using-image-pull-secrets.html#images-allow-pods-to-reference-images-from-secure-registries_using-image-pull-secrets).

</details>

## Set Up Your Environment

### External Postgres Database (Optional)

If you have opted to use an [external PostgreSQL database](/self-hosted/2.23/getting-started/installation/install-using-helm/cp-system-requirements.md#external-postgres-database-optional), you need to perform initial setup to ensure successful installation. Follow these steps:

1. Create a SQL script file, edit the parameters below, and save it locally:

   * Replace `<DATABASE_NAME>` with a dedicate database name for NVIDIA Run:ai in your PostgreSQL database.
   * Replace `<ROLE_NAME>` with a dedicated role name (user) for NVIDIA Run:ai database.
   * Replace `<ROLE_PASSWORD>` with a password for the new PostgreSQL role.
   * Replace `<GRAFANA_PASSWORD>` with the password to be set for Grafana integration.

   ```sql
   -- Create a new database for runai
   CREATE DATABASE <DATABASE_NAME>; 

   -- Create the role with login and password
   CREATE ROLE <ROLE_NAME>  WITH LOGIN PASSWORD '<ROLE_PASSWORD>'; 

   -- Grant all privileges on the database to the role
   GRANT ALL PRIVILEGES ON DATABASE <DATABASE_NAME> TO <ROLE_NAME>; 

   -- Connect to the newly created database
   \c <DATABASE_NAME> 

   -- grafana
   CREATE ROLE grafana WITH LOGIN PASSWORD '<GRAFANA_PASSWORD>'; 
   CREATE SCHEMA grafana authorization grafana;
   ALTER USER grafana set search_path='grafana';
   -- Exit psql
   \q
   ```
2. Run the following command on a machine where PostgreSQL client (`pgsql`) is installed:

   * Replace `<POSTGRESQL_HOST>` with the PostgreSQL ip address or hostname.
   * Replace `<POSTGRESQL_USER>` with the PostgreSQL username.
   * Replace `<POSTGRESQL_PORT>` with the port number where PostgreSQL is running.
   * Replace `<POSTGRESQL_DB>` with the name of your PostgreSQL database.
   * Replace `<POSTGRESQL_DB>` with the name of your PostgreSQL database.
   * Replace `<SQL_FILE>` with the path to the SQL script created in the previous step.

   ```bash
   psql --host <POSTGRESQL_HOST> \ 
   --user <POSTGRESQL_USER> \
   --port <POSTGRESQL_PORT> \ 
   --dbname <POSTGRESQL_DB> \
   -a -f <SQL_FILE> \
   ```


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://run-ai-docs.nvidia.com/self-hosted/2.23/getting-started/installation/install-using-helm/preparations.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.