From 3da5f0b001ca4bf809301a0a4e109f2ea6b888a2 Mon Sep 17 00:00:00 2001
From: pareenaverma <pareena.verma@arm.com>
Date: Thu, 30 Oct 2025 15:18:39 -0400
Subject: [PATCH 01/10] Update install-circleci-cli.md

---
 .../circleci-gcp/install-circleci-cli.md            | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-gcp/install-circleci-cli.md b/content/learning-paths/servers-and-cloud-computing/circleci-gcp/install-circleci-cli.md
index dbf2afdfa5..036b183de0 100644
--- a/content/learning-paths/servers-and-cloud-computing/circleci-gcp/install-circleci-cli.md
+++ b/content/learning-paths/servers-and-cloud-computing/circleci-gcp/install-circleci-cli.md
@@ -11,10 +11,21 @@ This guide explains how to install the **CircleCI Command Line Interface (CLI)**
 The CLI allows you to interact with CircleCI directly from your terminal, such as to validate configuration files, run jobs locally, or manage runners.
 
 ### Install Required Packages
+
+Add OpenSUSE Leap repository:
+```bash
+sudo zypper addrepo https://download.opensuse.org/distribution/leap/15.5/repo/oss/ openSUSE-Leap-15.5-OSS
+```
+
+Refresh repositories:
+```bash
+sudo zypper refresh
+```
+# Install git
 Before installing the CircleCI CLI, make sure your system has the basic tools required for downloading and extracting files.
 
 ```console
-sudo zypper install curl tar gzip coreutils gpg git
+sudo zypper install curl tar gzip coreutils gpg git-core
 ```
 
 ## Download and Extract the CircleCI CLI

From 7d21b17a7cde1b3dd970cafda13df726a3dd8c2e Mon Sep 17 00:00:00 2001
From: pareenaverma <pareena.verma@arm.com>
Date: Mon, 3 Nov 2025 08:45:53 -0500
Subject: [PATCH 02/10] Update install_circleci_runner.md

---
 .../circleci-gcp/install_circleci_runner.md                | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-gcp/install_circleci_runner.md b/content/learning-paths/servers-and-cloud-computing/circleci-gcp/install_circleci_runner.md
index dbacd91960..d7748c4e27 100644
--- a/content/learning-paths/servers-and-cloud-computing/circleci-gcp/install_circleci_runner.md
+++ b/content/learning-paths/servers-and-cloud-computing/circleci-gcp/install_circleci_runner.md
@@ -18,8 +18,13 @@ SUSE is an RPM-based distribution, so first add the official CircleCI repository
 ```console
 curl -s https://packagecloud.io/install/repositories/circleci/runner/script.rpm.sh?any=true | sudo bash
 ```
-
 ### Install the CircleCI Runner
+Create a symlink for `adduser` as the Circle CI runner script assumes Ubuntu/Debian as your OS:
+
+```bash
+sudo ln -s /usr/sbin/useradd /usr/sbin/adduser
+```
+
 Install the pre-built CircleCI runner package:
 
 ```console

From ae388f6b3820dc989f0781919362904958629112 Mon Sep 17 00:00:00 2001
From: pareenaverma <pareena.verma@arm.com>
Date: Mon, 3 Nov 2025 09:15:50 -0500
Subject: [PATCH 03/10] Update circleci-arm64-cloud-demo.md

---
 .../circleci-gcp/circleci-arm64-cloud-demo.md  | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-gcp/circleci-arm64-cloud-demo.md b/content/learning-paths/servers-and-cloud-computing/circleci-gcp/circleci-arm64-cloud-demo.md
index 780b8d1e96..8737531fb1 100644
--- a/content/learning-paths/servers-and-cloud-computing/circleci-gcp/circleci-arm64-cloud-demo.md
+++ b/content/learning-paths/servers-and-cloud-computing/circleci-gcp/circleci-arm64-cloud-demo.md
@@ -57,11 +57,22 @@ Before proceeding with the app setup, please make sure **Node.js** and **npm** (
 sudo zypper install nodejs
 sudo zypper install npm
 ```
