Forem: Mahinsha Nazeer

Building Friday: A Multi-Provider AI Agent That Lives in Your Terminal

Mahinsha Nazeer — Sun, 12 Apr 2026 01:38:39 +0000

“Just a rather very intelligent system.” — Tony Stark 😀

Every DevOps Engineer has a terminal open. What if that terminal could think?

Friday — an open-source, multi-provider AI agent that runs entirely in your terminal. No browser tabs, no Electron apps, no subscriptions bundling features you don’t need. Just a clean, minimal CLI that connects to Gemini, ChatGPT, Claude, GitHub Copilot, or your own local Ollama server — and lets you switch between them with a single command.

In this post, I’ll walk through why I built it, the architecture behind it, and how you can install it in one command.

What Friday Delivers

Friday is a terminal-native AI agent with three core capabilities:

1. Multi-Provider Chat

Connect to any major AI provider through a unified interface:

The Problem

Modern AI workflows are fragmented:

Multiple browser tabs (ChatGPT, Claude, Gemini)
Constant copy-paste between the terminal and AI tools
No direct execution — only suggestions

Even simple queries, like checking disk usage, require manual execution after being asked.

The requirement was clear:

A single interface that supports multiple models and can perform real actions on the machine.

What Friday Delivers

1. Unified Multi-Provider Interface

Friday integrates major AI providers into one CLI:

available providers

Model availability is dynamically fetched via APIs — ensuring accuracy without manual updates.

2. Agentic Capabilities for DevOps

Friday is built for execution, not just conversation.

Core capabilities:

Shell command execution (with confirmation)
File operations (read, write, search)
Web search integration
System diagnostics (CPU, memory, disk)
Python execution

Example:

Instead of suggesting commands, Friday directly performs tasks like file discovery or diagnostics.

All critical operations require explicit confirmation, ensuring safety.

3. Voice Interaction

Voice support enables hands-free interaction:

Toggle via /voice
Speak queries with empty input
Configure pitch, speed, and voice profile

This is particularly useful during troubleshooting or multitasking scenarios.

Architecture Overview

Friday follows a modular, provider-agnostic architecture:

Application Layer (CLI + Commands)
        ↓
Friday Client (Abstraction Layer)
        ↓
Providers (Gemini, OpenAI, Claude, Copilot, Ollama)

Provider Abstraction

Each provider implements a common interface:

class BaseProvider(ABC):
    def initialize(self): ...
    def chat(self, message, history, tools): ...
    @property
    def model(self): ...

This enables seamless extensibility with minimal integration effort.

Tool System

Tools are defined once and adapted across providers:

@register_tool
def get_system_info():
    return {...}

A universal schema ensures compatibility across different APIs.

Dynamic Model Discovery

Friday queries provider APIs at runtime:

Eliminates outdated configurations
Supports local and remote Ollama instances
Ensures real-time model availability

Command System

A structured command interface simplifies interaction:

/login Connect provider
/switch Change provider
/model Select model
/logout Remove credentials
/voice Toggle voice
/voice config Configure voice
/tools List tools
/help Show commands
bye Exit

Credentials are securely stored with restricted permissions.

User Interface

Built using the Rich library, the UI is clean and minimal:

Color-coded provider panels
Markdown rendering with syntax highlighting
Interactive menus
Lightweight terminal-first design

The focus remains on usability rather than visual complexity.

Getting Started

Installation

git clone https://github.com/mahinshanazeer/friday.git && cd friday && bash install.sh

First Run

friday

Authenticate using /login, and the session persists for future use.

Uninstall

cd friday && bash uninstall.sh

Key Learnings

1. Provider APIs Differ Significantly

Function-calling implementations vary widely across providers, requiring a unified abstraction layer.

2. Terminal UX Matters

Design improvements significantly impact usability and adoption.

3. Reliability Is Critical

Graceful handling of missing dependencies or failures ensures stability.

4. Persistence Improves Experience

Credential storage transformed the tool from experimental to practical.

Built Using AI

Friday itself was built using AI-assisted development:

Antigravity — architecture and scaffolding
GitHub Copilot — inline coding
Claude — design validation and reviews

Workflow:

Define architecture via prompts
Iteratively build features
Debug and refine using AI

Result: A production-ready system built in hours rather than weeks.

Roadmap

Planned improvements include:

Streaming responses
Chat export functionality
Plugin architecture
Multi-modal input (image support)
Git integration

Repository

🔗 https://github.com/mahinshanazeer/friday

git clone https://github.com/mahinshanazeer/friday.git && cd friday && bash install.sh

Closing Note

Friday is built on a simple principle:

Your terminal should not just execute commands — it should assist, decide, and act.

Installing and Configuring n8n on a Raspberry Pi (Private Home Server)

Mahinsha Nazeer — Mon, 23 Mar 2026 14:49:52 +0000

GitHub - mahinshanazeer/n8n-home-server: Installing and Configuring n8n on a Raspberry Pi (Private Home Server)

Introduction

Automation is becoming a core part of modern workflows, whether for DevOps, personal productivity, or integrations. n8n is a powerful, open-source workflow automation platform that allows you to create custom integrations with full control over your data.

In this guide, we will set up n8n on a Raspberry Pi using Docker, configured for private network access (no domain, no SSL) — ideal for home labs.

Why Self-Host n8n on Raspberry Pi?

Low-cost, always-on device
Full data privacy (no third-party cloud dependency)
Perfect for home lab and DevOps experimentation
Lightweight yet powerful automation engine

Prerequisites

Ensure the following are ready:

Raspberry Pi (Pi 4/5 recommended, 4GB+ RAM)
Linux OS (Ubuntu Server / Raspberry Pi OS Lite)
Docker & Docker Compose installed
Static private IP (recommended)

Project Structure

We will keep everything inside a single directory:

~/n8n/
├── .env
├── docker-compose.yml
├── n8n-data/
└── local-files/

directory structure

This approach ensures:

Easy backup
Clean portability between systems
Full control over persistent data

Step 1: Create Project Directory

mkdir -p ~/n8n && cd ~/n8n
mkdir n8n-data local-files

Step 2: Create Environment Configuration

Create a .env file:

nano .env

Add the following:

N8N_HOST=192.168.1.200
N8N_PORT=5678
N8N_PROTOCOL=http

WEBHOOK_URL=http://192.168.1.200:5678/

GENERIC_TIMEZONE=Asia/Kolkata

N8N_SECURE_COOKIE=false

Key Notes:

N8N_HOST → Your Raspberry Pi private IP
WEBHOOK_URL → Required for workflows
N8N_SECURE_COOKIE=false → Mandatory for HTTP access

Step 3: Create Docker Compose File

Create docker-compose.yml:

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    container_name: n8n
    restart: always
    ports:
      - "5678:5678"
    environment:
      - N8N_HOST=${N8N_HOST}
      - N8N_PORT=${N8N_PORT}
      - N8N_PROTOCOL=${N8N_PROTOCOL}
      - N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=${N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS}
      - N8N_SECURE_COOKIE=${N8N_SECURE_COOKIE}
      - NODE_ENV=${NODE_ENV}
      - WEBHOOK_URL=${WEBHOOK_URL}
      - GENERIC_TIMEZONE=${GENERIC_TIMEZONE}
      - TZ=${GENERIC_TIMEZONE}
    volumes:
      # n8n data: SQLite database and encryption key
      - ./n8n-data:/home/node/.n8n
      # Shared files between n8n and host (use /files path inside n8n)
      - ./local-files:/files

Step 4: Start n8n

docker compose up -d

Verify:

docker compose ps

Step 5: Access n8n

Open in browser:

http://192.168.1.200:5678

home page

Create your admin account
Start building workflows (will create another blog on building workflows)

Common Issue (Important)

Secure Cookie Error

You may see:

“Your n8n server is configured to use a secure cookie…”

Fix:

Set in .env:

N8N_SECURE_COOKIE=false

Restart:

docker compose down
docker compose up -d

Data Persistence

All important data is stored in:

~/n8n/n8n-data

This includes:

Workflows
Credentials
SQLite database

Github: https://github.com/mahinshanazeer/n8n-home-server

From a Confused Graduate to a DevOps Engineer

Mahinsha Nazeer — Mon, 09 Mar 2026 06:50:36 +0000

This is a submission for the 2026 WeCoded Challenge: Echoes of Experience

After graduating with a B.Tech in Electronics and Communication Engineering, I was confused about which profession to choose. There were no mentors around me, and no one I knew worked in this field. Choosing a career path was difficult. I attended several aptitude tests and managed to clear some of them, but I often struggled during interviews because of my poor communication skills. Even today, I still find it challenging to express what is in my mind clearly. Many times, when I tried to explain something, people misunderstood me, which made me even more disappointed.

