Veriviz Continuous Deployment Setup Guide¶

Welcome to Veriviz! This guide will walk you through adding a new service to Veriviz and setting up Continuous Deployment (CD) on UNC’s OKD platform. By the end, you’ll have an automated pipeline that builds and deploys your new service whenever you push to main.

Table of Contents¶

Prerequisites
Step 1: Create or Update Your Dockerfile
Step 2: Set Up an OKD Project
Step 3: Deploy the Service Manually Once
Step 4: Expose a Route (Optional)
Step 5: Create a Build Webhook Secret in OKD
Step 6: Add the Webhook to GitHub Secrets
Step 7: Configure GitHub Actions
Step 8: Commit and Merge
Step 9: Verify Your Deployment
Optional: Adding Secrets (.env) to the Deployment
Tips and Extras

Prerequisites¶

You have GitHub access to the Veriviz repository (public or private).
You have OKD/CloudApps access at UNC (make sure you can log in and select your project).
You have a Dockerfile for your new service or can create one.
You know the name of your new service, e.g. veriviz-newservice.

Step 1: Create or Update Your Dockerfile¶

Place a Dockerfile in your service’s directory, e.g., newservice/Dockerfile.

Example (Node/Express):

FROM node:20

WORKDIR /usr/src/app

COPY package*.json ./
RUN npm install

COPY . .

EXPOSE 8000

CMD [\"node\", \"server.js\"]

Adjust as needed for your framework (Python, Go, etc.).

Step 2: Set Up an OKD Project¶

Log into OKD (UNC’s CloudApps). NOTE: You Must be using eduroam wifi or the UNC VPN to be able to login on your CLI and on the cloudapps website. Learn more about the VPN here.

Navigate to https://cloudapps.unc.edu/ and sign in
Click on your ONYEN in the upper-right of the console and click Copy Login Command
Click Display Token and copy the Login in with this token token which should look like oc login --token=<YOUR_TOKEN> --server=https://api.apps.unc.edu:6443
Open up your project in its devcontainer making sure the OKD CLI is installed in the dev container (you can check this by running oc version)

Log in with the follwoing commands and using your token you copied

oc login --token=<YOUR_TOKEN> --server=https://api.apps.unc.edu:6443
oc project <YOUR_PROJECT_NAME>

Confirm with oc status

Step 3: Deploy the Service Manually Once¶

This will create a BuildConfig, ImageStream, and Deployment for your new service:

oc new-app https://github.com/<user>/<repo>.git#main \
  --context-dir=newservice \
  --name=veriviz-newservice \
  --strategy=docker \
  --labels=app=veriviz-newservice

--context-dir=newservice: Tells OKD to use your newservice folder with the Dockerfile inside. Exmaple for veriviz is frontend.
--name=veriviz-newservice: The name for your build & deployment.

Check the status:

oc logs -f buildconfig/veriviz-newservice

For Private Repositories

If you repository is private, follow these instructions instead of Step 3. Only replace the step 3 instructions with these. Steps 1-2 and 4-12 stay the same.

Step 4: Expose a Route (Optional)¶

If your service needs to be accessible outside of OKD (e.g. from a frontend or public internet):

oc create route edge --service=veriviz-newservice --insecure-policy=Redirect
oc get route veriviz-newservice

You’ll see the URL for your service.

Note

If this service is internal-only, you can skip creating a route.

Step 5: Create a Build Webhook Secret in OKD¶

You want GitHub to trigger builds on pushes/merges. First, find your webhook URL:

oc describe bc/veriviz-newservice | grep -C 1 generic
oc get bc veriviz-newservice -o yaml | grep -C 1 generic

You’ll see something like:

https://api.apps.unc.edu:6443/apis/build.openshift.io/v1/namespaces/<namespace>/buildconfigs/veriviz-newservice/webhooks/<secret>/generic

Copy that URL.

Step 6: Add the Webhook to GitHub Secrets¶

Go to your GitHub Repo → Settings → Secrets and variables → Actions
New Repository Secret:
Name: CD_BUILD_WEBHOOK_VERIVIZ_NEWSERVICE
Value: (paste the full webhook URL)

Name

The name can be anything you want, but make it descirptive in case you dpeloy multiple services form one repo.

Step 7: Configure GitHub Actions¶

Create or edit your .github/workflows/cicd.yml. For example:

name: Veriviz CI/CD Pipeline

on:
  push:
    branches: [ main ]

jobs:
  cd-veriviz-newservice:
    name: \"Continuous Deployment - veriviz-newservice\"
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Trigger OKD Build
        run: |
          curl -X POST ${{ secrets.CD_BUILD_WEBHOOK_VERIVIZ_NEWSERVICE }}

Step 8: Commit and Merge¶

Create a new branch, e.g. feature/newservice-cd.
Push and open a Pull Request.
Once merged into main, GitHub Actions will:
Run the pipeline
Hit the OKD webhook
Trigger a new build & deploy

Note

Alternatively, you can also push directly to the main branch to achieve the same result.

Step 9: Verify Your Deployment¶

Check OKD builds:

oc get builds
oc logs -f bc/veriviz-newservice

Check the service:

oc get pods
oc logs deployment/veriviz-newservice

Check the route (if exposed):
```
oc get route veriviz-newservice
```
Confirm you can hit it in the browser.

Optional: Adding Secrets (.env) to the Deployment¶

If your new service requires environment variables:

Create a .env in newservice/.env (don’t commit to GitHub).

In your dev container:

oc create secret generic veriviz-newservice-env --from-env-file=newservice/.env
oc set env deployment/veriviz-newservice --from=secret/veriviz-newservice-env

replacing veriviz-newservice-env with the name you want for your secret.

On redeploy, your app can read the environment variables inside the container.

Tips and Extras¶

How do I manually rebuild without deleting everything?¶

Use:

oc start-build veriviz-newservice

Or trigger the webhook again:

curl -X POST <your-webhook-URL>

What if I want to rename or delete the service?¶

oc delete all -l app=veriviz-newservice

This removes the BuildConfig, Deployment, Route, and Service labeled app=veriviz-newservice.

What if my repository is private?¶

If Your Repository Is private, then OKD won’t be able to automatically clone it unless you give it credentials. Here’s how:

Generate a GitHub Personal Access Token (classic) with repo read permissions.
Go to your github profile -> Developer Settings -> Personal access tokens -> Tokens(Classics) and copy the PAT after creation

Create a secret in OKD:

oc create secret generic veriviz-newservice-pat \
  --from-literal=username=<GITHUB_USERNAME> \
  --from-literal=password=<YOUR_PAT>

Label the secret so OKD can find it:

oc label secret veriviz-newservice-pat app=veriviz-newservice

Create the new app using the secret:

oc new-app https://github.com/<user>/<private-repo>.git#main \
  --context-dir=newservice \
  --name=veriviz-newservice \
  --strategy=docker \
  --source-secret=veriviz-newservice-pat \
  --labels=app=veriviz-newservice

The rest (webhook, route, secrets for .env) is the same as above.

Note

The --source-secret=veriviz-newservice-pat is critical so OKD can clone your private repo.