-### Clone Your App Repository
-Clone your application repository (or create one locally):
+### Create a repository for your example code
+First, install GitHub CLI:
+
+```bash
+sudo zypper install gh
+```
+Authenticate:
+
+```bash
+gh auth login
+```
+
+Create a new repository for your example code:
 
 ```console
-git clone https://github.com/<your-repo>/arm64-node-demo.git
+gh repo create arm64-node-demo --public --clone
 cd arm64-node-demo
 ```
 
@@ -170,6 +181,7 @@ package.json
 Once all files (`Dockerfile`, `index.js`, `package.json`, `.circleci/config.yml`) are ready, push your project to GitHub so CircleCI can build it automatically.
 
 ```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

From a1068389d6ea4a1bd06ffa6c4af0d529c7b408d4 Mon Sep 17 00:00:00 2001
From: pareenaverma <pareena.verma@arm.com>
Date: Mon, 3 Nov 2025 09:17:56 -0500
Subject: [PATCH 04/10] Update _index.md

---
 .../servers-and-cloud-computing/circleci-gcp/_index.md         | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-gcp/_index.md b/content/learning-paths/servers-and-cloud-computing/circleci-gcp/_index.md
index 264a2b50d8..5ed1b2542a 100644
--- a/content/learning-paths/servers-and-cloud-computing/circleci-gcp/_index.md
+++ b/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:

From d4fa26250838449bc227b6d59e808acbe5f6ab9d Mon Sep 17 00:00:00 2001
From: pareenaverma <pareena.verma@arm.com>
Date: Mon, 3 Nov 2025 09:20:02 -0500
Subject: [PATCH 05/10] Update background.md

---
 .../circleci-gcp/background.md                            | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-gcp/background.md b/content/learning-paths/servers-and-cloud-computing/circleci-gcp/background.md
index fa99445bc3..70e628a4f6 100644
--- a/content/learning-paths/servers-and-cloud-computing/circleci-gcp/background.md
+++ b/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/).

From 2916ff201eb881678fa2e68cf5cacb246655920d Mon Sep 17 00:00:00 2001
From: pareenaverma <pareena.verma@arm.com>
Date: Mon, 3 Nov 2025 09:33:08 -0500
Subject: [PATCH 06/10] Update install-circleci-cli.md

---
 .../circleci-gcp/install-circleci-cli.md      | 26 ++++++++++++-------
 1 file changed, 16 insertions(+), 10 deletions(-)

diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-gcp/install-circleci-cli.md b/content/learning-paths/servers-and-cloud-computing/circleci-gcp/install-circleci-cli.md
index 036b183de0..a456d42a4b 100644
--- a/content/learning-paths/servers-and-cloud-computing/circleci-gcp/install-circleci-cli.md
+++ b/content/learning-paths/servers-and-cloud-computing/circleci-gcp/install-circleci-cli.md
@@ -7,46 +7,52 @@ layout: learningpathall
 ---
 
 ## Install CircleCI CLI on GCP VM
-This guide explains how to install the **CircleCI Command Line Interface (CLI)** on a **GCP SUSE Arm64 virtual machine**.  
-The CLI allows you to interact with CircleCI directly from your terminal, such as to validate configuration files, run jobs locally, or manage runners.
+This section explains how to install the CircleCI Command Line Interface (CLI) on a SUSE Linux (Arm64) virtual machine running on Google Cloud C4A (Axion). The CLI allows you to interact with CircleCI directly from your terminal, to validate configuration files, run jobs locally, or manage runners.
 
 ### Install Required Packages
 
-Add OpenSUSE Leap repository:
+Before installing the CLI, make sure your SUSE environment has the necessary repositories and development tools. Add the openSUSE Leap repository:
+
 ```bash
 sudo zypper addrepo https://download.opensuse.org/distribution/leap/15.5/repo/oss/ openSUSE-Leap-15.5-OSS
 ```
 
-Refresh repositories:
+Refresh package repositories:
 ```bash
 sudo zypper refresh
 ```
+This updates the local metadata so that zypper recognizes the latest available packages and dependencies.
+
 # Install git
 Before installing the CircleCI CLI, make sure your system has the basic tools required for downloading and extracting files.
 
 ```console