After about two months, I received an offer from a company based in Bangalore. Because of the COVID situation, the job was remote. However, the role turned out to be very different from what was described in the job description. It was not a technical role, and the work environment was quite toxic. Since there was nothing meaningful to learn and it did not help in building my career, I decided to resign after just one month. Looking back today, it was one of the wisest decisions I have made in my life.

Soon after that, I received a call from another company located in Cochin, close to my hometown. The role was related to Linux, so I decided to give it a try.

I joined Poornam Infovision in January 2022. Initially, it was very tough because I had no background in Linux. After completing my training period, I moved to a team that provided shared hosting support. We handled more than 60 clients and mainly provided ticket-based support. Even though there were some Linux-related tasks, most of the work involved cPanel and Plesk.

I struggled with multitasking. The ticket flow in the team was very high, and handling multiple issues simultaneously was difficult for me. When I worked on several things at the same time, I sometimes missed important details in tickets, which started affecting my performance. After a few months, HR noticed this, and they initially decided to let me go. I was mentally prepared for it because I felt this role was not the right fit for me.

However, instead of terminating my role, the HR lead decided to give me another chance and moved me to a different team. That decision completely changed my life.

In my second team, the most interesting person was my team lead. He became my first real mentor and guided me well. When I joined the team, we had only two clients. Suddenly, we received another client — a data centre where we managed operations. The work involved pure Linux and networking. That was the moment things started to become interesting for me.

My lead handed over full responsibility for that client to me. It became my first client. In my previous team, my lead was afraid to even let me handle a single ticket, but here someone trusted me with an entire client. I gave my 100% effort, and things slowly started to change. I became more interested in learning new technologies.

During the same time, one of my college friends joined an MNC and told me about the tasks he was doing during training. That motivated me to start learning on my own. I created an AWS account and launched my first EC2 instance. I experimented with setting up reverse proxies, configuring firewalls, and deploying websites on my server. Slowly, I began exploring other AWS services as well.

During this period, the client I was handling was moved to another team because it required deeper networking expertise. However, the company decided to merge our team with another team that was focused on AWS. This gave me the opportunity to apply what I had been learning on my own.

By this time, I had developed a basic understanding of Linux and networking through data centre operations. Through self-learning, I also gained knowledge of core AWS services. From my hosting support experience, I already knew the basics of DNS and Linux systems. This was only the seventh month of my career.

After the teams merged, we started working on multiple projects together. The environment was very open and collaborative. There were no strict restrictions — we explored problems from different perspectives and discussed ideas as a team. This helped us gain a deeper technical understanding.

I never stopped learning. I dedicated at least one hour every day to learning something new. I started learning Docker and CI/CD tools. In one of our projects, Docker was required, but the microservices were running as traditional Linux services. I proposed the idea of containerising them to my lead, and he showed interest.

We attempted to containerise the microservices. I spent more than two months working on it, but eventually failed to achieve the final result. However, during that process, I learned a lot. I gained a deep understanding of file descriptor tables, Docker, Docker Compose, Docker Swarm, Docker networking, volumes, resource management, and secrets.

Because my early performance in the first team had affected my evaluation, my salary remained very low — around ₹12,000 per month. Meanwhile, some new employees in the team were earning more than ₹25,000. I never complained about it. I focused on learning and improving myself. From a management perspective, they were evaluating based on output, so technically it was understandable.

After spending two years there, I decided it was time to explore new opportunities. I started applying to other companies and attending interviews. Once again, my communication challenges became a barrier. Even though I had the technical knowledge, explaining it clearly was difficult. But I kept trying.

Eventually, I received an offer from Infosys.

At Infosys, I joined a legacy project that was around 15 years old. The team was working on modernising the infrastructure. The project was related to aircraft maintenance systems, and the infrastructure was fully based on AWS.

At Infosys, I learned a lot about professional processes and enterprise environments. I also worked on improving my communication skills. I learned Bash scripting and started building automation using AWS CLI. I also designed and set up a self-managed Kubernetes cluster as a testing environment. Through this, I gained a better understanding of system architecture and infrastructure design.

However, after spending almost a year there, I felt that my learning opportunities were becoming limited. Most of the work involved routine operational tasks. I applied internally for other opportunities and even got selected for an Azure-based project. Unfortunately, my manager did not release me from the current project because my performance was strong.

At that point, I realized that resignation was the only option. Exactly one year after joining, I decided to resign.

Currently, I am working at Accenture Song. It has been about seven months now. I received the offer and joined immediately after my last working day at Infosys.

The work here is more challenging. I have to communicate directly with clients and handle complex tasks. There is definitely pressure, but I actually enjoy it. Every day is different, with new challenges and new learning opportunities.

When I look back at my journey, I realise that the best decisions I made were choosing the right opportunities at the right time. Instead of staying in my comfort zone, I focused on improving myself.

I am naturally a very introverted person, and my current role requires constant communication with clients. I am still working on improving this skill. At one point in my life, I never imagined that I would work at a company like Accenture. But life has its own way of surprising us.

I do not know where I will be in the next 5 or 10 years. But I am certain about one thing — I will continue to take opportunities, keep learning, and keep improving myself.

I still remember that, in the early stages of my career, I often thought about quitting. Looking back today, not quitting was one of the best decisions I have ever made. I may not be working at the biggest company or earning the highest salary. But for someone like me — a person who started with nothing and had no background or guidance in this field — this journey itself feels like an achievement.

Automating Daily Tasks with systemd Timers: A Practical Guide Using Python

Mahinsha Nazeer — Sat, 29 Nov 2025 06:32:45 +0000

In this guide, I will demonstrate how to automate a daily Python task using systemd timers on Linux. We plan to automate a scheduled script execution on our home-lab Raspberry Pi, which operates 24×7 and also functions as the in-house DNS server for our home network.

1) Short overview

The setup uses a virtual environment located at /home/admin/devops_digest/devops_env/bin/python3 and runs a Python script placed at /home/admin/devops_digest/daily_linkedin.py every day at 7:00 AM. This walkthrough provides a clean and reliable approach suitable for production systems, ensuring your scheduled jobs run consistently without relying on external cron utilities.

Below is a concise, production-ready guide you can use in your blog. It explains each step, includes copy-pasteable commands and example service/timer files, and covers testing, logging, security and common troubleshooting notes.

2) Prerequisites

Linux system with systemd (most modern distributions).
Script located at /home/admin/devops_digest/daily_linkedin_debug.py.
A Python virtual environment at /home/admin/devops_env with required packages installed.
User who will run the job (admin in examples). Adjust paths/user if different.
(Optional) bsd-mailx configured if your script sends mail.

3) Why use systemd timers

More reliable than cron (handles missed runs with Persistent=true).
Centralised logs via journalctl.
Fine-grained control over runtime environment and restart/timeout policies

4) Create the systemd service unit

Create /etc/systemd/system/devops_digest.service with the exact content below:

[Unit]
Description=Daily LinkedIn DevOps Digest Generator
Documentation=man:systemd.service(5)
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
User=admin
WorkingDirectory=/home/admin/devops_digest
# Use the venv python interpreter to avoid environment issues
ExecStart=/home/admin/devops_env/bin/python /home/admin/devops_digest/daily_linkedin_debug.py
# Set a sensible timeout
TimeoutStartSec=600
# Restrict capabilities for safety (optional)
PrivateTmp=yes
ProtectSystem=full
NoNewPrivileges=yes

Notes:

User=admin runs the job as admin. Change it if needed.
ExecStart points to the venv Python so pip-managed packages inside the venv are used.

systemd service

5) Create the systemd timer unit

Create /etc/systemd/system/devops_digest.timer:

[Unit]
Description=Run DevOps Digest every morning at 07:00

[Timer]
# Run daily at 07:00 local time
OnCalendar=*-*-* 07:00:00
# If the machine was off at scheduled time, run at bootup
Persistent=true
# Randomized delay (optional) to avoid thundering herd if many timers exist
RandomizedDelaySec=1m
[Install]
WantedBy=timers.target

systemd timer

6) Enable and start the timer

Reload systemd, enable and start the timer:

sudo systemctl daemon-reload
sudo systemctl enable --now devops_digest.timer

Verify timer is active and next run:

systemctl list-timers devops_digest.timer --all
# or
systemctl status devops_digest.timer

enabling timer

7) Test the service manually

Run the service once to test behaviour and logs:

sudo systemctl start devops_digest.service
sudo systemctl status devops_digest.service --no-pager

Testing

View logs from the last run:

journalctl -u devops_digest.service -n 200 --no-pager

If the job runs as a non-root user and writes files in the user's home, check file ownership and that the User= is correct.

8) Inspect timer runs and history

To see when the timer last ran and when it will run next:

systemctl list-timers --all | grep devops_digest

For recent timer and service logs:

journalctl -u devops_digest.timer -u devops_digest.service --since "2 days ago" --no-pager

next schedule

9) Handling environment/secrets

