Update baseline.md

Author: pareenaverma

content/learning-paths/servers-and-cloud-computing/ruby-on-rails/baseline.md

@@ -7,21 +7,23 @@ layout: learningpathall
 ---
 
 ## Baseline Setup for Ruby on Rails with PostgreSQL
-This section covers the installation and configuration of **PostgreSQL** and a **Rails application** on a SUSE Arm-based GCP VM. It includes setting up PostgreSQL, creating a Rails app, configuring the database, and starting the Rails server.
+This section sets up PostgreSQL and connects it with a Ruby on Rails application on a SUSE Arm64 Google Cloud C4A virtual machine. You’ll install PostgreSQL, configure it for Rails, create a database user, and verify that Rails can connect and serve requests successfully.
 
 ### Install and Configure PostgreSQL
-PostgreSQL is used with Ruby on Rails as a robust, production-ready relational database that reliably stores and manages application data.
+PostgreSQL is a robust, production-grade relational database that integrates seamlessly with Ruby on Rails.
+
+Install PostgreSQL and its development headers:
 
 ```console
 sudo zypper install postgresql-devel postgresql-server
-sudo systemctl start postgresql
-sudo systemctl enable postgresql
 ```
 - `postgresql-devel` is required to compile the pg gem for Rails.
 
-Verify that the PostgreSQL service is active and running:
+After installation, ensure that PostgreSQL is running and configured to start automatically at boot:
 
 ```console
+sudo systemctl start postgresql
+sudo systemctl enable postgresql
 systemctl status postgresql
 ```
 The output should look like:
@@ -41,55 +43,64 @@ The output should look like:
              ├─ 27003 "postgres: autovacuum launcher " "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" ">
              └─ 27004 "postgres: logical replication launcher " "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" ">
 ```
+If the Active state reads running, your PostgreSQL service is operational and ready for configuration.
 
-This command creates a new PostgreSQL role (user) named `gcpuser` with **superuser privileges**.  
+### Create a Database Role for Rails
+Next, create a dedicated PostgreSQL role (user) that Rails will use to connect to the database.
 
 ```console
 sudo -u postgres psql -c "CREATE USER gcpuser WITH SUPERUSER PASSWORD 'your_password';"
 ```
-- `sudo -u postgres` → Runs the command as the `postgres` user (default PostgreSQL superuser).
-- `createuser --superuser gcpuser` → Creates a PostgreSQL role named `gcpuser` with full admin privileges.
-    - Can create databases
-    - Can create other roles/users
-    - Can grant privileges
+This command:
+
+Executes under the default PostgreSQL superuser account (postgres).
+Creates a new PostgreSQL role called gcpuser.
+Assigns superuser privileges, allowing the user to create databases, manage roles, and execute administrative tasks.
 
-This role will be used by Rails to connect to the PostgreSQL database.
+This user will serve as the Rails database owner and be referenced in the Rails configuration file (config/database.yml) later.
 
 ### Set Environment variables
 
-Before you create your Rails app, set the following environment variables:
+Before creating your Rails application, export environment variables so Rails and the `pg gem` can authenticate automatically with PostgreSQL.
 
 ```console
 export PGUSER=gcpuser
 export PGPASSWORD=your_password
 export PGHOST=localhost
 ```
+
+PGUSER → Specifies the PostgreSQL user that Rails will connect as.
+PGPASSWORD → Stores the password for that user in memory (temporary for this session).
+PGHOST → Points to the PostgreSQL host (in this case, the local VM).
+
 ### Create a Rails App with PostgreSQL
-Creates a new Rails application configured to use PostgreSQL as its database.
+Now, generate a new Rails application configured to use PostgreSQL as its default database adapter:
 
 ```console
 rails new db_test_rubyapp -d postgresql
 cd db_test_rubyapp
 bundle install
 ```
-- Creates a new Rails application called `db_test_app`.
-- `d postgresql` → Tells Rails to use PostgreSQL as the database instead of the default SQLite.
-- `bundle install` ensures all required gems are installed.
+- rails new db_test_rubyapp → Creates a new Rails application named db_test_rubyapp.
+- `d postgresql` → Instructs Rails to use PostgreSQL instead of the default SQLite database.
+- bundle install → Installs all gem dependencies defined in the Gemfile, including the pg gem that connects Rails to PostgreSQL.
 
 {{% notice Note %}}
 Check `config/database.yml` to ensure the `username` and `password` match your PostgreSQL role `(gcpuser)`.
 {{% /notice %}}
 
 ### Verify and Update Database Configuration
-Open and modify your Rails database configuration file:
+Rails uses the `config/database.yml` file to define how it connects to databases in different environments (development, test, and production).
+It's important to verify that these credentials align with the PostgreSQL role you created earlier.
+
+Open the file with your preferred text editor:
 
 ```console
 sudo vi config/database.yml
 ```
-Find the `default`: and `development`: sections.
-Ensure the username matches the PostgreSQL user you created (gcpuser):
+Locate the default and development sections, and make sure they match the PostgreSQL user and password you configured.
 
-You should see output similar to:
+Your configuration file should have the following fields set:
 ```output
 default: &default
   adapter: postgresql
