From 6886e2a5198fc3baead0f3044844b499cca83f45 Mon Sep 17 00:00:00 2001 From: Anh Hoang Nguyen Date: Tue, 19 Sep 2023 15:17:03 -0400 Subject: [PATCH] init --- .gitignore | 1 + README.md | 17 +++++ book.toml | 6 ++ src/README.md | 1 + src/SUMMARY.md | 7 ++ src/jenkins-pipeline/setup.md | 72 ++++++++++++++++++++ src/jenkins-pipeline/template.md | 110 +++++++++++++++++++++++++++++++ src/nvidia/drivers.md | 34 ++++++++++ 8 files changed, 248 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100644 book.toml create mode 100644 src/README.md create mode 100644 src/SUMMARY.md create mode 100644 src/jenkins-pipeline/setup.md create mode 100644 src/jenkins-pipeline/template.md create mode 100644 src/nvidia/drivers.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..7585238 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +book diff --git a/README.md b/README.md new file mode 100644 index 0000000..e62fcb7 --- /dev/null +++ b/README.md @@ -0,0 +1,17 @@ +# CERC Software Development Team Documentation + +This repository contains the CERC Software Development Team's documentation. + +## Prerequisites + +- [Git](https://git-scm.com/) +- [Rust](https://www.rust-lang.org/tools/install) + - [mdbook](https://rust-lang.github.io/mdBook/guide/installation.html) + +## Editing + +- Clone this repo: `git clone https://nextgenerations-cities.encs.concordia.ca/gitea/a_nguyen/dev-docs-tmp` +- `cd` into the repo: `cd /path/to/dev-docs-tmp` +- Run `mdbook serve --open` to start the development server. +- Edit the markdown files in the `src` folder. +- After making edits, commit and push the changes. diff --git a/book.toml b/book.toml new file mode 100644 index 0000000..015456b --- /dev/null +++ b/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["Anh Hoang Nguyen"] +language = "en" +multilingual = false +src = "src" +title = "CERC Developer Docs" diff --git a/src/README.md b/src/README.md new file mode 100644 index 0000000..c8447c6 --- /dev/null +++ b/src/README.md @@ -0,0 +1 @@ +# CERC Developer Guide, Tutorial, and Reference diff --git a/src/SUMMARY.md b/src/SUMMARY.md new file mode 100644 index 0000000..1b244b3 --- /dev/null +++ b/src/SUMMARY.md @@ -0,0 +1,7 @@ +# Summary + +- [Jenkins Pipeline]() + - [Pipeline setup](./jenkins-pipeline/setup.md) + - [Pipeline template](./jenkins-pipeline/template.md) +- [NVidia]() + - [Driver installation](./nvidia/drivers.md) diff --git a/src/jenkins-pipeline/setup.md b/src/jenkins-pipeline/setup.md new file mode 100644 index 0000000..6a5787c --- /dev/null +++ b/src/jenkins-pipeline/setup.md @@ -0,0 +1,72 @@ +# Set up a Jenkins Pipeline + +By norms, a Jenkins project that builds a Gitea repository should be organized into a folder with the following pipelines: + +``` +├── GIT_REPOSITORY_NAME +│ ├── dev +│ ├── pull-request +│ ├── release +``` + +## Create a folder on Jenkins + +1. In the Jenkins dashboard, click on `New Item`. +2. Enter a name for the folder, and select `Folder` as the type. It is best practice to use the same name as the repository. +3. (Optional) Enter details and description. +4. Click `Save`. + +## Create a pipeline + +### First steps + +1. In the Jenkins dashboard, click on the newly created folder. +2. Click on `New Item`. +3. Enter a name for the pipeline, and select `Pipeline` as the type. + +### General configurations + +1. Enter details and description. +1. Under `General`, tick `This project is parameterized`. +1. Open the `Add Parameter` dropdown, and select `String Parameter`. +1. For the `name`, enter `payload`. +1. Tick `Trim the string`. + +### Build Triggers + +1. Go to https://generate.plus/en/base64 and generate a 32-character random string. +2. Tick `Trigger builds remotely`. +3. Enter the generated token. + +### Pipeline Configurations + +> Note: In the future, we can use `Pipeline script from SCM` to load the pipeline from a repository. + +1. Under `Pipeline`, select `Pipeline script`. +2. Copy the [template from here](./template.md) and paste it in the text area. +3. Add your build steps. Pipeline syntax documentation can be found at https://www.jenkins.io/doc/book/pipeline/syntax/. + +### Generate Personal Access Token (PAT) + +1. Go to your Jenkins dashboard. +2. On the top right corner, click on your username. +3. Click on `Configure`. +4. Under `API Token`, click on `Add new Token`. +5. Enter a name for the token, and click `Generate`. +6. Copy the generated token and **saved it temporarily somewhere** (e.g. Notepad). +7. Click `Save`. + +## Configure webhook from Gitea + +Assumed that you have already created a repository on Gitea. + +1. Go to the repository on Gitea. +2. Click on `Settings` tab. +3. Click on `Webhooks` on the left panel. +4. Click on `Add Webhook`. +5. For `Target URL`, enter `http://localhost:8080/job/${folder_name}/${pipeline_name}/buildWithParameters` +6. Select `POST` as the `HTTP Method`. +7. For `Post Content Type`, select `application/x-www-form-urlencoded`. +8. For `Authorization Header`, enter `Basic ${YOUR_PAT_TOKEN_GENERATED_PREVIOUSLY}`. +9. Click `Update Webhook` to save. +10. Click `Test Delivery` to test the webhook. diff --git a/src/jenkins-pipeline/template.md b/src/jenkins-pipeline/template.md new file mode 100644 index 0000000..8279d57 --- /dev/null +++ b/src/jenkins-pipeline/template.md @@ -0,0 +1,110 @@ +# Jenkins Pipeline + +```groovy +pipeline { + agent any + environment { + // SOURCE CODE MANAGEMENT + GIT_REPOSITORY_URL = "https://YOUR_REPOSITORY_URL_HERE!!!.git" + // STAGES STATUS + CLONE_STAGE_STATUS = "FAIL" + PYLINT_STAGE_STATUS = "FAIL" + GENERATE_BUILD_INFORMATION_STAGE_STATUS = "FAIL" + BUILD_STAGE_STATUS = "FAIL" + UNIT_TEST_STAGE_STATUS = "FAIL" + PYPI_STAGE_STATUS = "FAIL" + AUTO_DOC_STAGE_STATUS = "FAIL" + // WEBHOOK PAYLOAD AND COMMIT DETAILS + WEBHOOK_SENDER_EMAIL = "" + WEBHOOK_SENDER_NAME = "" + WEBHOOK_SENDER_LOGIN = "" + COMMIT_HASH = "" + COMPARE_URL = "" + COMMIT_MSG = "" + BRAND_REF = "" + } + + stages { + stage('Clone') { + steps { + script { + catchError(buildResult: 'FAILURE', stageResult: 'FAILURE') { + echo 'Start branch development pipeline' + dir('webhook-test') { + git branch: 'main', changelog: false, credentialsId: 'Terence', poll: false, url: '${GIT_REPOSITORY_URL}' + } + CLONE_STAGE_STATUS = "SUCCESS" + } + } + } + } + stage('Webhook Handler') { + steps { + script { + echo '------- START RAW WEBHOOK PAYLOAD -------' + echo payload + echo '------- END RAW WEBHOOK PAYLOAD -------' + } + script { + try { + + // Parse the JSON content using jsonSlurper + def jsonSlurper = new groovy.json.JsonSlurper() + def jsonPayload = jsonSlurper.parseText(payload) + echo "Automatic trigger detected via webhook." + WEBHOOK_SENDER_EMAIL=jsonPayload.sender.email + WEBHOOK_SENDER_NAME=jsonPayload.sender.full_name + WEBHOOK_SENDER_LOGIN=jsonPayload.sender.login + COMMIT_HASH=jsonPayload.after + COMPARE_URL=jsonPayload.compare_url + COMMIT_MSG=jsonPayload.head_commit.message + BRANCH_REF=jsonPayload.ref + } catch (exception) { + echo "Manual trigger detected." + WEBHOOK_SENDER_EMAIL=currentBuild.getBuildCauses()[0].userId + WEBHOOK_SENDER_NAME="Manually " + currentBuild.getBuildCauses()[0].shortDescription + WEBHOOK_SENDER_LOGIN="N/A - Manual trigger" + COMMIT_HASH=sh (script: "cd webhook-test && git log -n 1 --pretty=format:'%H'", returnStdout: true) + COMPARE_URL="N/A - Manual trigger" + COMMIT_MSG=sh (script: "cd webhook-test && git log -n 1 --pretty=format:'%B'", returnStdout: true) + BRANCH_REF="N/A - Manual trigger" + } + GENERATE_BUILD_INFORMATION_STAGE_STATUS="SUCCESS" + } + } + } + stage('Cleanup') { + steps { + // By default, send to Teams channel, add additional emails here if needed. + mail to: "13dd15fb.liveconcordia.onmicrosoft.com@ca.teams.ms", + subject: "${env.BUILD_TAG} Pipeline Results", + body: """ +Results of Hub/release Pipeline ${env.BUILD_TAG} + +Build triggered by: ${WEBHOOK_SENDER_NAME} - ${WEBHOOK_SENDER_LOGIN} +Email: ${WEBHOOK_SENDER_EMAIL} + +--- Commit details --- +HEAD Commit: ${COMMIT_HASH} +Commit message: ${COMMIT_MSG} +Branch: ${BRANCH_REF} +See changes: ${COMPARE_URL} + +--- Pipeline stage status --- +Clone: ${CLONE_STAGE_STATUS} +Pylint: ${PYLINT_STAGE_STATUS} +Generate Build Information: ${GENERATE_BUILD_INFORMATION_STAGE_STATUS} +Build: ${BUILD_STAGE_STATUS} +Unit test: ${UNIT_TEST_STAGE_STATUS} +Publish to pypi: ${PYPI_STAGE_STATUS} +Generate autodoc: ${AUTO_DOC_STAGE_STATUS} + +To access the pipeline run logs, please go here: http://nextgenerations-cities.encs.concordia.ca:8080/job/Hub/job/release/ + """ + sh 'rm -rf webhook-test/.jenkins' + cleanWs() + } + } + } +} +``` diff --git a/src/nvidia/drivers.md b/src/nvidia/drivers.md new file mode 100644 index 0000000..a28a501 --- /dev/null +++ b/src/nvidia/drivers.md @@ -0,0 +1,34 @@ +# NVidia Drivers Installation + +This documentation has 2 parts: + +- [NVidia Drivers Installation](#nvidia-drivers-installation) + - [Windows](#windows) + - [Display Drivers](#display-drivers) + - [CUDA Toolkit](#cuda-toolkit) + - [Linux](#linux) + - [Display Drivers](#display-drivers-1) + - [CUDA Toolkit](#cuda-toolkit-1) + +## Windows + +### Display Drivers + +- Go to https://www.nvidia.com/Download/index.aspx?lang=en-us +- Most of our machines are using the GeForce RTX series, so select `GeForce` as the product type. +- For the product series, select the series of your GPU. Make sure it's the Notebooks series if you are using a laptop. E.g. GeForce RTX 20 Series (Notebooks). +- For the product, select your GPU. E.g. GeForce RTX 2080 Super. +- For the operating system, select your OS. E.g. Windows 10 64-bit. +- For the download type, select `Game Ready Driver`. +- Click `Search`. +- Click `Download`. +- Navigate to the downloaded file, and run it. Administrator privileges are required. +- Reboot when done. + +### CUDA Toolkit + +## Linux + +### Display Drivers + +### CUDA Toolkit