Do not put secrets in unit files. Use environment files with strict permissions:
Create /etc/devops_digest/env with KEY=value lines.
Protect it: sudo chown root:root /etc/devops_digest/env && sudo chmod 600 /etc/devops_digest/env
In the service unit: add EnvironmentFile=/etc/devops_digest/env.
Alternatively, source venv and have the script read secrets from ~/.config/devops_digest/ with 600 perms.

Example addition to [Service]:

EnvironmentFile=/etc/devops_digest/env

10) Recovering from failures

Add retry behaviour by using a small wrapper script that retries transient failures, or use Restart=on-failure (not typically useful for oneshot service).
Check logs: journalctl -u devops_digest.service -b
If your script requires a network, ensure network-online.target in [Unit] and Wants=network-online.target are present.

11) Optional: systemd user timer (runs as user)

If you prefer not to create root-owned units, you can use user-level systemd timers:

# as admin user (no sudo)
mkdir -p ~/.config/systemd/user
# copy the .service and .timer into ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now devops_digest.timer

Advantages: no root required. Disadvantages: user systemd must be running (e.g., login session or lingering enabled with loginctl enable-linger admin).

12) Security considerations

Run service as non-root user (User=).
Use PrivateTmp=yes, NoNewPrivileges=yes, ProtectSystem=full where applicable.
Keep venv and script permissions restricted to the running user.
Store secrets in protected files (chmod 600) or in a secrets manager.

13) Sample files recap

/etc/systemd/system/devops_digest.service — service unit (see step 4).
/etc/systemd/system/devops_digest.timer — timer unit (see step 5).
(Optional) /etc/devops_digest/env — env file for secrets (owner root, mode 600).

14) Troubleshooting checklist

systemctl status devops_digest.service → immediate errors.
journalctl -u devops_digest.service -e → full logs.
Check the script shebang and that ExecStart uses the venv Python.
Ensure User has permissions to read/write files referenced by the script.
If feed access fails, test curl from the server to verify network/DNS.

15) Quick blog-friendly conclusion

Systemd timers are the correct choice for reliable scheduled automation on modern Linux servers. They provide robust scheduling, built-in logging, easy management, and options for secure, user-scoped execution. For a daily digest job that runs Python from a virtualenv and emails results, use a one-shot service + timer, set Persistent=true and test with manual runs and journalctl before relying on automation.

Just Upgraded My Raspberry Pi Kubernetes Cluster to v1.34! I’ve documented the entire process of upgrading my Raspberry Pi–based Kubernetes cluster from v1.29 v1.34, including ETCD backup, incremental version upgrades, and some practical troubleshooting

Mahinsha Nazeer — Thu, 16 Oct 2025 14:44:13 +0000

Upgrading Our Raspberry Pi Kubernetes Cluster: From v1.29 to v1.34 & ETCD Backup Guide

Mahinsha Nazeer ・ Oct 16 '25

#raspberrypi #kubernetes #etcd #kubernetescluster

Upgrading Our Raspberry Pi Kubernetes Cluster: From v1.29 to v1.34 & ETCD Backup Guide

Mahinsha Nazeer — Thu, 16 Oct 2025 14:35:59 +0000

Keeping your cluster up-to-date is crucial for security, stability, and access to new features. In this blog, we’ll take a closer look at our home lab Kubernetes cluster running on Raspberry Pi devices. The setup includes 1 master node and 3 worker nodes, and it has been running smoothly for over four months without any major issues.

k8s home lab configuration — nodes

master2 — master node/ control plane

master1 — worker node 3

worker 1 — worker node 1

worker 2 — worker node 2

k8s home lab configuration — system components

As part of regular maintenance and to stay up-to-date with the latest features and security patches, we decided to upgrade the cluster from Kubernetes v1.29 to v1.34. Alongside the upgrade, we’ll also walk through the process of backing up the ETCD datastore, which is crucial for fault tolerance and disaster recovery.

Here’s what we’ll cover:

⬆️ Step-by-step guide to upgrading Kubernetes components.
🛡️ Safely backing up ETCD in the master node.
✅ Post-upgrade verification.

A. Backing Up ETCD

Before diving into the upgrade process, it’s essential to create a backup of ETCD, the key-value store that holds all cluster state data. This step is crucial because if anything goes wrong during the upgrade — whether it’s a misconfiguration or a failed component — we need a reliable way to restore the cluster to its current stable state.

Think of the ETCD backup as your safety net. It ensures that even in the worst-case scenario, you won’t lose your cluster’s configuration, workloads, or networking setup.

Run the following command to confirm the ETCD pod name running on your control plane:

kubectl get pods -n kube-system | grep etcd

k8s configuration — ETCD setup

Suppose your control plane (master node) runs ETCD as a static pod (which is the default in kubeadm-based clusters, including Raspberry Pi setups). In that case, you can run etcdctl directly on the master node host — because the ETCD data directory and certificates are mounted locally at /etc/kubernetes/pki/etcd/ and /var/lib/etcd/. In that case, you can use the following command to take the backup:

sudo ETCDCTL_API=3 etcdctl snapshot save /var/lib/etcd/backup.db \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key

If ETCD runs as a container (inside the pod) or you don’t have the etcdctl binary available on the host, then you’ll need to exec into the pod to run the backup from inside the container.

In my setup, where etcd runs as a container, I need to access the pod directly to execute the backup. There is no etcdctl binary available on the host.

kubectl exec -n kube-system <node-label>-- \
  etcdctl snapshot save /var/lib/etcd/backup.db \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key

#edit the <node-label> with etcd node

Creating backup

Now, verify the snapshot using the following command:

kubectl exec -n kube-system <node-label>-- \
  etcdctl snapshot status /var/lib/etcd/backup.db -w table

In the above screenshot, you can seee a deprecation warning. ETCD v3.6+ is deprecated etcdctl snapshot status and recommends using etcdutl snapshot status. However, in my kubeadm static pod setup, the etcdutl binary is not included in the ETCD container. Only etcdctl exists inside the pod. The warning is simply a deprecation notice, not a failure. You can safely continue using it etcdctl snapshot status — it works perfectly.

In my setup, I came across a deprecation warning while using etcdctl. To verify, I checked the current version of etcd using the following command.

Since my cluster is kubeadm-managed, even though etcd v3.6+ recommends using etcdutl for snapshot management, etcdctl inside the etcd pod still works perfectly for backup and restore. etcdutl is a newer utility introduced in etcd v3.6+ as a replacement for certain snapshot operations, but in my case, continuing with etcdctl is fully sufficient.

kubectl exec -n kube-system etcd-master2 -- etcdctl version

etcd version checking

In some scenarios, the etcd backup file may reside only inside the etcd pod and not in a host-accessible directory.

This can happen if the etcd container is minimal and lacks tools like tar to move files around, or if the host does not have etcdctl installed to create the snapshot directly. In such cases, you can use specific commands to move the backup file to a host-accessible directory.

kubectl cp kube-system/etcd-master2:/tmp/backup.tar.gz ./backup.tar.gz

In my setup, I created the etcd snapshot directly on the host in a host-accessible directory (for example, /var/lib/etcd/backup.db). Since the backup is already on the host, it can be copied or archived without using kubectl cp.

sudo cp /var/lib/etcd/backup.db ~/backup.db
sudo chown $USER:$USER ~/backup.db
ls -l ~/backup.db

backup.db file status

Additionally, it’s a good practice to create a copy of the backup on a remote server. This ensures an extra layer of safety and helps protect against data loss in case of hardware failure or accidental deletion.

B. Upgrading the cluster

Since we have backed up etcd, we can safely proceed with the kubeadm upgrade for our Raspberry Pi Kubernetes cluster. Let’s go through a step-by-step process to upgrade the cluster from v1.29 → v1.34.

Kubernetes officially supports upgrading one minor version at a time, which means that to move from 1.29 to 1.34, you need to perform incremental upgrades:

Step 1: v1.29 → v1.30
Step 2: v1.30 → v1.31

Step 3: v1.31 → v1.32

Step 4: v1.32 → v1.33

Step 5: v1.33 → v1.34

Please refer to the following URL for k8s official documentation on skew policy:

Version Skew Policy

Step 1: Pre-Checks for upgrading the cluster

Before upgrading the cluster, it’s essential to ensure that the cluster is healthy and stable. This helps prevent issues during the upgrade and ensures a smooth transition between versions.

kubectl version
kubectl get nodes
kubectl get cs
kubectl get pods -n kube-system

Current status of the cluster

Step 2: Upgrade kubeadm on the Master Node

You can also refer to the following documentation for more details regarding kubeadm upgrade:

Upgrading kubeadm clusters

To upgrade to v1.30, ensure that the directory /etc/apt/keyrings exists. If it doesn’t, create it before running the curl command (see the note below). Afterwards, update the package repository to target v1.30.

