# 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 ](https://run-ai-docs.nvidia.com/self-hosted/2.22/getting-started/installation/install-using-helm/install-control-plane)and [cluster](https://run-ai-docs.nvidia.com/self-hosted/2.22/getting-started/installation/install-using-helm/helm-install).

### 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](https://run-ai-docs.nvidia.com/self-hosted/2.22/getting-started/installation/cp-system-requirements#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> \
   ```