Merge pull request #2496 from pareenaverma/content_review

Tech Review of CircleCI Axion LP

Author: pareenaverma

content/learning-paths/servers-and-cloud-computing/circleci-gcp/_index.md

@@ -7,7 +7,7 @@ cascade:
 
 minutes_to_complete: 45
 
-who_is_this_for: This learning path is intended for software developers and DevOps engineers looking to set up and run CircleCI Arm native workflows on SUSE Linux Arm64 VMs, specifically on Google Cloud C4A with Axion processors, using self-hosted runners.
+who_is_this_for: This is an introductory topic for software developers and DevOps engineers looking to set up and run CircleCI Arm native workflows on SUSE Linux Arm64 VMs, specifically on Google Cloud C4A with Axion processors, using self-hosted runners.
 
 learning_objectives:
   - Provision a SUSE Arm64 virtual machine on Google Cloud (C4A with Axion processors)
@@ -40,7 +40,6 @@ tools_software_languages:
   - CircleCI
   - Node.js
   - npm
-  - Express
   - Docker
 
 operatingsystems:

content/learning-paths/servers-and-cloud-computing/circleci-gcp/background.md

@@ -16,10 +16,10 @@ To learn more about Google Axion, refer to the [Introducing Google Axion Process
 
 ## CircleCI
 
-CircleCI is a cloud-based **Continuous Integration and Continuous Delivery (CI/CD)** platform that automates the process of **building, testing, and deploying software**.
+CircleCI is a cloud-based Continuous Integration and Continuous Delivery (CI/CD) platform that automates the process of building, testing, and deploying software.
 
-It integrates with popular version control systems like **GitHub**, **Bitbucket**, and **GitLab**, and allows developers to define custom workflows in a `.circleci/config.yml` file using **YAML syntax**.
+It integrates with popular version control systems like GitHub, Bitbucket, and GitLab, and allows developers to define custom workflows in a `.circleci/config.yml` file using the YAML syntax.
 
-CircleCI supports multiple environments, including **Docker**, **Linux**, **macOS**, and **Windows**, and offers advanced features like **parallelism**, **caching**, and **matrix builds** to speed up pipelines and improve efficiency.
+CircleCI supports multiple platforms, including Linux, macOS, and Windows, and offers advanced features like parallelism, caching, and matrix builds to speed up pipelines and improve efficiency.
 
-It is widely used for **automating tests, running builds, deploying applications, and ensuring code quality** in modern development workflows. Learn more from the [CircleCI official website](https://circleci.com/) and its [documentation](https://circleci.com/docs/).
+It is widely used for automating tests, running builds, deploying applications, and ensuring code quality in modern development workflows. Learn more from the [CircleCI official website](https://circleci.com/) and its [documentation](https://circleci.com/docs/).

content/learning-paths/servers-and-cloud-computing/circleci-gcp/circleci-arm64-cloud-demo.md

@@ -6,69 +6,97 @@ weight: 8
 layout: learningpathall
 ---
 
-## Deploying a Cloud-Native Arm64 Node.js App using self-hosted CircleCI Runner on GCP
+## Deploying a Cloud-Native Arm64 Node.js App Using a Self-Hosted CircleCI Runner on GCP
 
-This guide walks through building and testing a simple **Node.js web app** using a **self-hosted CircleCI Arm64 runner** on a **GCP SUSE Arm64 VM**.
+This section demonstrates how to build and test a simple Node.js web application using a self-hosted CircleCI runner running on a Google Cloud C4A (Axion Arm64) SUSE Linux virtual machine. 
 
+You’ll configure Docker on the VM so that CircleCI jobs can build, test, and run containerized applications directly in your Arm64 environment, ideal for cloud-native development and CI/CD workflows targeting Arm architecture.
 
-### Install and Configure Docker
-Ensure Docker is installed, started, and accessible by both your user and the CircleCI runner service.
 
-- **Install Docker**: Refresh your package manager and install Docker on your system.
-- **Enable Docker Service**: Ensure Docker starts on boot and is running.
-- **Add User to Docker Group**: Add both your user and the CircleCI runner to the Docker group to grant access.
+### Install and Configure Docker
+Ensure Docker is installed, enabled, and accessible by both your local user and the CircleCI runner service.
 
-```console
+1. Install Docker
+Refresh your package manager and install Docker on your system:
+```bash
 sudo zypper refresh
 sudo zypper install docker
+```
+2. Enable and start Docker service
+Set Docker to start automatically at boot and verify it’s running:
+```bash
 sudo systemctl enable docker
 sudo systemctl start docker
 sudo systemctl status docker
+```
+3. Grant Docker access to users
+Add both your current user and the circleci system user to the Docker group so they can run Docker commands without sudo:
+```bash
 sudo usermod -aG docker $USER
 sudo usermod -aG docker circleci
 ```
 ### Validate Docker access
-This command switches to the CircleCI user and checks if Docker is working correctly.
+After installing Docker and adding the circleci user to the Docker group, verify that the CircleCI runner user can access Docker without requiring elevated privileges.
 
-```console
+Run the following commands:
+```bash
 sudo -u circleci -i
 docker ps
 exit
 ```
 
 ### Verify Docker Permissions
-Check Docker socket permissions and ensure that the CircleCI runner is active and running.
+Now, confirm that Docker’s socket permissions and the CircleCI runner service are both configured correctly.
 
-```console
+```bash
 ls -l /var/run/docker.sock
 ps -aux | grep circleci-runner
 ```
-- **Check Docker Socket Permissions**: This command ensures the Docker socket is accessible.
-- **Verify CircleCI Runner Process**: Confirm the CircleCI runner service is active and running.
+These commands ensure that the Docker socket is accessible and the CircleCI runner service is active and running.
 
-### **Install Node.js and npm**
+Once both checks pass, your environment is ready to build and run container-based pipelines with CircleCI on SUSE Arm64.
 
-Before proceeding with the app setup, please make sure **Node.js** and **npm** (Node.js package manager) are installed on the VM, as they are required to run your Node.js app.
+### Install Node.js and npm
 
-- **Install Node.js**: Use the official Node.js package for Arm64 architecture. 
-- **Install npm**: npm is automatically installed when Node.js is installed.
+Before setting up the sample application, ensure that `Node.js` and its package manager `npm` are installed on your SUSE Arm64 VM. Both are required to run, build, and test the `Node.js` web application within your CircleCI pipeline.
+
+- Install Node.js: Install the official Node.js package built for the Arm64 architecture.
+- Install npm: npm (Node Package Manager) is bundled with Node.js but can also be explicitly installed or upgraded if needed.
 
 ```console
 sudo zypper install nodejs
 sudo zypper install npm
 ```
-### Clone Your App Repository
-Clone your application repository (or create one locally):
+Next, you’ll create the demo project and prepare its CircleCI configuration to run jobs using your self-hosted Arm64 runner.
+
+### Create a repository for your example code
+To store and manage your Node.js demo application, you’ll create a new GitHub repository using the GitHub CLI.
+
+1. Install the GitHub CLI
+The GitHub CLI (gh) lets you manage repositories, issues, and pull requests directly from your terminal.
+
+```bash
+sudo zypper install -y gh
+```
+2. Authenticate with GitHub
+Run the following command to connect the CLI to your GitHub account:
+
+```bash
+gh auth login
+```
+
+3. Create a New Repository
+Create a new public repository for your demo project and clone it locally:
 
 ```console
-git clone https://github.com/<your-repo>/arm64-node-demo.git
+gh repo create arm64-node-demo --public --clone
 cd arm64-node-demo
 ```
 
 ### Create a Dockerfile
-In the root of your project, create a `Dockerfile` that defines how to build and run your application container.
+In the root of your project, create a file named `Dockerfile` to define how your `Node.js` application container will be built and executed.
 
-```dockerfile
+```console
 # Dockerfile
 FROM arm64v8/node:20-alpine
 WORKDIR /app
@@ -78,13 +106,18 @@ COPY . .
 EXPOSE 3000
 CMD ["npm", "start"]
 ```
-- **Use Arm64 Node.js Image**: The `arm64v8/node` image is specifically designed for Arm64 architecture.
-- **Install Dependencies**: `RUN npm install` installs the project dependencies listed in `package.json`.
-- **Expose Port**: The app will run on port 3000.
-- **Start the App**: The container will execute `npm start` to launch the Node.js server.
+Breakdown of the Dockerfile:
+
+- Uses Arm64 Node.js Image: The `arm64v8/node` image is specifically designed for Arm64 architecture.
+- Install Dependencies: `RUN npm install` installs the project dependencies listed in `package.json`.
+- Expose Port: The app will run on port 3000.
+- Start the App: The container will execute `npm start` to launch the Node.js server.
+
+Next, you’ll add the application code and a `.circleci/config.yml` file to automate the build and test pipeline using your self-hosted Arm64 runner.
 
 ### Add a CircleCI Configuration
-Create a `.circleci/config.yml` file to define the CircleCI pipeline for building and testing your Node.js app on Arm64 architecture.
+Create a configuration file that defines your CircleCI pipeline for building, running, and testing your Node.js app on Arm64 architecture.
+In the root of your project, create a folder named `.circleci` and inside it, add a file called `config.yml` with the contents below:
 
 ```yaml
 version: 2.1
@@ -124,14 +157,17 @@ workflows:
     jobs:
       - arm64-demo
 ```
-- **arm64-demo Job**: This job checks if the architecture is Arm64, builds the Docker image, runs it in a container, and tests the app endpoint.
-- **resource_class**: Specify the resource class for the CircleCI runner (e.g., a custom Arm64 runner if using self-hosted).
-- **Test Endpoint**: The job sends a request to the app to verify it’s working.
+
+Explanation of the yaml file:
+
+- arm64-demo Job: This job checks if the architecture is Arm64, builds the Docker image, runs it in a container, and tests the app endpoint.
+- resource_class: Specify the resource class for the CircleCI runner (e.g., a custom Arm64 runner if using self-hosted).
+- Test Endpoint: The job sends a request to the app to verify it’s working.
 
 ### Node.js Application
-Here’s the basic code for the Node.js app.
+Create the application files in your repository root directory for the Node.js app.
 
-`index.js`:
+Use a file editor of your choice and copy the contents shown below into a file named `index.js`:
 
 ```javascript
 const express = require('express');
@@ -146,7 +182,8 @@ app.listen(PORT, () => {
   console.log(`Server running on port ${PORT}`);
 });
 ```
-package.json
+
+Now copy the content below into a file named `package.json`:
 
 ```json
 {
@@ -162,53 +199,65 @@ package.json
   }
 }
 ```
-- **Express Server**: The application uses Express.js to handle HTTP requests and respond with a simple message.
-- **Package Dependencies**: The app requires the `express` package for handling HTTP requests.
+- Express Server: The application uses Express.js to handle HTTP requests and respond with a simple message.
+- Package Dependencies: The app requires the `express` package for handling HTTP requests.
 
 ### Push Code to GitHub
 
-Once all files (`Dockerfile`, `index.js`, `package.json`, `.circleci/config.yml`) are ready, push your project to GitHub so CircleCI can build it automatically.
+Now that all project files (Dockerfile, index.js, package.json, and .circleci/config.yml) are ready, push the code to GitHub.
+This allows CircleCI to automatically detect the repository and trigger your Arm64 build pipeline using the self-hosted runner.
+
+Configure Git username and add and commit project files:
 
 ```console
+git config --global user.name "your-user-name"
 git add .
 git commit -m "Add ARM64 CircleCI Node.js demo project"
 git push -u origin main
 ```
-- **Add and Commit Changes**: Stage and commit your project files.
-- **Push to GitHub**: Push your code to the GitHub repository so that CircleCI can trigger the build.
+You have pushed your code to the GitHub repository so that CircleCI can trigger the build.
 
 ### Start CircleCI Runner and Execute Job
-Ensure that your CircleCI runner is enabled and started. This will allow your self-hosted runner to pick up jobs from CircleCI.
+Before triggering your first workflow, ensure that the CircleCI runner service is enabled and running on your SUSE Arm64 VM. This will allow your self-hosted runner to pick up jobs from CircleCI.
 
-```console
+```bash
 sudo systemctl enable circleci-runner
 sudo systemctl start circleci-runner
 sudo systemctl status circleci-runner
 ```
-- **Enable CircleCI Runner**: Ensure the CircleCI runner is set to start automatically on boot.
-- **Start and Check Status**: Start the CircleCI runner and verify it is running.
+- Enable CircleCI Runner: Ensures the runner service starts automatically on system boot.
+- Start and Check Status: Starts the CircleCI runner and verifies it is running.
+
 
-After pushing your code to GitHub, open your **CircleCI Dashboard → Projects**, and confirm that your **ARM64 workflow** starts running using your **self-hosted runner**.
+### Verify Job Execution in CircleCI
+
+After pushing your code to GitHub, open your CircleCI Dashboard → Projects, and confirm that your Arm64 workflow starts running using your self-hosted runner.
 
 If the setup is correct, you’ll see your job running under the resource class you created.
 
 ### Output
-Once the job starts running, CircleCI will:
+When the CircleCI workflow starts running on your self-hosted Arm64 runner, you’ll see the following stages executed in your CircleCI Dashboard:
 
-- Detect the ARM64 architecture.
+1. Detect the ARM64 Architecture
+CircleCI confirms the job is executing on your Arm64 self-hosted runner. This validates that the pipeline is correctly targeting your Google Cloud C4A (Axion) VM.
 
 ![CircleCI Dashboard alt-text#center](images/output1.png "Figure 1: Show architecture")
 
-- Build the Docker image.
+2. Build the Docker image
+The runner builds the `arm64-node-demo` Docker image using the Dockerfile you defined.
 
 ![CircleCI Dashboard alt-text#center](images/output2.png "Figure 2: Docker Image")
 
-- Runs a container from that image.
+3. Runs a container from that Image
+Once the image is built, the job launches a container to host your Node.js web app.
 
 ![CircleCI Dashboard alt-text#center](images/output4.png "Figure 3: Container Run")
 
-- Test the application by hitting the endpoint.
-
+4. Test the application by hitting the endpoint.
+The workflow tests the running app by sending an HTTP request to http://localhost:3000.
 ![CircleCI Dashboard alt-text#center](images/output3.png "Figure 3: Verify App")
+If the app responds successfully, the test confirms that the Node.js web server is running correctly inside the container.
 
 If successful, you will see your CircleCI job running and the app deployed in the CircleCI Dashboard.
+
+This demonstrates an end-to-end cloud-native CI/CD workflow running natively on SUSE Arm64 with Google Cloud C4A (Axion) as a self-hosted runner on CircleCI.

content/learning-paths/servers-and-cloud-computing/circleci-gcp/create_resource_class.md

@@ -7,36 +7,38 @@ layout: learningpathall
 ---
 
 ## Create a Resource Class for Self-Hosted Runner in CircleCI
-This guide explains how to create a **Resource Class** in the **CircleCI Web Dashboard** for a **self-hosted runner**.  
-A Resource Class defines a unique identifier for your runner and links it to your CircleCI namespace, allowing CircleCI jobs to target your custom machine environment.
+This section explains how to create a Resource Class in the CircleCI Web Dashboard for a self-hosted runner.
+A Resource Class is a unique identifier that links your self-hosted runner to your CircleCI organization (namespace). It defines the “machine type” that CircleCI jobs can target, ensuring that only authorized jobs run on your managed infrastructure, in this case, your SUSE Linux Arm64 VM on Google Cloud C4A (Axion).
 
 ### Steps
 
-1. **Go to the CircleCI Web Dashboard**
-   - From the left sidebar, navigate to **Self-Hosted Runners**.  
-   - You’ll see a screen asking you to accept the **terms of use**.  
-   - **Check the box** that says **“Yes, I agree to the terms”** to enable runners.  
-   - Then click **Self-Hosted Runners** to continue setup.
+1. Open the CircleCI Web Dashboard
+   - Login or Create a new account at [CircleCI](https://app.circleci.com/home)
+   - In the left-hand navigation panel, click Self-Hosted Runners.
+   - If this is your first time setting up runners, you’ll be prompted to accept the Terms of Use.
+     Check “Yes, I agree to the terms” to enable runner functionality for your organization.
+   - After accepting, click Self-Hosted Runners again to continue the setup process.
 
 ![Self-Hosted Runners alt-text#center](images/shrunner0.png "Figure 1: Self-Hosted Runners ")
 
-2. **Create a New Resource Class**
+2. Create a New Resource Class
 
-Click **Create Resource Class** on your CircleCI dashboard. 
+On your CircleCI Dashboard, click Create Resource Class.
 
-**Fill in the following details:** 
+Fill in the following details:
 
-   - **Namespace:** Your CircleCI username or organization name (e.g., `circleci`)
-   - **Resource Class Name:** A clear, descriptive name for your runner (e.g., `arm64`)
-   - Click **Create Resource Class**.
+  * Namespace: Your CircleCI organization or username (e.g., circleci)
+  * Resource Class Name: A clear, descriptive identifier for your runner (e.g., arm64)
+  * Once complete, click Create Resource Class to generate it.
 
 ![Self-Hosted Runners alt-text#center](images/shrunner1.png "Figure 2: Create Resource Class ")
 
 ![Self-Hosted Runners alt-text#center](images/shrunner2.png "Figure 3: Details Resource Class & Namespace")
 
-3. **Save and Copy the Token**
-   - Once created, CircleCI will generate a **Resource Class Token**.  
-   - Copy this token and store it securely — you will need it to register your runner on the GCP VM.
+3. Save and Copy the Token
+
+ After creating the resource class, CircleCI automatically generates a Resource Class Token, a secure authentication key used to register your runner. Copy this token immediately and store it in a secure location.
+You’ll need this token in the next step to connect your SUSE Arm64 runner on the Google Cloud C4A (Axion) VM to CircleCI.
 
 ![Self-Hosted Runners alt-text#center](images/shrunner3.png "Figure 4: Resource Class Token")