Each Kubernetes minor release repository (v1.29, v1.30, v1.31, etc.) may use a different GPG key. Using the key from an older version, such as v1.29, can cause package verification failures when installing packages from the v1.30 repository.

To prevent such errors, always use the GPG key and repository provided specifically for the minor version you are upgrading to.

# If the directory `/etc/apt/keyrings` does not exist, it should be created before the curl command, read the note below.
# sudo mkdir -p -m 755 /etc/apt/keyrings
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.30/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

# This overwrites any existing configuration in /etc/apt/sources.list.d/kubernetes.list
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.30/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

Before upgradingkubeadmEnsure your package lists are up to date. Then, install the required version by using the following commands

sudo apt-mark unhold kubelet kubeadm kubectl && \
sudo apt-get update
sudo apt-get install -y kubeadm=1.30.14-1.1 kubelet=1.30.14-1.1 kubectl=1.30.14-1.1
sudo apt-mark hold kubelet kubeadm kubectl

If you want to upgrade to a specific Kubernetes version, you can use the following command to list all available minor versions in the corresponding repository:

apt-cache madison kubeadm

available packages in the repo

For comprehensive guidance on upgrading your Kubernetes cluster to version v1.30 , refer to the official Kubernetes documentation:

Installing kubeadm

This resource provides detailed, step-by-step instructions tailored for clusters managed with kubeadm , ensuring a smooth and efficient upgrade process.

Once the upgrade is complete, verify the kubeadm version using the following command:

kubeadm version
kubectl version --client
kubelet --version

current kubeadm version

Step 3: Plan the Upgrade

After upgrading kubeadm, it’s important to check the upgrade path and verify the versions of all cluster components. This ensures that all parts of your Kubernetes cluster are compatible and running the expected versions.

sudo kubeadm upgrade plan

It will display:

The current cluster version and control plane version.
The available target versions you can upgrade to.
The versions of kubelet and kubectl on your nodes.
Any required steps or notes for a smooth upgrade.

kubeadm upgrade plan output — 1

kubeadm upgrade plan output — 2

Step 4: Upgrade the Control Plane

Once the upgrade plan is reviewed and all changes are understood, you can proceed with upgrading the cluster. Use the kubeadm upgrade apply command, which is provided in the output of kubeadm upgrade plan.

sudo kubeadm upgrade apply v1.30.14

The upgrade process may take some time, depending on the size and complexity of your cluster. Once it completes successfully, you should see a message similar to the following:

upgraded to “v1.30.14”

Now, verify the control plane using the following commands:

#rebooting the master node or restarting the kubelete is highly recommended
sudo systemctl daemon-reload
sudo systemctl restart kubelet
kubectl get nodes
kubectl get pods -n kube-system

Step 5: Upgrade Worker Nodes

Now repeat the same steps from ‘Step 2: Upgrade kubeadm on the Master Node’ again in master1, worker1 and worker2 nodes (worker nodes). Workers do not control the cluster state; running upgrade plan there doesn’t provide meaningful information. First drain the worker node from the control plane, so that all the resources will be taken out of the node

ssh to controlplane (master2)
-------------------------------
#step 1:
kubectl drain <worker-node> --ignore-daemonsets --delete-emptydir-data

***
kubectl drain worker1 --ignore-daemonsets --delete-emptydir-data
***

draining resources from worker node (master1)

Now you can repeat the steps we followed for control plane for upgrading the version:

ssh to master1 node
-------------------------------
#step 1:
sudo rm -rf /etc/apt/sources.list.d/kubernetes.list

#step 2:
# If the directory `/etc/apt/keyrings` does not exist, it should be created before the curl command, read the note below.
# sudo mkdir -p -m 755 /etc/apt/keyrings
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.30/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
#step 3:
# This overwrites any existing configuration in /etc/apt/sources.list.d/kubernetes.list
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.30/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

#step 4:
sudo apt-mark unhold kubelet kubeadm kubectl && \
sudo apt-get update
sudo apt-get install -y kubeadm=1.30.14-1.1 kubelet=1.30.14-1.1 kubectl=1.30.14-1.1
sudo apt-mark hold kubelet kubeadm kubectl

#step 5:
kubeadm version

#step 6:
#rebooting the master node or restarting the kubelete is highly recommended
sudo systemctl daemon-reload
sudo systemctl restart kubelet
kubectl get nodes
kubectl get pods -n kube-system

#step 7:
kubeadm upgrade node

upgrading worker node — host ‘master2’ is a worker node here. (master2 — master node/ control planemaster1 — worker node 3worker 1 — worker node 1worker 2 — worker node 2)

Also verify the nodes from control plane:

upgrade completed

Now we can following commmand to make the node available for schedule;

kubectl uncordon master1
#run this command in the control plane.

Marking node as schedulable

kubectl uncordon command is used to mark a node as schedulable again after it has been drained.

Similarly we can do the upgrades in other 2 worker nodes, I will mention the commands below:

worker1:

ssh to controlplane (master2)
-------------------------------
#step 1:
kubectl drain <worker-node> --ignore-daemonsets --delete-emptydir-data

***
kubectl drain worker1 --ignore-daemonsets --delete-emptydir-data
***

ssh to worker1 node

#step 1:
sudo rm -rf /etc/apt/sources.list.d/kubernetes.list

#step 2:
# If the directory `/etc/apt/keyrings` does not exist, it should be created before the curl command, read the note below.
# sudo mkdir -p -m 755 /etc/apt/keyrings
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.30/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
#step 3:
# This overwrites any existing configuration in /etc/apt/sources.list.d/kubernetes.list
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.30/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

#step 4:
sudo apt-mark unhold kubelet kubeadm kubectl && \
sudo apt-get update
sudo apt-get install -y kubeadm=1.30.14-1.1 kubelet=1.30.14-1.1 kubectl=1.30.14-1.1
sudo apt-mark hold kubelet kubeadm kubectl

#step 5:
kubeadm version

#step 6:
#rebooting the master node or restarting the kubelete is highly recommended
sudo systemctl daemon-reload
sudo systemctl restart kubelet

#step 7:
sudo kubeadm upgrade node

ssh to controlplane (master2)
-------------------------------
#step 1:
kubectl uncordon worker1
kubectl get nodes
kubectl get pods -n kube-system

worker2:

ssh to controlplane (master2)
-------------------------------
#step 1:
kubectl drain <worker-node> --ignore-daemonsets --delete-emptydir-data

***
kubectl drain worker2 --ignore-daemonsets --delete-emptydir-data
***

ssh to worker2 node
-------------------------------
#step 1:
sudo rm -rf /etc/apt/sources.list.d/kubernetes.list

#step 2:
# If the directory `/etc/apt/keyrings` does not exist, it should be created before the curl command, read the note below.
# sudo mkdir -p -m 755 /etc/apt/keyrings
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.30/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
#step 3:
# This overwrites any existing configuration in /etc/apt/sources.list.d/kubernetes.list
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.30/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

#step 4:
sudo apt-mark unhold kubelet kubeadm kubectl && \
sudo apt-get update
sudo apt-get install -y kubeadm=1.30.14-1.1 kubelet=1.30.14-1.1 kubectl=1.30.14-1.1
sudo apt-mark hold kubelet kubeadm kubectl

#step 5:
kubeadm version

#step 6:
#rebooting the master node or restarting the kubelete is highly recommended
sudo systemctl daemon-reload
sudo systemctl restart kubelet
kubectl get nodes
kubectl get pods -n kube-system

#step 7:
sudo kubeadm upgrade node

ssh to controlplane (master2)
-------------------------------
#step 1:
kubectl uncordon worker2

All nodes have now been successfully upgraded to v1.30.14 , as shown in the following screenshot.

kubernetes version v1.30.14

Step 5: Upgrading to 1.34

Following the same process, we’ll now proceed to upgrade the cluster from v1.30.14 to v1.31. Then we will proceed with with

Step 1: v1.29.15 → v1.30.14–1.1

Step 2: v1.30.14–1.1 → v1.31.13–1.1

Step 3: v1.31.13–1.1 → v1.32.9

Step 4: v1.32.9 → v1.33.5

Step 5: v1.33.5 → v1.34.1

In control-plane (master2) use the following steps to upgrade to version 1.31:

ssh to controlplane (master2)

#step 1:
sudo rm -rf /etc/apt/sources.list.d/kubernetes.list

# If the directory `/etc/apt/keyrings` does not exist, it should be created before the curl command, read the note below.
# sudo mkdir -p -m 755 /etc/apt/keyrings
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.31/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

# This overwrites any existing configuration in /etc/apt/sources.list.d/kubernetes.list
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.31/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

#step 2:
sudo apt update
apt-cache madison kubeadm

#step 3:
sudo apt-mark unhold kubelet kubeadm kubectl && \
sudo apt-get update
sudo apt-get install -y kubeadm kubelet kubectl #will take the latest version
sudo apt-mark hold kubelet kubeadm kubectl