-sudo zypper install curl tar gzip coreutils gpg git-core
+sudo zypper install -y curl tar gzip coreutils gpg git-core
 ```
+Once Git and the required tools are installed, you’re ready to download and configure the CircleCI CLI binary for Arm64.
 
 ## Download and Extract the CircleCI CLI
-Now download the CircleCI CLI binary for Linux Arm64 and extract it.
+Download the CircleCI CLI binary for Linux Arm64 and extract it.
 
 ```console
 curl -fLSs https://github.com/CircleCI-Public/circleci-cli/releases/download/v0.1.33494/circleci-cli_0.1.33494_linux_arm64.tar.gz | tar xz
 sudo mv circleci-cli_0.1.33494_linux_arm64/circleci /usr/local/bin/
 ```
+Explanation of the commands:
+
 - The `curl` command downloads the `.tar.gz` archive from the official CircleCI GitHub release page.
 - The `| tar xz` part extracts the downloaded file directly without saving it separately.
-- After extraction, you’ll see a new folder named `circleci-cli_0.1.33494_linux_arm64` in your current directory.
+
+After extraction, you’ll see a new folder named `circleci-cli_0.1.33494_linux_arm64` in your current directory.
 
 ### Verify the Installation
-Finally, verify that the CLI is installed correctly by checking its version.
+Check that the CircleCI CLI is installed and executable:
 
 ```console
 circleci version
 ```
-You should see an output similar to:
+You should see output similar to:
 ```output
 0.1.33494+7cc6570 (release)
 ```
-If you see similar version output, the installation was successful!
+The CircleCI CLI is now installed and running natively on your SUSE Arm64 VM (Google Cloud C4A).

From b8358c34d5e5e62720f6a39d08c20f878a24c71e Mon Sep 17 00:00:00 2001
From: pareenaverma <pareena.verma@arm.com>
Date: Mon, 3 Nov 2025 09:41:25 -0500
Subject: [PATCH 07/10] Update create_resource_class.md

---
 .../circleci-gcp/create_resource_class.md     | 34 ++++++++++---------
 1 file changed, 18 insertions(+), 16 deletions(-)

diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-gcp/create_resource_class.md b/content/learning-paths/servers-and-cloud-computing/circleci-gcp/create_resource_class.md
index 6959ce5144..e890b61e69 100644
--- a/content/learning-paths/servers-and-cloud-computing/circleci-gcp/create_resource_class.md
+++ b/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")
    

From 332aa83f27d1e5117f16d40f130ed7b242e64098 Mon Sep 17 00:00:00 2001
From: pareenaverma <pareena.verma@arm.com>
Date: Mon, 3 Nov 2025 09:51:20 -0500
Subject: [PATCH 08/10] Update install_circleci_runner.md

---
 .../circleci-gcp/install_circleci_runner.md   | 44 ++++++++++---------
 1 file changed, 23 insertions(+), 21 deletions(-)

diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-gcp/install_circleci_runner.md b/content/learning-paths/servers-and-cloud-computing/circleci-gcp/install_circleci_runner.md
index d7748c4e27..8e1d7bd9f8 100644
--- a/content/learning-paths/servers-and-cloud-computing/circleci-gcp/install_circleci_runner.md
+++ b/content/learning-paths/servers-and-cloud-computing/circleci-gcp/install_circleci_runner.md
@@ -8,64 +8,66 @@ layout: learningpathall
 
 ## Install CircleCI Machine Runner on SUSE Arm64
 
-This guide explains how to install and configure the **CircleCI Machine Runner** on a **GCP SUSE Arm64 virtual machine**.  
-This setup allows your self-hosted environment to execute CircleCI jobs targeting Arm64 architecture.
+This section explains how to install and configure the CircleCI Machine Runner on a SUSE Linux Arm64 virtual machine running on Google Cloud C4A (Axion). By installing this runner, you enable your own VM to execute CircleCI Arm-native jobs.
 
 ### Add CircleCI Package Repository
 
-SUSE is an RPM-based distribution, so first add the official CircleCI repository:
+Because SUSE is an RPM-based Linux distribution, you first need to add the official CircleCI package repository from PackageCloud:
 
 ```console
 curl -s https://packagecloud.io/install/repositories/circleci/runner/script.rpm.sh?any=true | sudo bash
 ```
+This command automatically detects your distribution and adds the appropriate repository configuration for SUSE-based systems.
+
 ### Install the CircleCI Runner
-Create a symlink for `adduser` as the Circle CI runner script assumes Ubuntu/Debian as your OS:
+Before installation, create a symbolic link for `adduser`. The CircleCI runner installation script is primarily built for Debian/Ubuntu systems, which use the `adduser` command. SUSE uses `useradd` instead.
 
 ```bash
 sudo ln -s /usr/sbin/useradd /usr/sbin/adduser
 ```
 
-Install the pre-built CircleCI runner package:
+Now install the CircleCI runner package:
 
 ```console
 sudo zypper install -y circleci-runner
 ```
 ### Prepare User and Permissions
-Before starting the runner, ensure the required user, group, and directory permissions are properly set up:
-
-```console
-# Create a symlink for adduser (required on SUSE)
-sudo ln -s /usr/sbin/useradd /usr/sbin/adduser
+Before starting the CircleCI runner, ensure the correct user, group, and directory permissions are in place. These steps ensure the runner operates securely and has proper access to its configuration and work directories.
 
