README.md

# Project Documentation

This project involves the following stages:

---

## 1. Creating an OpenStack Account

To access our cloud infrastructure, follow these steps:

1. Ensure you are connected to the UAB Campus Network or VPN.
2. Visit [cloud.rc.uab.edu](https://cloud.rc.uab.edu) to verify access.
3. Contact the team to request an account if you don’t have one.

---

## 2. Deploying an Ad-hoc Cluster

### Prerequisite

- **Bright (now Nvidia) cluster key:** A Bright cluster key is required. As of Nov 1, 2024, creating new accounts on Bright's platform is restricted. A limited supply of keys is available.

### Steps to Deploy:

1. Clone the repository:
   ```bash
   git clone git@gitlab.rc.uab.edu:rc/cod-heat-stack.git
   cd cod-heat-stack
   ```

2. Set up a virtual environment and install dependencies:
   ```bash
   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   ```

3. Update the following variables in `group_vars/all`:
   - `ssh_key`: Public SSH key.
   - `product_key`: Bright Easy8 product key.
   - `password`: Plain text password.

4. Deploy the cluster:
   ```bash
   ansible-playbook main.yaml -v
   ```

5. Verify deployment:
   ```bash
   openstack stack list
   ```

### Access the Master Node:

1. Retrieve the floating IP:
   ```bash
   COD_HEAD_IP=$(openstack stack output show <your-stack-name> head_a_floating_ip -f value -c output_value)
   ```

2. SSH into the head node:
   ```bash
   ssh root@$COD_HEAD_IP
   ```

### Additional Steps:

- For OpenOnDemand, login nodes, and compute nodes, refer to the `/CRI_XCBC` directory on the master node and run the respective playbooks.

### Cluster Deletion:

To delete a cluster:
```bash
openstack stack delete -y --wait <your-stack-name>
```

---

## 3. Setting Up a GitLab Runner

GitLab Runners are agents that execute jobs defined in `.gitlab-ci.yml`.

### Types of Runners:

- **Shared:** Available to all projects on the instance.
- **Group:** Available to projects within a group.
- **Project:** Specific to a project.

### Steps to Set Up:

1. **Create an Access Token:**

   - Navigate to `Settings -> Access Tokens` in GitLab.
   - Specify a name, expiration date, role (`Owner`), and scope (`create_runner`).
   - Save the token securely, as it will only be shown once.

2. **Register a Runner:**

   Use the appropriate command for your use case:

   - **Group Runner:**
     ```bash
     curl -sX POST https://<GITLAB_URL>/api/v4/user/runners \
     --data runner_type=<RUNNER_TYPE> \
     --data "group_id=<target_group_id>" \
     --data "description=gitlab-ci-runner" \
     --data "tag_list=<your comma-separated tags>" \
     --header "PRIVATE-TOKEN: <your_access_token>"
     ```

   - **Project Runner:**
     ```bash
     curl -sX POST https://<GITLAB_URL>/api/v4/user/runners \
     --data runner_type=<RUNNER_TYPE> \
     --data "project_id=<target_project_id>" \
     --data "description=gitlab-ci-runner" \
     --data "tag_list=<your comma-separated tags>" \
     --header "PRIVATE-TOKEN: <your_access_token>"
     ```

   - **Shared Runner:**
     ```bash
     curl -sX POST https://<GITLAB_URL>/api/v4/user/runners \
     --data runner_type=<RUNNER_TYPE> \
     --data "group_id=<target_group_or_project_id>" \
     --data "description=shared-runner" \
     --data "tag_list=<your comma-separated tags>" \
     --header "PRIVATE-TOKEN: <your_access_token>"
     ```

### Notes:

- The runner status will display as `Never contacted` until the actual runner is configured.
- Save the `token` value returned by the API for later use.

---

## 4. Building and Deploying Proxy Nodes

### Prerequisites:

- **Docker Desktop:** Ensure Docker is installed and running.
- **GitLab Access:** You should have credentials for GitLab. If using two-factor authentication (2FA), use a personal access token instead of a password.

### Steps:

1. **Authenticate to the GitLab Container Registry:**
   ```bash
   docker login gitlab.rc.uab.edu:4567
   ```

   If you use 2FA, replace your password with a personal access token.

2. **Download or Pull an Image (Optional):**
   ```bash
   docker pull <image_name>:<tag>
   ```

   Replace `<image_name>` and `<tag>` with the actual image name and tag you need.

3. **Tag the Image for GitLab Registry:**
   ```bash
   docker tag <local_image_name>:<tag> gitlab.rc.uab.edu:4567/<your_gitlab_namespace>/<project_name>:<tag>
   ```

   Replace:
   - `<local_image_name>` and `<tag>` with the local image name and tag.
   - `<your_gitlab_namespace>/<project_name>` with your actual GitLab project path.

4. **Push the Image to GitLab’s Container Registry:**
   ```bash
   docker push gitlab.rc.uab.edu:4567/<your_gitlab_namespace>/<project_name>:<tag>
   ```

### Set Up GitLab Environment as the Final Step
To finalize your GitLab environment setup:

1. Go to the **Operate** tab in your GitLab project.
2. Create the desired environment (e.g., `build`, `dev`, or `production`).
3. Assign and configure environment-specific variables as per your requirements.
4. Trigger the pipeline and call the appropriate environment (`build` or `dev`) as needed based on pipeline job requirements.


### Deployment Pipeline:

You can now schedule a pipeline to build and deploy proxy nodes. Use the same process for additional proxy nodes, such as HTTP proxies.

---

## Screenshots

## Deploy and Build Pipeline for SSH Proxy Node

### Build Pipeline Example
Below is a screenshot showing the build pipeline for the SSH proxy node:

![Build Pipeline for SSH Proxy Node](https://gitlab.rc.uab.edu/rc/hpc-factory-proxy-nodes-notes/-/raw/main/screenshots/build_ssh_proxy.png)

### Deploy Pipeline Example
Below is a screenshot showing the deploy pipeline for the SSH proxy node:

![Deploy Pipeline for SSH Proxy Node](https://gitlab.rc.uab.edu/rc/hpc-factory-proxy-nodes-notes/-/raw/main/screenshots/deploy_ssh_proxy.png)

---

## Troubleshooting

1. **Environment Variables Not Working:**
   - Check if the variables are correctly scoped to the environment.
   - Validate the variable values in the **Settings > CI/CD > Variables** section.