#step 4:
kubeadm version
kubectl version --client
kubelet --version

#step 5:
sudo kubeadm upgrade plan

#step 6:
sudo kubeadm upgrade apply <version>
#I used the following command
sudo kubeadm upgrade apply v1.31.13

#step 7:
#rebooting the master node or restarting the kubelete is highly recommended
sudo systemctl daemon-reload
sudo systemctl restart kubelet
kubectl get nodes
kubectl get pods -n kube-system

Now lets setup the worker nodes:

ssh to controlplane (master2)
-------------------------------
#step 1:
kubectl drain <worker-node> --ignore-daemonsets --delete-emptydir-data

ssh to <worker-node> node
-------------------------------
#step 1:
sudo rm -rf /etc/apt/sources.list.d/kubernetes.list

#step 2:
# If the directory `/etc/apt/keyrings` does not exist, it should be created before the curl command, read the note below.
# sudo mkdir -p -m 755 /etc/apt/keyrings
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.31/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
#step 3:
# This overwrites any existing configuration in /etc/apt/sources.list.d/kubernetes.list
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.31/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

#step 4:
sudo apt update
apt-cache madison kubeadm
sudo apt-mark unhold kubelet kubeadm kubectl && \
sudo apt-get install -y kubeadm kubelet kubectl #will take the latest version
sudo apt-mark hold kubelet kubeadm kubectl

#step 5:
kubeadm version

#step 6:
sudo kubeadm upgrade node

#step 7:
#rebooting the master node or restarting the kubelete is highly recommended
sudo systemctl daemon-reload
sudo systemctl restart kubelet
kubectl get nodes
kubectl get pods -n kube-system

ssh to controlplane (master2)
-------------------------------
#step 1:
kubectl uncordon <worker-node>

upgraded to v1.31.13

Follow the same steps to upgrade sequentially through the remaining versions. The process remains identical — the only change is the repository you add in Step 2 , where the Kubernetes repository is updated.

Simply replace it with the corresponding repository for each target version before proceeding with the upgrade.

For v1.32:
------------
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.32/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.32/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

For v1.33:
------------
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.33/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.33/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

For v1.34:
------------
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.34/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.34/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

so far all good, if you want to restore the ETCD with the backup file you can follow below mentioned steps, you can use this incase if you need to revert back the changes.

sudo systemctl stop kube-apiserver
etcdctl snapshot restore /var/lib/etcd/backup.db \
  --data-dir /var/lib/etcd
#mention the exact path -/var/lib/etcd/backup.db
sudo systemctl start kube-apiserver

#now verify the installation using following command
etcdctl endpoint health \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key

kubectl get nodes
kubectl get pods --all-namespaces

version v1.34.1

We have now successfully completed the cluster upgrade. 🎉

If you have any questions, feel free to reach out — I’m not a specialist, but I’ll be happy to research and share the most accurate updates I can find.

A Hands-On Kubernetes Project for Starters

Mahinsha Nazeer — Sun, 07 Sep 2025 12:21:58 +0000

Deploying a Simple App on K3S in AWS EC2 with GitHub Actions & ECR

Mahinsha Nazeer ・ Sep 7 '25

#github #kubernetes #kubernetescluster #githubactions

Deploying a Simple App on K3S in AWS EC2 with GitHub Actions & ECR

Mahinsha Nazeer — Sun, 07 Sep 2025 12:15:31 +0000

In this session, we’ll walk through the configuration of K3S on an EC2 instance and deploy a multi-container application with a frontend, backend, and database. The application will run inside a Kubernetes cluster using Deployments and StatefulSets in headless mode. For the setup, we’ll use EC2 to host the cluster, GitHub as our code repository, and GitHub Actions to implement CI/CD.

If you’re an absolute beginner and not familiar with configuring EC2, I recommend checking out my blog here:

Step-by-Step Guide to Launching an EC2 Instance on AWS : For Beginners

This will be an end-to-end project deployment designed for those learning K3S, CI/CD, and Docker. You’ll gain hands-on experience in setting up CI/CD pipelines, writing Dockerfiles, and using Docker Compose. We’ll then move on to deploying the application in K3S, working with Kubernetes manifests, and exploring key components such as Deployments, Services (NodePort and ClusterIP), ConfigMaps, Persistent Volumes (PV), Persistent Volume Claims (PVC), and StatefulSets.

K3S is a lightweight Kubernetes distribution developed by Rancher (now SUSE). It’s designed to be:

Lightweight — small binary, minimal dependencies.

Easy to install — single command installation.

Optimized for edge, IoT, and small clusters — runs well on low-resource machines like Raspberry Pi or small EC2 instances.

Fully compliant — supports all standard Kubernetes APIs and workloads.

In short, K3S simplifies Kubernetes and makes it resource-efficient, making it ideal for single-node clusters, test environments, and learning purposes.

Log login to the EC2 machine and install k3s first:

K3s

You can install K3S on your machine using the following single command:

sudo apt update -y && sudo apt upgrade -y
curl -sfL https://get.k3s.io | sh - 
# Check for Ready node, takes ~30 seconds 
sudo k3s kubectl get node

Installation of k3s

Once the installation is completed, the output should be similar to this:

Kubectl node status

Once the cluster is up and running, we can move on to the application. You can refer to the following repository for the demo To-Do List app. Before cloning the repository, make sure Docker is installed on the machine to build and test the application. For installing Docker, refer to the following URL:

Ubuntu

#run the following command first to remove conficting packages

for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove $pkg; done

# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update

#Installing Docker
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

#Now verify the installtion.
sudo docker run hello-world

Now, let’s dive into the demo application. The Application Stack:

Frontend: React.js
Backend API: Node.js + Express
Database: MongoDB
Containerization & Registry: Docker + AWS ECR
Orchestration & Service Management: Kubernetes (K3s)

Next, let’s clone the application repository to your local machine.

GitHub - mahinshanazeer/docker-frontend-backend-db-to_do_app: Simple Application with Frontend + Backened + DB

git clone https://github.com/mahinshanazeer/docker-frontend-backend-db-to_do_app

Clone the github application

Once the repository is cloned, switch to the application directory and check for the Docker Compose file.

Directory structure

version: "3.8"
services:
  web:
    build:
      context: ./frontend
      args:
        REACT_APP_API_URL: ${REACT_APP_API_URL}
    depends_on:
      - api
    ports:
      - "3000:80"
    networks:
      - network-backend
    env_file:
      - ./frontend/.env

  api:
    build: ./backend
    depends_on:
      - mongo
    ports:
      - "3001:3001"
    networks: 
      - network-backend

  mongo:
    build: ./backend-mongo  
    image: docker-frontend-backend-db-mongo
    restart: always
    volumes: 
      - ./backend-mongo/data:/data/db
    environment: 
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: adminhackp2025
    networks: 
      - network-backend

networks:
  network-backend:

volumes: 
  mongodb_data:

In the Docker Compose file, you’ll see sections for web, api, and mongo. Let’s dive into each directory and review the Dockerfiles. The Docker Compose file builds the Docker images using the Dockerfiles located in their respective directories.


root@ip-172-31-22-24:/home/ubuntu/docker-frontend-backend-db-to_do_app/frontend# cd /home/ubuntu/docker-frontend-backend-db-to_do_app/frontend
root@ip-172-31-22-24:/home/ubuntu/docker-frontend-backend-db-to_do_app/frontend# cat Dockerfile 
# ---------- Build Stage ----------
FROM node:16-alpine AS build

WORKDIR /app

# Copy dependency files first
COPY package*.json ./

# Install dependencies
RUN npm install --legacy-peer-deps

# Copy rest of the app
COPY . .

# Build the React app
RUN npm run build

# ---------- Production Stage ----------
FROM nginx:alpine

# Copy custom nginx config if you have one
# COPY nginx.conf /etc/nginx/conf.d/default.conf

# Copy build output from build stage
COPY --from=build /app/build /usr/share/nginx/html

# Expose port 80
EXPOSE 80

# Start nginx
CMD ["nginx", "-g", "daemon off;"]

***

root@ip-172-31-22-24:/home/ubuntu/docker-frontend-backend-db-to_do_app/backend# cd /home/ubuntu/docker-frontend-backend-db-to_do_app/backend
root@ip-172-31-22-24:/home/ubuntu/docker-frontend-backend-db-to_do_app/backend# cat Dockerfile 
FROM node:10-alpine

WORKDIR /usr/src/app

COPY package*.json ./

RUN npm install

COPY . .

EXPOSE 3001

***

root@ip-172-31-22-24:/home/ubuntu/docker-frontend-backend-db-to_do_app/backend# cd /home/ubuntu/docker-frontend-backend-db-to_do_app/backend-mongo/
root@ip-172-31-22-24:/home/ubuntu/docker-frontend-backend-db-to_do_app/backend-mongo# cat Dockerfile 
FROM mongo:6.0
EXPOSE 27017

