Update circleci-arm64-cloud-demo.md

Author: pareenaverma

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

@@ -6,80 +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.
+
+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
 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,54 +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.