-# Create CircleCI system user and group
+Create CircleCI system user and group: 
+```bash
 sudo useradd -m -r circleci
 sudo groupadd --system circleci
-
-# Set up CircleCI directories and permissions
+```
+Set up CircleCI directories and permissions:
+```bash
 sudo mkdir -p /var/lib/circleci
 sudo chown -R circleci:circleci /var/lib/circleci
 sudo chown -R circleci:circleci /etc/circleci-runner
-
-# Reload systemd and restart the runner service
+```
+Reload systemd and restart the runner service:
+```bash
 sudo systemctl daemon-reload
 sudo systemctl restart circleci-runner
-
-# Verify service status
+```
+Verify service status:
+```bash
 sudo systemctl status circleci-runner
 ```
 
 ### Configure the Runner Token
 
-Replace the authentication token in the runner configuration file.
-Use the token obtained from your Resource Class in the CircleCI Dashboard.
+Now, configure the authentication token that connects your runner to CircleCI.
+Use the token generated earlier from your Resource Class in the CircleCI dashboard.
 
 ```console
 export RUNNER_AUTH_TOKEN="AUTH_TOKEN "
 sudo sed -i "s/<< AUTH_TOKEN >>/$RUNNER_AUTH_TOKEN/g" /etc/circleci-runner/circleci-runner-config.yaml
 ```
+Replace AUTH_TOKEN with the actual token copied from the CircleCI dashboard.
 
 ### Enable and Start the Runner
-Enable the CircleCI runner service to start automatically and verify it’s running:
+Enable the CircleCI service to start automatically at boot, then start and verify the runner:
 
 ```console
 sudo systemctl enable circleci-runner
@@ -90,6 +92,6 @@ Oct 09 11:15:03 lpprojectsusearm64 circleci-runner[10150]: 11:15:03 6f109 46.059
 Oct 09 11:15:03 lpprojectsusearm64 circleci-runner[10150]: 11:15:03 6f109 46.119ms claim app.loop_name=claim:  mode=agent res>
 Oct 09 11:15:03 lpprojectsusearm64 circleci-runner[10150]: 11:15:03 6f109 46.144ms worker loop: claim:  app.backoff_ms=5000 a>
 ```