Open the .env file in the frontend directory and update the IP address to your EC2 public IP. This environment variable is used by the frontend to connect to the backend, which runs on port 3001.

vi /home/ubuntu/docker-frontend-backend-db-to_do_app/frontend/.env

#edit the IP address, I have updated my EC2 public IP
~~~
REACT_APP_API_URL=http://54.90.185.176:3001/
~~~

We can also cross-check the total number of APIs using the following commands:

grep -R "router." backend/ | grep "("
grep -R "app." backend/ | grep "("
grep -R "app." backend/ | grep "(" | wc -l
grep -R "router." backend/ | wc -l

Let’s test the application by spinning up the containers. Navigate back to the project’s root directory and run the Docker Compose command.

cd /home/ubuntu/docker-frontend-backend-db-to_do_app
docker compose up -d

Once you run the command, Docker will start building the images and spin up the containers as soon as the images are ready

building docker containers

Wait until you see the ‘built’ and ‘created’ messages. Once the containers are up and running, use docker ps -a to verify the status.

build completed and containers started.

docker ps -a

docker processes

Once the Docker containers are up and running, verify that the application is working as expected.

Once the Docker containers are up and running, verify that the application is working as expected. Open the server’s IP address on port 3000. You can confirm the mapped ports in the Docker Compose file or by checking the docker ps -a output. Here, port 3000 is for the frontend web app, port 3001 is for the backend, and MongoDB runs internally on port 27017 without public access. In this example, load the website by entering 54.90.185.176:3000 in your browser.

Application interface

If you’re using Chrome, right-click anywhere on the page and open Inspect > Network. Then click on Add Todo to verify that the list updates correctly, and the network console shows a 200 status response

checking the network

Application testing

Click on the buttons and try to add new file, and verify the status codes:

Testing

So far, everything looks good. Now, let’s proceed with the Kubernetes deployment. To configure resources in Kubernetes, we’ll need to create manifest files in YAML format. You can create these files as shown below.

mkdir /home/ubuntu/manifest
touch api-deployment.yaml api-service.yaml image_tag.txt mongo-secret.yaml mongo-service.yaml mongo-statefulset-pv-pvc.yaml web-deployment.yaml web-env-configmap.yaml web-service.yaml

Now edit each file and add the following contents:

api-deployment.yaml:

Defines how the backend API should run inside the cluster.

Creates 2 replicas of the API for reliability.

Uses environment variables from secrets for MongoDB authentication.

Ensures the API pods always restart if they fail.

👉 Importance: Provides scalability and fault tolerance for the backend service.

Rolling Update: Gradually replaces old pods with new ones. Uses fewer resources, minimal downtime if tuned, but users may hit bad pods if the new version is faulty.

👉 Rolling = efficient and native.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  labels:
    app: api
spec:
  replicas: 2
  selector:
    matchLabels:
      app: api
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 3
      maxUnavailable: 0
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
        - name: api
          image: 495549341534.dkr.ecr.us-east-1.amazonaws.com/hackp2025:api-20250907111542
          ports:
            - containerPort: 3001
          env:
            - name: MONGO_INITDB_ROOT_USERNAME
              valueFrom:
                secretKeyRef:
                  name: mongo-secret
                  key: username
            - name: MONGO_INITDB_ROOT_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: mongo-secret
                  key: password
      restartPolicy: Always

api-service.yaml

Exposes the API deployment to the outside world.

Type NodePort makes the service reachable via :31001.

Ensures frontend or external clients can communicate with the backend.

👉 Importance: Acts as a bridge between users/frontend and the backend API.

apiVersion: v1
kind: Service
metadata:
  name: api
  labels:
    app: api
spec:
  type: NodePort
  selector:
    app: api
  ports:
    - port: 3001 # internal cluster port
      targetPort: 3001 # container port
      nodePort: 31001 # external port on the node

mongo-secret.yaml

Stores sensitive information (username & password) in base64-encoded format.

Used by both the API and MongoDB.

Keeps credentials out of plain-text manifests.

👉 Importance: Secure way to handle database credentials.

apiVersion: v1
kind: Secret
metadata:
  name: mongo-secret
type: Opaque
data:
  # Base64 encoded values
  username: YWRtaW4= # "admin"
  password: YWRtaW5oYWNrcDIwMjU= # "adminhackp2025"

mongo-service.yaml

Defines the MongoDB service.

- ClusterIP: None makes it a headless service , required for StatefulSets.

Allows pods to connect to MongoDB by DNS (e.g., mongo-0.mongo).

👉 Importance: Provides stable networking for MongoDB StatefulSet pods.

apiVersion: v1
kind: Service
metadata:
  name: mongo
  labels:
    app: mongo
spec:
  ports:
    - port: 27017
      targetPort: 27017
  selector:
    app: mongo
  clusterIP: None # headless service for StatefulSet

mongo-statefulset-pv-pvc.yaml

Handles the database persistence and StatefulSet definition.

- PersistentVolume (PV): Reserves storage (5Gi).

- PersistentVolumeClaim (PVC): Ensures pods can claim storage.

- StatefulSet: Guarantees stable network identity and persistent storage for MongoDB.

👉 Importance: Ensures MongoDB data is preserved even if the pod restarts.

Blue/Green Deployment: Runs two environments (Blue = live, Green = new). Traffic is switched instantly once Green is ready. Near-zero downtime and easy rollback, but requires double resources and is more complex for stateful apps.

👉 Blue/Green = safer cutover, higher cost.

# PersistentVolume for Green MongoDB
apiVersion: v1
kind: PersistentVolume
metadata:
  name: mongo-green-pv
spec:
  capacity:
    storage: 5Gi
  accessModes:
    - ReadWriteOnce
  hostPath:
    path: /root/hackpproject/data-green # separate path for green
  persistentVolumeReclaimPolicy: Retain
  storageClassName: "" # Must match PVC in StatefulSet

---

# StatefulSet for Green MongoDB
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: mongo-green
  labels:
    app: mongo
    version: green
spec:
  serviceName: mongo # existing headless service
  replicas: 1
  selector:
    matchLabels:
      app: mongo
      version: green
  template:
    metadata:
      labels:
        app: mongo
        version: green
    spec:
      containers:
        - name: mongo
          image: 495549341534.dkr.ecr.us-east-1.amazonaws.com/hackp2025:db-20250907111542
          ports:
            - containerPort: 27017
          env:
            - name: MONGO_INITDB_ROOT_USERNAME
              valueFrom:
                secretKeyRef:
                  name: mongo-secret
                  key: username
            - name: MONGO_INITDB_ROOT_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: mongo-secret
                  key: password
          volumeMounts:
            - name: mongo-data
              mountPath: /data/db
  volumeClaimTemplates:
    - metadata:
        name: mongo-data
      spec:
        accessModes: ["ReadWriteOnce"]
        resources:
          requests:
            storage: 5Gi
        storageClassName: "" # binds to the pre-created PV

web-deployment.yaml

Defines how the frontend (React.js app) should run.

Runs 2 replicas for high availability.

Pulls API endpoint from ConfigMap.

Resource requests/limits ensure fair scheduling.

👉 Importance: Deploys the UI and links it to the backend API via config.

Rolling Update: Gradually replaces old pods with new ones. Uses fewer resources, minimal downtime if tuned, but users may hit bad pods if the new version is faulty.

👉 Rolling = efficient and native.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  labels:
    app: web
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 3         
      maxUnavailable: 0   
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: web
          image: 495549341534.dkr.ecr.us-east-1.amazonaws.com/hackp2025:web-20250907111542
          ports:
            - containerPort: 3000
              protocol: TCP
          env:
            - name: REACT_APP_API_URL
              valueFrom:
                configMapKeyRef:
                  name: web-env
                  key: REACT_APP_API_URL
          resources:
            requests:
              cpu: "200m"
              memory: "1024Mi"
            limits:
              cpu: "2"
              memory: "2Gi"
      restartPolicy: Always

web-env-configmap.yaml

Stores non-sensitive environment variables.

Defines the API endpoint for the frontend (REACT_APP_API_URL).

Can be updated easily without rebuilding Docker images.

👉 Importance: Provides flexibility to change configuration without redeploying code.

apiVersion: v1
kind: ConfigMap
metadata:
  name: web-env
  labels:
    app: web
data:
  REACT_APP_API_URL: http://98.86.216.31:31001

web-service.yaml

Exposes the frontend to users.

- Type NodePort makes it available externally at :32000.

Maps port 3000 (service) → port 80 (container).

👉 Importance: Allows end-users to access the web app from their browser.

apiVersion: v1
kind: Service
metadata:
  name: web
  labels:
    app: web