@@ -104,34 +115,49 @@ development:
 ```
 
 ### Change the Authentication Method
-Change the authentication method in the PostgreSQL configuration file `pg_hba.conf` from `ident` to `md5`. 
+By default, PostgreSQL on many Linux distributions (including SUSE) uses the ident authentication method for local connections. This method maps Linux system usernames directly to PostgreSQL roles. While convenient for local access, it prevents password-based authentication, which is necessary for Rails and most application connections.
+
+To allow Rails to connect using a username and password, change the authentication method in PostgreSQL’s configuration file `pg_hba.conf` from ident to md5.
 
 Open your configuration file
 ```console
 sudo vi /var/lib/pgsql/data/pg_hba.conf
 ```
-Find lines that look like this:
+The file location `/var/lib/pgsql/data/pg_hba.conf` is the default data directory path for PostgreSQL on SUSE Linux.
+
+Find lines like the following in the file:
+
 ```output
 # IPv4 local connections:
 host    all             all             127.0.0.1/32            ident
 # IPv6 local connections:
 host    all             all             ::1/128                 ident
 ```
-Change the method on these lines to look like:
+Modify both lines to use md5, which enables password-based authentication:
+
 ```output
 # IPv4 local connections:
 host    all             all             127.0.0.1/32            md5
 # IPv6 local connections:
 host    all             all             ::1/128                 md5
 ```
-Save the file. Restart PostgreSQL:
+After saving the file, restart the PostgreSQL service to apply the new authentication settings:
 
 ```console
 sudo systemctl restart postgresql
 ```
+
+Verify the change:
+```console
+sudo systemctl status postgresql
+```
+The service should show as active (running).
+
 ### Create and Initialize the Database
-Initializes and creates the development and test databases for your Rails app using PostgreSQL.
+Once PostgreSQL is configured and Rails can authenticate, you can create your application’s development and test databases.
+This step verifies that Rails is correctly connected to PostgreSQL and that the pg gem is working on your Arm64 environment.
 
+Run the following command from inside your Rails app directory:
 ```console
 rails db:create
 ```
@@ -140,22 +166,26 @@ You should see output similar to:
 Created database 'db_test_rubyapp_development'
 Created database 'db_test_rubyapp_test'
 ```
-This means Rails successfully connected to PostgreSQL and created both dev and test databases.
+This output confirms that Rails successfully. It connected to the PostgreSQL service using the credentials from `config/database.yml` and created two new databases — one for development and one for testing.
 
 ### Generate a Scaffold for Testing