-Also, you can verify it from the dashboard:
+You can also confirm that your runner is connected and active by visiting the Self-Hosted Runners page in the CircleCI web dashboard.
 
 ![Self-Hosted Runners alt-text#center](images/dashboard.png "Figure 1: Self-Hosted Runners ")

From 6859b26f52acbdac9cb8dd79194a890f4b82c67e Mon Sep 17 00:00:00 2001
From: pareenaverma <pareena.verma@arm.com>
Date: Mon, 3 Nov 2025 09:53:13 -0500
Subject: [PATCH 09/10] Update install_circleci_runner.md

---
 .../circleci-gcp/install_circleci_runner.md                    | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-gcp/install_circleci_runner.md b/content/learning-paths/servers-and-cloud-computing/circleci-gcp/install_circleci_runner.md
index 8e1d7bd9f8..17d6966387 100644
--- a/content/learning-paths/servers-and-cloud-computing/circleci-gcp/install_circleci_runner.md
+++ b/content/learning-paths/servers-and-cloud-computing/circleci-gcp/install_circleci_runner.md
@@ -95,3 +95,6 @@ Oct 09 11:15:03 lpprojectsusearm64 circleci-runner[10150]: 11:15:03 6f109 46.144
 You can also confirm that your runner is connected and active by visiting the Self-Hosted Runners page in the CircleCI web dashboard.
 
 ![Self-Hosted Runners alt-text#center](images/dashboard.png "Figure 1: Self-Hosted Runners ")
+
+Your CircleCI Machine Runner is now installed, configured, and registered on your SUSE Arm64 VM (Google Cloud C4A).
+You can now define jobs in your `.circleci/config.yml` that target your Arm-native Resource Class and begin running builds directly on this runner.

From 5ff4b3c211e32b11c1a58da956f55159e79bf023 Mon Sep 17 00:00:00 2001
From: pareenaverma <pareena.verma@arm.com>
Date: Mon, 3 Nov 2025 10:29:24 -0500
Subject: [PATCH 10/10] Update circleci-arm64-cloud-demo.md

---
 .../circleci-gcp/circleci-arm64-cloud-demo.md | 139 +++++++++++-------
 1 file changed, 88 insertions(+), 51 deletions(-)

diff --git a/content/learning-paths/servers-and-cloud-computing/circleci-gcp/circleci-arm64-cloud-demo.md b/content/learning-paths/servers-and-cloud-computing/circleci-gcp/circleci-arm64-cloud-demo.md
index 8737531fb1..f581576f2d 100644
--- a/content/learning-paths/servers-and-cloud-computing/circleci-gcp/circleci-arm64-cloud-demo.md
+++ b/content/learning-paths/servers-and-cloud-computing/circleci-gcp/circleci-arm64-cloud-demo.md
@@ -6,70 +6,87 @@ 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.
+
+Once both checks pass, your environment is ready to build and run container-based pipelines with CircleCI on SUSE Arm64.
 
-### **Install Node.js and npm**
+### Install Node.js and npm
 
-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.
+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**: Use the official Node.js package for Arm64 architecture. 
-- **Install npm**: npm is automatically installed when Node.js is installed.
+- 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
 ```
+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
-First, install GitHub CLI:
+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 gh
+sudo zypper install -y gh
 ```
-Authenticate:
+2. Authenticate with GitHub
+Run the following command to connect the CLI to your GitHub account:
 
 ```bash
 gh auth login
 ```
 
-Create a new repository for your example code:
+3. Create a New Repository
+Create a new public repository for your demo project and clone it locally:
 
 ```console
 gh repo create arm64-node-demo --public --clone
@@ -77,9 +94,9 @@ 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
@@ -89,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
@@ -135,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');
@@ -157,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
 {
@@ -173,12 +199,15 @@ 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"
@@ -186,41 +215,49 @@ 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.