spec:
  type: NodePort
  selector:
    app: web # Must match Deployment labels
  ports:
    - name: http
      port: 3000 # Service port inside cluster
      targetPort: 80 # Container port
      nodePort: 32000 # External port accessible from outside

We have now moved all the manifest files to /root/hackpproject/manifestfiles.

Once the manifests are finalised, the next step is to create a repository in ECR to push the build artefact images.

Steps to Create an ECR Repository:

1.Log in to AWS Console → Go to the ECR service.

Create Repository

Click Create repository.

Select Private repository.

Enter repository names — prodimage. (In this case, we are creating a single repository for all those 3 images)

Leave others as default and click Create repository.

Authenticate Docker with ECR

Step 1: Finding the ECR

Step 2: Creating Repository

Step 3: onfiguring Repository

Once the registry is created, you can proceed with the CI/CD pipeline.

Reposiroty end point

Now, let’s create a GitHub Actions pipeline to deploy the code to the EC2 K3S cluster. The first step is to configure GitHub Actions with access to the repository, ECR, and the EC2 instance via SSH.

Navigate to the project directory and create a folder named ‘.github’. Inside this folder, create a file named ‘ci-cd.yml’.

mkdir .github
cd .github
touch ci-cd.yml
vi ci-cd.yml

The ci-cd.yml file is the core configuration file for GitHub Actions that defines your CI/CD pipeline. Now use the following script in that ci-cd.yml file:

name: CI/CD Pipeline