-A database and Scaffold are required to create the actual PostgreSQL database for your Rails app and quickly generate the model, controller, views, and migrations for your data.
-Let’s create a small test model and table — for example, a simple Task tracker:
+To verify your Ruby on Rails and PostgreSQL integration, you’ll create a small scaffold application.
+A scaffold is a Rails generator that automatically builds a model, controller, views, and database migration, allowing you to test CRUD (Create, Read, Update, Delete) operations quickly.
+
+For this example, you’ll create a simple Task Tracker app that manages tasks with titles and due dates.
+Run the following command inside your Rails project directory:
 
 ```console
 rails generate scaffold task title:string due_date:date
 ```
-This command automatically generates:
-- Database migration for the tasks table
-- A model (task.rb)
-- A controller and views for CRUD operations
-- **Scaffold** → Automatically generates boilerplate code for CRUD operations, saving time and ensuring your app has working forms and routes.
+This single command automatically generates:
+A database migration to create the tasks table in PostgreSQL.
+A model file (app/models/task.rb) that maps to the tasks table.
+A controller (app/controllers/tasks_controller.rb) with full CRUD actions (index, show, new, create, edit, update, destroy).
+Corresponding views in app/views/tasks/ with ready-to-use HTML + embedded Ruby templates.
+Route entries in config/routes.rb to make the new resource accessible via /tasks.
 
-Then apply the migration:
+Now apply the migration to create the tasks table in your PostgreSQL database:
 
 ```console
 rails db:migrate
@@ -169,17 +199,16 @@ You should see output similar to:
 == 20251006101717 CreateTasks: migrated (0.0128s) =============================
 ```
 
-Database schema successfully updated.
+This confirms that Rails connected successfully to PostgreSQL and the database schema was updated.
+The new tasks table was created inside your db_test_rubyapp_development database.
 
 ### Verify Table and Database Connectivity
-The previous command `rails generate scaffold task title:string due_date:date` created a `tasks` table in your PostgreSQL database.
-
-Now, verify that the table exists and has the correct structure following the steps below:
+TThe scaffold created a tasks table in your PostgreSQL database. Verify it exists and has the expected schema:
 
 ```console
 sudo -u postgres psql
 ```
-In the PostgreSQL shell, run the following commands:
+Inside the PostgreSQL shell, run:
 
 ```console
 \c db_test_rubyapp_development
@@ -211,7 +240,7 @@ Indexes:
     "tasks_pkey" PRIMARY KEY, btree (id)
 ```
 
-### Run Rails Server
+### Open port 3000 in Google Cloud (VPC firewall)
 Before proceeding to run the Rails server, you need to allow port 3000 from your GCP console. Below are the steps to do that:
 
 a. On the GCP console, navigate to **Firewall** -> **Create Firewall Rule**
@@ -241,20 +270,22 @@ In the **"Protocols and Ports"**, click on **"TCP"**, and mention the port numbe
 Click on **"Create"**. The Firewall rule will be created successfully and can be viewed in the Firewall Policies Page:
 
 ![ Create Firewall rule alt-text#center](images/firewall5.png "Figure 5: Create Firewall rule")
- 
-Once done, go back to the VM, install FirewallD 
+
+ ### OS firewall (firewalld) on SUSE
+Once done, go back to your VM, install FirewallD:
 ```console
 sudo zypper install firewalld
 ```
-
-Now start FirewallD and execute the below commands to allow port 3000:
+Now start FirewallD and execute the commands to allow port 3000:
 
 ```console
 sudo systemctl start firewalld
 sudo systemctl enable firewalld
 sudo firewall-cmd --permanent --add-port=3000/tcp
 sudo firewall-cmd --reload
 ```
+
+## Start Rails
 Now that port 3000 is allowed in your VM’s ingress firewall rules, you can start the Rails server using the following command:
 
 ```console
@@ -276,4 +307,4 @@ You will see a Rails welcome page in your browser if everything is set up correc
 
 ![Rails-info page alt-text#center](images/rails-web.png "Figure 6: Ruby/Rails Welcome Page")
 
-This verifies the basic functionality of the Ruby/Rails installation before proceeding to the benchmarking.
+With port 3000 reachable and the welcome page loading, your Rails stack on SUSE Arm64 (C4A Axion) is verified end-to-end and you can proceed to benchmarking.