on:
  push:
    branches:
      - main

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    env:
      ECR_REGISTRY: ${{ secrets.ECR_REGISTRY }}

    steps:
      - name: Pulling the repository
        uses: actions/checkout@v3

      - name: Pre-Build Checks (optional)
        run: |
          echo "Checking Docker installation..."
          docker --version
          echo "Checking Docker Compose installation..."
          docker compose version

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2

      - name: Login to AWS ECR
        uses: aws-actions/amazon-ecr-login@v2
        env:
          AWS_REGION: ${{ secrets.AWS_REGION }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

      - name: Set Image Tag (Timestamp)
        id: set_image_tag
        run: |
          IMAGE_TAG=$(date +'%Y%m%d%H%M%S')
          echo "image_tag=$IMAGE_TAG" >> $GITHUB_OUTPUT
          echo "$IMAGE_TAG" > image_tag.txt
          echo "IMAGE_TAG=$(cat image_tag.txt)" >> $GITHUB_ENV
          cat image_tag.txt

      - name: Upload image_tag.txt to K3s server
        uses: appleboy/scp-action@v0.1.7
        with:
          host: ${{ secrets.EC2_HOST }}
          username: ${{ secrets.EC2_USER }}
          key: ${{ secrets.EC2_SSH_KEY }}
          port: 22
          source: image_tag.txt
          target: /root/hackpproject/manifestfiles



      - name: Clean up old ECR images
        continue-on-error: true
        env:
          AWS_REGION: ${{ secrets.AWS_REGION }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: |
            echo "Listing all images in ECR..."
            aws ecr list-images --repository-name hackp2025 --region $AWS_REGION \
              --query 'imageIds[*]' --output json > image_ids.json || echo "No images to delete"

            if [-s image_ids.json]; then
              echo "Deleting old images from ECR..."
              aws ecr batch-delete-image --repository-name hackp2025 --region $AWS_REGION \
                --image-ids file://image_ids.json
            else
              echo "No images found, skipping deletion."
            fi

      - name: Install Trivy
        run: |
          wget https://github.com/aquasecurity/trivy/releases/download/v0.18.3/trivy_0.18.3_Linux-64bit.deb
          sudo dpkg -i trivy_0.18.3_Linux-64bit.deb


      - name: Build and Push Docker Images
        run: |
          echo "Building Docker images..."
          docker compose -f docker-compose.yml build
          docker images

          echo "Tagging images with timestamp: $IMAGE_TAG"
          docker tag hackkptask1-api:latest $ECR_REGISTRY/hackp2025:api-$IMAGE_TAG
          trivy image $ECR_REGISTRY/hackp2025:api-$IMAGE_TAG || echo "⚠️ Vulnerabilities found in API image. Proceeding anyway."
          docker push $ECR_REGISTRY/hackp2025:api-$IMAGE_TAG

          docker tag hackkptask1-web:latest $ECR_REGISTRY/hackp2025:web-$IMAGE_TAG
          trivy image $ECR_REGISTRY/hackp2025:web-$IMAGE_TAG || echo "⚠️ Vulnerabilities found in Web image. Proceeding anyway."
          docker push $ECR_REGISTRY/hackp2025:web-$IMAGE_TAG

          docker tag docker-frontend-backend-db-mongo:latest $ECR_REGISTRY/hackp2025:db-$IMAGE_TAG
          trivy image $ECR_REGISTRY/hackp2025:db-$IMAGE_TAG || echo "⚠️ Vulnerabilities found in Mongo image. Proceeding anyway."
          docker push $ECR_REGISTRY/hackp2025:db-$IMAGE_TAG


      - name: Deploy to K3s via SSH
        uses: appleboy/ssh-action@v0.1.7
        with:
          host: ${{ secrets.EC2_HOST }}
          username: ${{ secrets.EC2_USER }}
          key: ${{ secrets.EC2_SSH_KEY }}
          port: 22
          script: |
            IMAGE_TAG=$(cat /root/hackpproject/manifestfiles/image_tag.txt)
            ECR_REGISTRY="495549341534.dkr.ecr.us-east-1.amazonaws.com"
            MANIFEST_DIR="/root/hackpproject/manifestfiles"

            echo "IMAGE_TAG=$IMAGE_TAG"
            echo "ECR_REGISTRY=$ECR_REGISTRY"

            # Replace only the part after "image: "
            sudo sed -i "s|image: .*hackp2025:web.*|image: ${ECR_REGISTRY}/hackp2025:web-${IMAGE_TAG}|g" $MANIFEST_DIR/web-deployment.yaml
            sudo sed -i "s|image: .*hackp2025:api.*|image: ${ECR_REGISTRY}/hackp2025:api-${IMAGE_TAG}|g" $MANIFEST_DIR/api-deployment.yaml
            sudo sed -i "s|image: .*hackp2025:db.*|image: ${ECR_REGISTRY}/hackp2025:db-${IMAGE_TAG}|g" $MANIFEST_DIR/mongo-statefulset-pv-pvc.yaml

            aws ecr get-login-password --region us-east-1 \
              | sudo docker login --username AWS --password-stdin 495549341534.dkr.ecr.us-east-1.amazonaws.com

            # Apply manifests
            sudo kubectl delete all --all -n hackpproject
            sudo kubectl apply -f $MANIFEST_DIR
            sudo kubectl rollout status deployment/web
            sudo kubectl rollout status deployment/api

            #push file to manifest repo
            cd $MANIFEST_DIR
            cd $MANIFEST_DIR
            # Configure git identity for commits
            git config user.name "hackp25project"
            git config user.email "github-push@hackp25"

            # Ensure we’re on main
            git checkout main

            # Fetch latest changes
            git pull --rebase origin main

            # Commit and push if changes exist
            if [-n "$(git status --porcelain)"]; then
                git add .
                git commit -m "Update manifests for image tag: ${ECR_REGISTRY}/hackp2025:web-${IMAGE_TAG}"
                git push origin main
            else
                echo "No changes to commit."
            fi

Now we need to configure the secrets. Follow the screenshots below:

Step 1: Configuring secrets

Step 2: Configuring secrets

Step 3: Adding Repository secret

Note: You can ignore the KUBECONFIG and GH_SSH_KEY secrets, as they are not required for this specific use case. For reference, please see the screenshot I created using ChatGPT, which outlines each secret, its purpose, and how to obtain it.

For more details on configuring and using the AWS CLI, you can refer to my previous blog. I’ll include the link below for your reference:

Configuring AWS CLI for Terraform / Script Automation

I have not included the SSH key generation and key management steps, as they are common knowledge. Including them would make the guide unnecessarily long. It is expected that users are familiar with configuring SSH keys; otherwise, I recommend reviewing Linux fundamentals before starting with Kubernetes.

Next, we need to authorise the EC2 instance to access ECR using the AWS CLI.

aws ecr get-login-password --region us-east-1 > ecr_pass
aws ecr get-login-password --region us-east-1 \
  | sudo docker login --username AWS --password-stdin 495549341534.dkr.ecr.us-east-1.amazonaws.com

Also, create a secret for MongoDB credentials. This command creates a Kubernetes Secret mongo-secret that securely stores the MongoDB username and password. Instead of hardcoding credentials in manifests, applications like the backend API or MongoDB deployment can reference this secret for authentication, ensuring better security and centralised management of sensitive data. We are using the secret in mongo-deploying yaml file, please refer to the manifest file on the top

kubectl create secret generic mongo-secret \
  --from-literal=username=admin \
  --from-literal=password=adminhackp2025

Now the configuration is completed, once you commit the changes and push to the github, the pipeline will start working:


git add .github/
git commit -m "CICD configuration updated"
git push origin main

#my remote is configured as origin and branch is main

Once pushed to remote, come back to github repository

Github Actions

Here, you can see some jobs marked with a red cross and others with a green tick. The red cross indicates failed jobs, while the green tick indicates successful ones.

Github Actions failure

Click on the job, then select option (4) to view the complete details. Troubleshooting should be performed based on the errors identified in the logs

Debugging

If you need to make changes to the ci-cd.yml file, follow the steps below and rerun all jobs. By default, the pipeline will automatically restart whenever you commit changes to the ci-cd.yml from the GitHub repository.

Editing CICD yml file

Once the CI/CD jobs execute successfully, you will see a green tick mark on the left.

Job successfull

Now, return to the server and run kubectl get all to verify the list of all deployed components.

kubectl get all

Instead of port 3000, the application is exposed on port 32000. Open the application URL http://98.86.216.31:32000/ and verify that it is working correctly, just as we did earlier with Docker Compose.

Demo Application loading fine

We successfully set up a CI/CD pipeline using GitHub Actions to deploy the application on an EC2-hosted K3S cluster. The workflow automated the build, scan, and push of Docker images to AWS ECR, followed by deployment to the cluster.

After verifying the deployments with kubectlWe confirmed the application is accessible via http://98.86.216.31:32000/ and is working as expected.

[Boost]

Mahinsha Nazeer — Sun, 07 Sep 2025 02:55:58 +0000

Mahinsha Nazeer

Jun 25 '25

Run AI Locally: Creating a Local AI Chat Assistant for Targeted Workflows

#llm #ollama #chatbotdevelopment #ai

Comments

10 min read

Step-by-Step Guide to Launching an EC2 Instance on AWS : For Beginners

Mahinsha Nazeer — Sun, 31 Aug 2025 06:31:48 +0000

Step-by-Step Guide to Launching an EC2 Instance on AWS: For Beginners

This guide is designed for beginners stepping into AWS. Amazon EC2 (Elastic Compute Cloud) is a virtual machine in the cloud, enabling you to launch servers and run your applications with ease. To set up an EC2 instance, you’ll need to configure a few essential parameters, which we’ll walk through step by step.

Getting started with cloud computing is easier than ever with AWS Free Tier. AWS offers a free tier program that allows beginners to explore many AWS services, including EC2, without incurring charges for up to 12 months. This is ideal for learning, experimenting, or running small-scale projects.

In this guide, we’ll walk you through launching your first EC2 instance — a virtual server in the cloud — using parameters and settings suitable for beginners. By the end of this tutorial, you’ll have a fully functional EC2 instance ready for deploying applications, all while staying within the free tier limits.

You can check out AWS Free Tier here:

Free Cloud Computing Services - AWS Free Tier

Start by logging in to your AWS Management Console. In the search bar at the top, type EC2 and select it from the results. This will take you to the EC2 Dashboard, where you can manage and launch your virtual servers.

AWS Console search bar

Once you are on the EC2 Dashboard, click on the ‘Launch Instance’ button. This will initiate the process of creating a new virtual server, guiding you through configuring instance details, selecting an Amazon Machine Image (AMI), choosing an instance type, and setting up security options.

Launching new EC2 instance

1. Names and tags:

Give a suitable name for your EC2 machine

2. Choose an Amazon Machine Image (AMI)

An AMI is a pre-configured template for your instance. Options include:

Amazon Linux — Lightweight and optimised for AWS.
Ubuntu, Red Hat, Windows Server — Depending on your application needs.
Custom AMIs — If you have a pre-configured image.
Choose the architecture (For beginners, 64-bit x86 is fine, which is there by default)

Configuration

3. Choose an Instance Type

This defines the compute resources for your server:

CPU, memory, storage, and network capacity.
Common types: t2.micro (free tier eligible), t3.medium, etc.
Choose based on your workload requirements.

4. Configure Instance Details

Key settings in this section:

Number of Instances — How many identical servers to launch at once. Default is 1.
Network & Subnet — Select your VPC and subnet.
Auto-assign Public IP — Useful if you need internet access.
IAM Role — Assign permissions for AWS services.
Monitoring & Shutdown Behaviour — Optional settings for CloudWatch and automatic stop/terminate actions.

5. Create or Select a Key Pair

In the Review and Launch step, you can select an existing key pair or create a new one. ( Easiest method for beginners)
If creating a new key pair:
Give it a descriptive name (e.g., WebServerKey).
Download the .pem file immediately—AWS will not allow downloading it later.

6. Add Storage

Define EBS volumes for your instance.
Configure size , volume type , and encryption.
You can add additional volumes if required.

7. Add Tags

Tags are key-value pairs to identify your instance:

Example: Key = Name, Value = WebServer1.
Tags make managing multiple instances easier.

8. Configure Security Group

Security groups act as a firewall for your instance.
Add rules for inbound traffic, e.g.:
SSH (22) — for Linux access.
HTTP (80) and HTTPS (443) — for web servers.
You can create a new security group or select an existing one.

9. Review and Launch

Verify all settings before launching.
Click Launch , and select or create a key pair for SSH access.
Download the key pair and store it securely — it’s required to connect to your instance.

Network and SSH configuration

Storage configuration

Final Step: Launch Your EC2 Instance

After reviewing all settings, configuring the SSH key , and ensuring your security groups are properly set:

Click the “Launch” button.
Your instance will start initialising. You can monitor its status in the EC2 Dashboard under Instances.
Once the instance state changes to “running” , note the public IP or DNS name — you will use this to connect via SSH.

Security Reminder:

Never share your .pem key file publicly.
Only allow SSH access from trusted IPs in your security group.

Now your EC2 instance is ready, and you can deploy applications or configure it as required.

Launching instance

Once your EC2 instance is in the “running” state, you can connect to it from your local machine using the SSH key you created:

Locate the Public IP

In the EC2 Dashboard, select your instance and copy its public IP address or public DNS name.

Set Permissions for Your Key

On Linux/macOS, run:
chmod 400 your-key.pem
This ensures the SSH key file is secure and usable.

Connect via SSH

Run the following command from your terminal:
ssh -i /path/to/your-key.pem ec2-user@
For Ubuntu AMIs , replace ec2-user with ubuntu.

Successful Connection

After connecting, you’ll see the command prompt of your EC2 instance, indicating you can now manage it remotely and deploy applications.

Raspberry Pi Homelab setup with Kubernetes

Mahinsha Nazeer — Sun, 31 Aug 2025 02:38:46 +0000

Mahinsha Nazeer

Jun 6 '25

Raspberry Pi K8S Cluster Setup for Home Lab with Cilium

#kubernetes #raspberrypi #docker #kubernetescluster

Comments

14 min read

Sending Email Notifications on SSH Login Events

Mahinsha Nazeer — Mon, 07 Jul 2025 12:10:48 +0000

Monitoring SSH logins is a simple yet powerful way to stay informed about access to your Linux server. Whether you’re managing production infrastructure or personal devices, receiving real-time email alerts for SSH logins can help you detect unauthorised access and maintain better operational visibility. In this guide, we’ll walk through configuring your server to automatically send email notifications whenever a user logs in via SSH, using native tools like Postfix and PAM.

For configuring Postfix to use Gmail as an SMTP relay, you may refer to the following blog. In this article, we’ll focus solely on setting up the script to monitor and send email alerts for SSH logins.

Configuring Postfix notification using Gmail SMTP server.

Let’s create a Bash script that automatically sends an email notification whenever a user accesses the server via SSH.

vi /usr/local/bin/ssh-login-alert.sh

#now add the following content to the file:
~~~
#!/bin/bash

HOSTNAME=$(hostname)
IP=${PAM_RHOST:-$(who | awk '/pts/{print $5}' | tr -d '()' | head -n1)}
USER=${PAM_USER:-$(whoami)}
TIME=$(date '+%Y-%m-%d %H:%M:%S')
echo -e "SSH Login Alert:\nUser: $USER\nIP: $IP\nTime: $TIME\nHost: $HOSTNAME" | mail -s "WARNING: SSH Login on $HOSTNAME from $IP" test@gmail.com
~~~

script

Ensure that you’ve correctly specified the email subject line and recipient address in the designated sections of the script before deploying it. Also, we need to provide executable permissions for the script:

chmod +x /usr/local/bin/ssh-login-alert.sh

Once the script is prepared and tested, the next step is to integrate it into the PAM configuration to trigger on SSH logins.

vim /etc/pam.d/sshd
#now add the following content on the top of sshd configuration inside pam.d

~~~
session optional pam_exec.so /usr/local/bin/ssh-login-alert.sh
~~~

pam.d configuration

With the script in place, simply log out and log back in via SSH to verify that the email notification is triggered as expected.