DEV Community: Sospeter Mong'are

Installing and Testing Docker on WSL with MobaXterm on Windows Os

Sospeter Mong'are — Tue, 16 Jun 2026 10:14:19 +0000

Introduction

If you are a developer on Windows who wants to use Docker without installing Docker Desktop, you are in the right place. In this guide, you will learn how to install Docker Engine inside WSL (Windows Subsystem for Linux) using MobaXterm, test it with a real Node.js application, and manage your containers like a pro — all from the command line.

By the end of this article, you will:

Understand what WSL and MobaXterm are and why they work great together
Have Docker Engine installed and running inside Ubuntu on WSL
Test Docker with the official hello-world image
Build and run a real Node.js web app inside a Docker container
Know how to start, stop, and clean up Docker containers

💡 Who is this guide for? Developers who are comfortable with the command line but are new to Docker on WSL. No prior Docker experience required.

1. What Are WSL and MobaXterm?

WSL — Windows Subsystem for Linux

WSL is a feature built into Windows 10 and 11 that lets you run a real Linux environment directly on your Windows machine — no virtual machine, no dual boot. You get a full Ubuntu terminal that shares your file system and network with Windows.

Think of WSL as a thin Linux layer that sits underneath your Windows desktop. It is fast, lightweight, and perfect for running developer tools like Docker, Node.js, Python, and more.

MobaXterm — A Better Terminal for WSL

MobaXterm is a powerful terminal application for Windows that includes built-in SSH, X11 forwarding, and — most importantly — direct access to your WSL sessions. It gives you a much better development experience than the default Windows Terminal for WSL work.

When you open a WSL tab in MobaXterm, you are working inside your Ubuntu environment. That is where all our Docker commands will run.

⚠️ Important Note About WSL and systemd: By default, WSL does not use systemd (the Linux service manager). This means sudo systemctl start docker may not work. Instead, we use sudo service docker start. This guide uses the correct command throughout.

2. Prerequisites

Before we begin, make sure you have the following:

Windows 10 (version 2004 or later) or Windows 11
WSL 2 installed with Ubuntu (Ubuntu 20.04 or 22.04 recommended)
MobaXterm installed — download free from mobaxterm.mobatek.net
A stable internet connection for downloading packages

To verify WSL is installed, open PowerShell and run:

wsl --list --verbose

You should see your Ubuntu distro listed with Version 2. If not, run wsl --set-version Ubuntu 2 to upgrade.

3. Opening Your WSL Session in MobaXterm

Launch MobaXterm and start a WSL session:

Open MobaXterm from your Windows Start menu
Click on Sessions → New Session
Select WSL from the session types
Choose your Ubuntu distribution from the dropdown
Click OK — you now have a Linux terminal open!

Your prompt should look something like this:

sospeter@DESKTOP-ABC123:~$

All commands in this guide are run inside this MobaXterm WSL terminal.

4. Installing Docker Engine on WSL

We will install Docker Engine using the official Docker apt repository. Follow each step carefully.

Step 1: Add Docker's Official GPG Key

First, update your package list and install the required dependencies:

sudo apt update
sudo apt install ca-certificates curl -y

Then create the directory for Docker's GPG key and download it:

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

Step 2: Add the Docker Repository

Now add Docker's official package repository to your Ubuntu apt sources:

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update

Step 3: Install Docker Packages

Install Docker Engine along with the CLI, containerd runtime, and the Compose plugin:

sudo apt install docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin -y

This may take a few minutes depending on your internet speed.

Step 4: Start Docker

In WSL, we start Docker using the service command:

sudo service docker start

To verify Docker is running:

sudo service docker status

You should see output that includes Docker is running.

🔁 Auto-start tip: Add sudo service docker start > /dev/null 2>&1 to your ~/.bashrc file so Docker starts automatically every time you open MobaXterm.

Step 5: Add Your User to the Docker Group (Optional but Recommended)

By default, Docker commands require sudo. To run Docker without it:

sudo usermod -aG docker $USER

# Apply the group change (or close and reopen your terminal)
newgrp docker

5. Verifying Docker with hello-world

Let us confirm Docker is working with the official test image:

sudo docker run hello-world

You should see output like this:

Hello from Docker!
This message shows that your installation appears to be working correctly.

To generate this message, Docker took the following steps:
 1. The Docker client contacted the Docker daemon.
 2. The Docker daemon pulled the "hello-world" image from Docker Hub.
 3. The Docker daemon created a new container from that image.
 4. The Docker daemon streamed that output to the Docker client.

If you see that — congratulations! 🎉 Docker is installed and working correctly on your WSL.

6. Building and Running a Real Node.js App

The hello-world image is a good sanity check, but let us go further and run a real web application inside Docker.

Step 1: Create a Project Folder

mkdir ~/docker-test && cd ~/docker-test

Step 2: Create the Application File

Create a file called app.js:

nano app.js

Paste the following code:

const http = require('http');

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello from Docker on WSL! 🐳\n');
});

server.listen(3000, () => {
  console.log('Server running on port 3000');
});

Save and exit with Ctrl + X, then Y, then Enter.

Step 3: Create the Dockerfile

nano Dockerfile

Paste the following:

# Use the official Node.js Alpine image (small and fast)
FROM node:18-alpine

# Set the working directory inside the container
WORKDIR /app

# Copy our application file into the container
COPY app.js .

# Tell Docker our app listens on port 3000
EXPOSE 3000

# Command to run when the container starts
CMD ["node", "app.js"]

Step 4: Build the Docker Image

sudo docker build -t wsl-test-app .

The -t flag gives the image a name (tag). The . tells Docker to look for the Dockerfile in the current directory.

Step 5: Run the Container

sudo docker run -d -p 3000:3000 --name my-test-app wsl-test-app

What each flag does:

Flag	Meaning
`-d`	Run in the background (detached mode)
`-p 3000:3000`	Map port 3000 on your host to port 3000 in the container
`--name my-test-app`	Give the container a friendly name
`wsl-test-app`	The image name we just built

Step 6: Test the Running App

curl http://localhost:3000

Expected output:

Hello from Docker on WSL! 🐳

You can also open http://localhost:3000 in your Windows browser and see the same result!

7. Managing Your Containers

Command	What It Does
`docker ps`	List all running containers
`docker ps -a`	List all containers including stopped ones
`docker logs my-test-app`	View logs from a container
`docker stop my-test-app`	Stop a running container
`docker start my-test-app`	Start a stopped container
`docker rm my-test-app`	Delete a container
`docker images`	List all images on your machine
`docker rmi wsl-test-app`	Delete an image
`docker exec -it <name> sh`	Open a shell inside a running container

Cleaning Up Your Test App

# Stop the running container
sudo docker stop my-test-app

# Remove the container
sudo docker rm my-test-app

# (Optional) Remove the image
sudo docker rmi wsl-test-app

Stopping Docker Engine

sudo service docker stop

8. Troubleshooting Common Issues

Cannot connect to the Docker daemon
Run sudo service docker start to start the Docker service.

Permission denied running Docker
Either prefix commands with sudo, or add yourself to the docker group (Section 4, Step 5).

Port already in use
Change the port mapping to -p 3001:3000 and visit localhost:3001 instead.

WSL using too much RAM
Create C:\Users\YourName\.wslconfig with:

[wsl2]
memory=4GB
processors=2

9. Quick Reference Cheat Sheet

# Docker service
sudo service docker start        # Start Docker
sudo service docker stop         # Stop Docker
sudo service docker status       # Check status

# Images
sudo docker build -t name .      # Build image from Dockerfile
sudo docker images               # List images
sudo docker rmi image-name       # Delete image

# Containers
sudo docker run -d -p 3000:3000 --name app image   # Run container
sudo docker ps                   # See running containers
sudo docker ps -a                # See all containers
sudo docker logs app             # View logs
sudo docker stop app             # Stop container
sudo docker rm app               # Remove container
sudo docker exec -it app sh      # Shell into container

Conclusion

You have successfully:

✅ Installed Docker Engine on WSL using the official apt repository
✅ Started and verified Docker is running with the hello-world image
✅ Built and deployed a real Node.js application inside a Docker container
✅ Learned how to manage, stop, and clean up containers

Docker on WSL is a powerful setup that gives you all the benefits of Linux containers without leaving your Windows machine. As you grow more comfortable, explore Docker Compose for multi-container applications, volume mounts for persistent data, and container networking for microservices architectures.

Happy coding and containerizing! 🐳

Found this helpful? Share it with fellow developers. Follow me on X for more backend, API, and DevOps content.

How to Install dbt with SQL Server on WSL (Windows Subsystem for Linux)

Sospeter Mong'are — Wed, 10 Jun 2026 13:31:41 +0000

Note: A beginner-friendly, step-by-step guide for data engineers on Windows

What is dbt?

dbt (data build tool) is an open-source transformation tool that lets you write SQL-based data models, test them, and document them — all from the command line. It sits on top of your database and transforms raw data into analytics-ready tables and views.

If you're working with data pipelines, ELT workflows, or data warehouses, dbt is a tool you'll encounter regularly.

Prerequisites

Before starting, make sure you have:

WSL 2 with Ubuntu 24.04 installed on your Windows machine
Python 3.12 available (python3 --version to check)
A virtual environment already created and activated (see the Airflow installation guide if you need to set one up)
Access to a SQL Server instance — remote, Azure SQL, or local

Step 1: Activate Your Virtual Environment

Always work inside a virtual environment to keep your dependencies isolated:

source ~/your-project-folder/env/bin/activate

Your prompt should show (env) at the beginning confirming it's active.

Step 2: Install dbt with the SQL Server Adapter

The SQL Server adapter for dbt is maintained as dbt-sqlserver. Installing it also pulls in dbt-core automatically:

pip install dbt-sqlserver

Verify the installation:

dbt --version

Confirm the adapter is installed:

pip show dbt-sqlserver

You should see:

Name: dbt-sqlserver
Version: 1.x.x
Summary: A Microsoft SQL Server adapter plugin for dbt
Requires: dbt-adapters, dbt-common, dbt-core, pyodbc

Note: dbt --version may not always list plugins explicitly in some environments — pip show dbt-sqlserver is the reliable way to confirm the adapter is present.

Step 3: Install the Microsoft ODBC Driver for SQL Server

dbt-sqlserver uses pyodbc under the hood, which requires Microsoft's ODBC driver to physically connect to SQL Server. Run the following commands one at a time:

Command 1 — Download and register Microsoft's GPG signing key:

curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg

Command 2 — Add Microsoft's package repository:

curl https://packages.microsoft.com/config/ubuntu/24.04/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list

Command 3 — Refresh apt to pick up the new repository:

sudo apt update

Command 4 — Install the ODBC driver:

sudo ACCEPT_EULA=Y apt install -y msodbcsql18 unixodbc-dev

Verify the driver is registered:

odbcinst -q -d -n "ODBC Driver 18 for SQL Server"

You should see:

[ODBC Driver 18 for SQL Server]
Description=Microsoft ODBC Driver 18 for SQL Server
Driver=/opt/microsoft/msodbcsql18/lib64/libmsodbcsql-18.6.so.2.1
UsageCount=1

This confirms the driver is installed and ready.

Step 4: Clone Your dbt Project Repository

If you have an existing dbt project in a Git repository, clone it:

cd ~
git clone <YOUR_REPO_URL_HERE>
cd <cloned-folder-name>

If the repository is private, authenticate using a GitHub Personal Access Token (PAT):

git clone https://<your-github-username>:<your-PAT>@github.com/org/repo.git

Step 5: Install dbt Project Dependencies

Most dbt projects have a packages.yml file that lists external dbt packages. Install them with:

dbt deps

Step 6: Configure Your `profiles.yml`

dbt connects to your database using a profiles.yml file. By default it lives at ~/.dbt/profiles.yml, but some projects include it locally inside the repo folder.

Create the default profiles directory and file:

mkdir -p ~/.dbt
nano ~/.dbt/profiles.yml

Paste the following template and fill in your actual credentials:

your_project_name:
  target: dev
  outputs:
    dev:
      type: sqlserver
      driver: "ODBC Driver 18 for SQL Server"
      server: your_server_address        # e.g. 192.168.1.10 or myserver.database.windows.net
      port: 1433
      database: your_database_name
      schema: your_schema_name
      user: your_username
      password: your_password
      encrypt: true
      trust_cert: true                   # set to false in production with a valid SSL cert
      login_timeout: 60                  # seconds before connection attempt times out

    prod:
      type: sqlserver
      driver: "ODBC Driver 18 for SQL Server"
      server: your_prod_server_address
      port: 1433
      database: your_prod_database
      schema: your_prod_schema
      user: your_prod_username
      password: your_prod_password
      encrypt: true
      trust_cert: true
      login_timeout: 60

Important: The top-level key (your_project_name) must exactly match the name: field inside the project's dbt_project.yml file.

Save and exit (Ctrl+O, Enter, Ctrl+X).

Step 7: Test the Connection

Run dbt's built-in connection test:

dbt debug --target dev

A successful output looks like:

All checks passed!

If you see a Login timeout expired error, check:

Your server address is correct and reachable
Port 1433 is open on the server's firewall
Your credentials are correct in profiles.yml
You're on the right network (VPN may be required for remote servers)

Test if the server port is reachable from WSL:

nc -zv your_server_address 1433

Step 8: Run Your dbt Models

Once the connection test passes, run a specific model:

dbt run --select model_name --target dev

Run all models:

dbt run --target dev

Run models against production:

dbt run --select model_name --target prod

List all available models in the project:

dbt ls --target dev

Other Database Adapters

dbt supports many databases. Here are the install commands for the most common ones:

Database	Install Command
SQL Server / Azure SQL	`pip install dbt-sqlserver`
PostgreSQL	`pip install dbt-postgres`
BigQuery	`pip install dbt-bigquery`
Snowflake	`pip install dbt-snowflake`
MySQL	`pip install dbt-mysql`
Redshift	`pip install dbt-redshift`
DuckDB	`pip install dbt-duckdb`
Databricks	`pip install dbt-databricks`
Trino	`pip install dbt-trino`

Each adapter has its own profiles.yml format. The type: field changes per adapter. For example:

PostgreSQL:

my_project:
  target: dev
  outputs:
    dev:
      type: postgres
      host: localhost
      port: 5432
      database: my_database
      schema: public
      user: my_user
      password: my_password

BigQuery:

my_project:
  target: dev
  outputs:
    dev:
      type: bigquery
      method: service-account
      project: my_gcp_project
      dataset: my_dataset
      keyfile: /path/to/service-account.json

Snowflake:

my_project:
  target: dev
  outputs:
    dev:
      type: snowflake
      account: my_account
      user: my_user
      password: my_password
      database: my_database
      schema: my_schema
      warehouse: my_warehouse
      role: my_role

Quick Reference: Most Used dbt Commands

dbt debug              # Test database connection
dbt deps               # Install project package dependencies
dbt run                # Run all models
dbt run --select model_name         # Run a specific model
dbt run --target prod               # Run against a specific target
dbt test                            # Run data tests
dbt ls                              # List all models
dbt compile                         # Compile SQL without running
dbt docs generate && dbt docs serve # Generate and view documentation

Summary of Installation Commands

# Activate virtual environment
source ~/your-project/env/bin/activate

# Install dbt with SQL Server adapter
pip install dbt-sqlserver

# Install ODBC Driver (run one at a time)
curl -fsSL https://packages.microsoft.com/keys/microsoft.asc | sudo gpg --dearmor -o /usr/share/keyrings/microsoft-prod.gpg
curl https://packages.microsoft.com/config/ubuntu/24.04/prod.list | sudo tee /etc/apt/sources.list.d/mssql-release.list
sudo apt update
sudo ACCEPT_EULA=Y apt install -y msodbcsql18 unixodbc-dev

# Verify ODBC driver
odbcinst -q -d -n "ODBC Driver 18 for SQL Server"

# Clone project repo
git clone <REPO_URL>
cd <project-folder>

# Install dbt packages
dbt deps

# Configure connection
mkdir -p ~/.dbt && nano ~/.dbt/profiles.yml

# Test connection
dbt debug --target dev

# Run models
dbt run --target dev

Written based on a real dbt + SQL Server setup on WSL2 Ubuntu 24.04 (Noble) with ODBC Driver 18.

How to Install Apache Airflow 2.9.1 on WSL (Windows Subsystem for Linux)

Sospeter Mong'are — Tue, 09 Jun 2026 13:48:58 +0000

Note: A beginner-friendly, step-by-step guide for developers on Windows

What is Apache Airflow?

Apache Airflow is an open-source platform used to programmatically author, schedule, and monitor workflows. It's widely used in data engineering, MLOps, and backend automation pipelines. If you're building ETL pipelines, running scheduled tasks, or orchestrating complex workflows, Airflow is a tool you'll likely encounter.

Prerequisites

Before we begin, make sure you have the following in place:

1. Windows Subsystem for Linux (WSL) installed

You need WSL 2 with Ubuntu 24.04 (Noble) installed on your Windows machine. If you haven't set it up yet, open PowerShell as Administrator and run:

wsl --install

Restart your machine when prompted, then launch Ubuntu from the Start menu.

2. MobiXterm or Windows Terminal (optional but recommended)

MobiXterm or Windows Terminal gives you a better terminal experience for working inside WSL. Either works fine.

3. Basic familiarity with the Linux terminal

You don't need to be a Linux expert, but knowing how to navigate directories (cd, ls) and run commands will help.

Step 1: Update Your System

Open your WSL terminal and run:

sudo apt update && sudo apt upgrade -y

This ensures your package lists and installed packages are up to date.

Step 2: Install Python 3 and Check the Version

Ubuntu 24.04 ships with Python 3.12 by default. Verify it's available:

python3 --version

You should see something like Python 3.12.x. If not, install it:

sudo apt install python3 python3-dev -y

Step 3: Install `python3.12-venv`

Airflow should always be installed inside a virtual environment to avoid dependency conflicts with your system Python.

First, install the venv module:

sudo apt install python3.12-venv -y

Troubleshooting - Network/download errors?
On some networks, apt may time out trying to download packages. If you see a Connection timed out or Connection failed error for python3-pip-whl, use wget to download it manually:
wget -O python3-pip-whl.deb "https://launchpadlibrarian.net/753358547/python3-pip-whl_24.0+dfsg-1ubuntu1.3_all.deb"
sudo dpkg -i python3-pip-whl.deb
sudo dpkg --configure -a
sudo apt --fix-broken install
Then retry the venv install:
sudo apt install python3.12-venv -y

Step 4: Create a Project Directory and Virtual Environment

Create a dedicated folder for your Airflow installation:

mkdir ~/airflow-2.9.1
cd ~/airflow-2.9.1

Now create a virtual environment inside it:

python3 -m venv venv

Activate the virtual environment:

source venv/bin/activate

Your terminal prompt should now show (venv) at the beginning, like:

(venv) user@DESKTOP-XXXX:~/airflow-2.9.1$

This confirms you are inside the virtual environment.

Step 5: Upgrade pip

Before installing Airflow, upgrade pip to the latest version:

pip install --upgrade pip

Step 6: Install Apache Airflow 2.9.1

Install Airflow using the official constraints file. This is important - Airflow has many dependencies, and the constraints file ensures compatible versions are installed together without conflicts.

pip install apache-airflow==2.9.1 \
  --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-2.9.1/constraints-3.12.txt"

This may take a few minutes. Once complete, verify the installation:

airflow version

You should see:

2.9.1

Step 7: Initialize the Airflow Database

Airflow uses a metadata database to track DAG runs, tasks, logs, and more. Initialize it with:

airflow db init

This creates the default SQLite database and the ~/airflow directory with all necessary config files.

Step 8: Create an Admin User

Create your first admin user to log into the Airflow web UI:

airflow users create \
  --username admin \
  --firstname YourFirstName \
  --lastname YourLastName \
  --role Admin \
  --email your@email.com

You will be prompted to set a password. Enter and confirm it.

Step 9: Start the Airflow Web Server and Scheduler

Airflow requires two processes running simultaneously - the webserver and the scheduler. Open two separate WSL terminal tabs or windows for this.

Terminal 1 - Start the webserver:

cd ~/airflow-2.9.1
source venv/bin/activate
airflow webserver --port 8080

Terminal 2 - Start the scheduler:

cd ~/airflow-2.9.1
source venv/bin/activate
airflow scheduler

Step 10: Access the Airflow UI

Open your browser and navigate to:

http://localhost:8080

You will see the Airflow login page. Enter the username and password you created in Step 8.

You should now be inside the Airflow Dashboard - ready to create and manage your DAGs!

Quick Reference: Starting Airflow After a Reboot

Every time you restart your machine and want to use Airflow, run these commands in two terminals:

# Both terminals: navigate and activate venv
cd ~/airflow-2.9.1
source venv/bin/activate

# Terminal 1
airflow webserver --port 8080

# Terminal 2
airflow scheduler

Summary of All Commands

# Update system
sudo apt update && sudo apt upgrade -y

# Install Python venv
sudo apt install python3.12-venv -y

# Create project directory and venv
mkdir ~/airflow-2.9.1 && cd ~/airflow-2.9.1
python3 -m venv venv
source venv/bin/activate

# Install Airflow
pip install --upgrade pip
pip install apache-airflow==2.9.1 \
  --constraint "https://raw.githubusercontent.com/apache/airflow/constraints-2.9.1/constraints-3.12.txt"

# Verify
airflow version

# Initialize DB and create user
airflow db init
airflow users create --username admin --firstname YourFirstName \
  --lastname YourLastName --role Admin --email your@email.com

# Start services
airflow webserver --port 8080   # Terminal 1
airflow scheduler               # Terminal 2

What's Next?

Now that Airflow is running, here are some things to explore next:

Write your first DAG - create a Python file in ~/airflow/dags/ to define a workflow
Explore Airflow Operators - BashOperator, PythonOperator, and more
Set up PostgreSQL as the Airflow backend (recommended for production over SQLite)
Use the CeleryExecutor for parallel task execution

How to Install `python-dotenv` in Python

Sospeter Mong'are — Tue, 02 Jun 2026 04:31:13 +0000

Environment variables are an essential part of modern software development. They allow developers to store sensitive information such as API keys, database credentials, and secret tokens outside the source code. In Python, one of the most popular libraries for managing environment variables is python-dotenv.

This article will guide you through installing and using python-dotenv in your Python projects.

What is `python-dotenv`?

python-dotenv is a Python package that reads key-value pairs from a .env file and loads them into environment variables. This helps keep sensitive configuration data separate from your codebase.

Benefits of Using `python-dotenv`

Keeps secrets out of source code
Simplifies configuration management
Makes applications easier to deploy across different environments
Works seamlessly with frameworks like Django, Flask, and FastAPI

Step 1: Install `python-dotenv`

Open your terminal or command prompt and run:

pip install python-dotenv

If you're using Python 3 and your system requires pip3, use:

pip3 install python-dotenv

To verify the installation:

pip show python-dotenv

You should see package information similar to:

Name: python-dotenv
Version: 1.x.x
Summary: Read key-value pairs from a .env file and set them as environment variables

Step 2: Create a `.env` File

In the root directory of your project, create a file named:

.env

Add your environment variables:

API_KEY=your_api_key_here
DATABASE_URL=mysql://user:password@localhost/dbname
DEBUG=True
SECRET_KEY=my_secret_key

Step 3: Load Environment Variables

Create a Python file and load the variables using load_dotenv().

from dotenv import load_dotenv
import os

# Load variables from .env file
load_dotenv()

api_key = os.getenv("API_KEY")
debug = os.getenv("DEBUG")

print(api_key)
print(debug)

When you run the script, the values from the .env file will be loaded into your application.

Step 4: Using `python-dotenv` in Django

Install the package:

pip install python-dotenv

In your settings.py file:

from dotenv import load_dotenv
import os

load_dotenv()

SECRET_KEY = os.getenv("SECRET_KEY")
DEBUG = os.getenv("DEBUG") == "True"

Your .env file:

SECRET_KEY=django-secret-key
DEBUG=True

This prevents sensitive settings from being hardcoded into your project.

Step 5: Using `python-dotenv` in Flask

from dotenv import load_dotenv
import os
from flask import Flask

load_dotenv()

app = Flask(__name__)

app.config["SECRET_KEY"] = os.getenv("SECRET_KEY")

@app.route("/")
def home():
    return "Hello World"

if __name__ == "__main__":
    app.run()

Step 6: Keep Your `.env` File Out of Git

Never commit your .env file to version control.

Add it to .gitignore:

.env

This ensures sensitive information remains private.

Common Environment Variables

Example .env file:

DATABASE_HOST=localhost
DATABASE_PORT=3306
DATABASE_NAME=mydb
DATABASE_USER=root
DATABASE_PASSWORD=password

OPENAI_API_KEY=your_openai_key
WHATSAPP_TOKEN=your_whatsapp_token

DEBUG=True

Access them in Python:

import os

host = os.getenv("DATABASE_HOST")
port = os.getenv("DATABASE_PORT")

Troubleshooting

1. ModuleNotFoundError

Error:

ModuleNotFoundError: No module named 'dotenv'

Solution:

pip install python-dotenv

Ensure you're installing it in the same virtual environment you're running your application from.

2. Variables Returning `None`

Check that:

The .env file exists in the project root.
load_dotenv() is called before os.getenv().
Variable names match exactly.

Example:

load_dotenv()

api_key = os.getenv("API_KEY")

Best Practices

Never commit .env files to Git repositories.
Use meaningful variable names.
Store all secrets in environment variables.
Use separate .env files for development, staging, and production.
Validate required environment variables when your application starts.

Example:

import os
from dotenv import load_dotenv

load_dotenv()

required_vars = ["API_KEY", "DATABASE_URL"]

for var in required_vars:
    if not os.getenv(var):
        raise ValueError(f"Missing environment variable: {var}")

Conclusion

The python-dotenv package provides a simple and secure way to manage configuration settings in Python applications. By storing sensitive information in a .env file and loading it with load_dotenv(), you can keep your code clean, secure, and easy to maintain. Whether you're building a Django application, Flask API, FastAPI service, or automation script, python-dotenv is a valuable tool that every Python developer should know.

AI Workflows vs AI Agents: Understanding the Difference and When to Use Each

Sospeter Mong'are — Fri, 29 May 2026 09:27:54 +0000

Artificial intelligence systems today are often described as either workflows or agents. While they may seem similar because both use AI models, they are fundamentally different in how they operate, how much autonomy they have, and what problems they are best suited for.

Understanding this distinction is important for anyone building automation systems, backend services, or AI-powered products.

What is an AI Workflow?

An AI workflow is a structured, predefined sequence of steps where AI is used at specific points in the process.

In a workflow, a human designs the entire process in advance. The AI does not decide what to do next. It simply performs tasks within the steps that have already been defined.

Key idea

The process is fixed. Only the execution uses AI.

Example of an AI workflow

A simple customer support automation might look like this:

A user submits a support ticket
AI summarizes the message
AI classifies the urgency level
The ticket is routed to the correct department
The customer receives an automated response

Each step is predefined. The system always follows the same path.

Tools commonly used for AI workflows

AI workflows are usually built using automation platforms such as:

These tools allow you to visually design step-by-step automations and insert AI models where needed.

Characteristics of AI workflows

AI workflows typically have the following traits:

Step-by-step execution
Predictable outcomes
Mostly deterministic logic
Easier debugging and maintenance
Faster to build and deploy
Best suited for repetitive business processes
Limited decision-making ability

Real-world use cases

AI workflows are widely used in production systems such as:

Email summarization systems
Auto-posting content to social media
Invoice processing pipelines
CRM data updates
WhatsApp auto-replies
Lead qualification systems

They are especially strong in business environments where reliability and consistency matter more than flexibility.

What is an AI Agent?

An AI agent is a more autonomous system that can make decisions about how to complete a task.

Instead of following a fixed sequence of steps, an AI agent works toward a goal and determines the best actions to take dynamically.

You provide:

A goal or objective
Access to tools or APIs
Optional memory or context

The agent then figures out how to achieve the goal.

Key idea

The process is not fully predefined. The AI decides the steps.

Example of an AI agent

If you give an agent a task like:

“Find 10 Kenyan fintech APIs, summarize them, and prepare documentation drafts.”

The agent may:

Search the web for fintech APIs
Open documentation pages
Extract endpoints and features
Summarize each API
Organize results into structured notes
Save or export the information
Retry failed steps if needed
Ask clarifying questions if something is unclear

The important part is that the exact path is not prewritten.

Frameworks used for building AI agents

Modern AI agents are built using specialized frameworks such as:

These frameworks allow models to reason, use tools, maintain memory, and coordinate multi-step tasks.

Characteristics of AI agents

AI agents typically have these properties:

Goal-oriented behavior
Higher autonomy
Dynamic decision-making
Ability to use multiple tools
Reasoning over steps
Memory or context awareness
More complex to design and control
Flexible problem-solving capability

Real-world use cases

AI agents are used for more advanced and adaptive tasks such as:

Research assistants that gather and summarize information
Coding agents that write and debug software
Sales assistants that qualify and follow up on leads
Data analysis assistants that explore datasets dynamically
Personal productivity assistants that manage tasks and schedules

AI Workflow vs AI Agent: The Core Difference

Aspect	AI Workflow	AI Agent
Process structure	Fixed	Flexible
Decision-making	Human-defined	AI-driven
Predictability	High	Medium to low
Autonomy	Low	High
Complexity	Easier	More complex
Debugging	Simple	Harder
Best use case	Repetitive automation	Complex problem solving

Simple Analogy

A simple way to understand the difference:

AI workflow is like a GPS with a fixed route already planned
AI agent is like a driver who decides routes dynamically based on traffic, obstacles, and conditions

Example Comparison

AI Workflow Example

Using n8n:

A Gmail trigger receives a message
AI summarizes the email
The summary is saved to Notion
A Slack notification is sent

Everything is predefined and consistent.

AI Agent Example

An AI assistant system may:

Read incoming emails
Decide which ones are important
Draft responses automatically
Schedule meetings
Search the web for missing context
Follow up on unanswered messages

The system decides what to do at each step.

Important Reality in Today’s AI Landscape

Although the term “AI agent” is widely used, many real-world systems marketed as agents are actually advanced AI workflows with some dynamic decision-making added.

Fully autonomous agents are still challenging because they are:

Hard to control reliably
Expensive to run at scale
Difficult to debug when things go wrong
Sometimes unpredictable in production systems

Because of this, many companies prefer a hybrid approach.

The Best Practical Approach Today

In real-world systems, the most effective architecture is often a combination of both:

AI workflows provide structure and reliability
AI agents provide intelligence and flexibility inside parts of the workflow

This hybrid model gives the best balance between control and adaptability.

Final Takeaway

AI workflows are structured and predictable systems enhanced with AI
AI agents are goal-driven systems that can decide their own steps
Workflows are best for automation and business processes
Agents are best for complex, adaptive problem-solving

In practice, modern AI products rarely choose one or the other exclusively. They blend both to build systems that are reliable, intelligent, and scalable.

Understanding MCP (Model Context Protocol): The Future of AI Integrations

Sospeter Mong'are — Wed, 20 May 2026 11:53:28 +0000

Artificial Intelligence is rapidly moving beyond simple chatbots. Today, AI systems are becoming assistants that can search databases, read files, interact with APIs, automate workflows, and even operate business systems.

One of the technologies making this possible is MCP, short for Model Context Protocol.

If you are hearing about MCP for the first time, this article will help you understand what it is, why it matters, how it works, and why developers are paying close attention to it.

What is MCP?

MCP (Model Context Protocol) is a standardized way for AI models to connect with tools, applications, databases, APIs, and external systems.

In simple terms:

MCP acts like a bridge between AI and software systems.

Without MCP, AI assistants mostly rely on text conversations. They can answer questions, but they cannot naturally interact with real-world systems unless developers build custom integrations for every single tool.

MCP changes this by introducing a common communication standard.

Why MCP Matters

Modern AI systems are becoming more capable every day, but intelligence alone is not enough.

For AI to become truly useful in businesses and applications, it needs access to:

Databases
APIs
File systems
Cloud platforms
CRMs
Developer tools
Internal company systems

The challenge is that every system works differently.

One application may use REST APIs.
Another may use GraphQL.
Another may require SQL queries.
Another may use completely custom workflows.

Without standardization, developers must create separate integrations for every tool.

MCP solves this problem.

A Simple Analogy

Think of MCP as a universal adapter for AI.

Different software systems are like different power sockets around the world.

Without an adapter:

nothing connects properly.

MCP provides a standardized way for AI systems to communicate with all these tools using one common structure.

Another good analogy is:

APIs are individual roads
MCP is the traffic system organizing everything

How MCP Works

At a high level, MCP involves four main components:

The User
The AI Assistant
The MCP Client/Server
External Tools or Systems

The flow looks like this:

User
  ↓
AI Assistant
  ↓
MCP Client
  ↓
MCP Server
  ↓
Tools / APIs / Databases

Step-by-Step Example

Imagine a user asks:

“Show me all failed payments from today and summarize the issue.”

Here is what happens behind the scenes.

Step 1: AI Understands the Request

The AI realizes it needs payment transaction data.

Step 2: MCP Discovers Available Tools

The MCP server may expose tools such as:

[
  "search_transactions",
  "get_failed_payments",
  "generate_report"
]

The AI can automatically discover what tools are available.

Step 3: AI Calls a Tool

The AI sends a structured request such as:

{
  "tool": "get_failed_payments",
  "date": "2026-05-20"
}

Step 4: MCP Server Executes the Request

The MCP server:

connects to databases
fetches data
processes results
returns structured information

Step 5: AI Responds Naturally

The AI finally responds:

“There were 37 failed transactions today. Most failures were caused by insufficient balance.”

The user gets a natural conversation experience while MCP handles the technical communication in the background.

MCP vs APIs

Many beginners confuse MCP with APIs, but they are different.

APIs

APIs are direct communication channels between software systems.

Example:

Application A → API → Application B

Each API has:

different endpoints
different authentication
different request formats
different documentation

Developers must learn every API separately.

MCP

MCP standardizes how AI interacts with these systems.

Instead of teaching AI how every system works individually, MCP provides one common structure.

You can think of it this way:

APIs	MCP
Software-to-software communication	AI-to-software communication
Every integration is custom	Standardized integration approach
Focused on applications	Focused on AI agents and assistants
Different structures everywhere	Common protocol structure

Why Developers Are Excited About MCP

MCP opens the door to a new generation of AI-powered systems.

Instead of building simple chatbots, developers can build:

AI agents
AI copilots
Intelligent automation systems
Operational assistants
AI support systems
AI developer tools
Enterprise AI platforms

This is one reason why AI engineering is evolving so quickly.

Real-World Use Cases of MCP

1. Customer Support AI

An AI assistant can:

check customer accounts
search transactions
issue refunds
generate reports

all through MCP-connected systems.

2. Developer Assistants

AI coding assistants can:

read repositories
create pull requests
analyze logs
interact with CI/CD pipelines

through MCP integrations.

3. Business Automation

Companies can build AI systems that:

automate workflows
generate analytics
manage operations
monitor systems
coordinate teams

using MCP servers connected to internal tools.

4. Banking and Fintech

A banking MCP server could expose:

account lookup
transaction history
payment reversal
fraud detection tools
reporting systems

allowing AI systems to assist operations securely.

MCP and AI Agents

MCP is becoming extremely important in the world of AI agents.

AI agents are systems that can:

reason
make decisions
use tools
perform tasks
execute workflows

For agents to work effectively, they need reliable access to tools and data.

MCP provides that infrastructure.

This is why MCP is frequently mentioned alongside topics like:

RAG (Retrieval-Augmented Generation)
AI workflows
orchestration
agent memory
multi-agent systems

MCP for Backend Developers

If you are a backend developer working with frameworks like Django, Node.js, Laravel, or Spring Boot, MCP creates exciting opportunities.

For example, your backend can expose MCP-compatible tools such as:

transaction search
analytics generation
user management
reporting systems
workflow automation

This allows AI systems to interact with your platform intelligently.

Traditional architecture:

Frontend → Backend API → Database

AI-enabled architecture with MCP:

AI Assistant → MCP Server → Backend → Database

This is one reason many developers believe MCP will become a major part of modern software architecture.

The Future of MCP

As AI systems continue to evolve, standardization becomes increasingly important.

MCP could become a foundational layer for:

enterprise AI systems
AI operating systems
AI workplace assistants
autonomous software agents
intelligent business platforms

Just as APIs transformed web development, MCP may transform AI integration.

Final Thoughts

MCP is not replacing APIs.

Instead, it builds on top of existing systems and makes them easier for AI to understand and use.

The key idea is simple:

APIs help software communicate with software.

MCP helps AI communicate with software intelligently and consistently.

As AI continues moving from conversation to action, MCP is becoming one of the most important concepts for developers, businesses, and AI engineers to understand.

The Stages of AI in Software Engineering - And Where We Are Today

Sospeter Mong'are — Wed, 15 Apr 2026 11:36:28 +0000

Software engineering hasn’t just evolved. It has accelerated.

In the last couple of years, the way we build software has changed more than most people realize. Many developers are still operating in older patterns, while the ground beneath them has already shifted.

To understand where we are going, it helps to break things down into stages.

Stage 1: Ask AI

This is where it started for most people.

AI was used like a smarter search engine. You would:

paste an error
ask for a function
get a quick fix

Nothing about your workflow really changed.

You were still:

thinking through the problem
designing the solution
writing most of the code

AI was just helping with syntax and speed.

Stage 2: AI in Your Editor

Then AI moved closer.

Instead of switching tabs, it started living inside your editor. It could:

autocomplete your thoughts
suggest full functions
understand your code context

This felt powerful. And it was.

But the control didn’t change.

You were still driving.
AI was just helping you move faster.

Stage 3: Describe the Problem

This is where the real shift began.

Instead of asking:
“How do I build this?”

You started asking:
“Here’s what I want. Build it.”

The focus moved away from code and into clarity.

You describe:

the feature
the behavior
the expected outcome

AI handles the implementation.

At this stage, your value is no longer how fast you can type.
It’s how clearly you can think.

Stage 4: Manage AI Agents (Where We Are Now)

We are no longer just working with a single AI.

We are starting to work with multiple agents at once.

Instead of writing code line by line, you:

assign tasks
run workflows in parallel
review outputs

One agent can build a feature.
Another writes tests.
Another refactors existing code.

This no longer feels like coding.

It feels like managing a team.

And that changes everything.

Stage 5: Autonomous AI Systems (What’s Next)

The next step is already taking shape.

Agents won’t just work in parallel.
They will work together.

A single request could trigger a full pipeline:

build
test
validate
deploy

With little to no human interruption.

Your role becomes:

defining requirements
setting boundaries
reviewing final outcomes

You are no longer in the loop at every step.
You step in when it matters.

Stage 6: Self-Evolving Systems (The Future)

This is where things get even more interesting.

Software will not just run.
It will improve itself.

Systems will:

learn from user behavior
adjust features automatically
optimize performance continuously
refine their own logic over time

Software becomes something closer to a living system.

Not static. Not finished. Always adapting.

What This Means for Engineers

The role of a software engineer is not disappearing.
But it is changing.

Less focus on:

writing every line of code

More focus on:

defining problems clearly
making architectural decisions
validating outcomes

The bottleneck is no longer coding speed.

It is thinking.

The Real Shift

AI didn’t remove the need for engineers.

It exposed something deeper:

If you cannot clearly explain what you want to build,
AI will build the wrong thing faster.

But if you can think clearly,
AI becomes a multiplier.

Final Thought

The best engineers in this new world will not be the fastest coders.

They will be the clearest thinkers.

Because in the end, AI executes.

Humans decide what is worth building.

Understanding SOLID Principles in Object-Oriented Programming

Sospeter Mong'are — Mon, 13 Apr 2026 14:08:02 +0000

When building software, especially in object-oriented languages like Java, writing code that works is only part of the job. The real challenge is writing code that is easy to maintain, extend, and scale over time. This is where SOLID principles come in.

SOLID is not about how many classes you should have. Instead, it is a set of five design principles that guide how you structure and organize your classes for better software quality.

What is SOLID?

SOLID is an acronym representing five key principles of object-oriented design:

Single Responsibility Principle
Open/Closed Principle
Liskov Substitution Principle
Interface Segregation Principle
Dependency Inversion Principle

These principles help developers reduce complexity, improve readability, and make systems easier to modify without breaking existing functionality.

1. Single Responsibility Principle (SRP)

A class should have only one reason to change, meaning it should handle only one responsibility.

For example, a class that manages user data should not also handle logging or database connections. Separating responsibilities ensures that changes in one area do not affect unrelated parts of the system.

This makes your code easier to debug and maintain.

2. Open/Closed Principle (OCP)

Software entities such as classes should be open for extension but closed for modification.

This means you should be able to add new functionality without changing existing code. Instead of modifying a class directly, you extend it or use abstractions.

This reduces the risk of introducing bugs into already tested code.

3. Liskov Substitution Principle (LSP)

Objects of a subclass should be able to replace objects of the parent class without affecting the correctness of the program.

In simple terms, if a class inherits from another, it should behave in a way that does not break expectations. If replacing a parent class with a child class causes errors, then the design violates this principle.

4. Interface Segregation Principle (ISP)

Clients should not be forced to depend on interfaces they do not use.

Instead of creating large, general-purpose interfaces, it is better to create smaller, more specific ones. This ensures that classes only implement what they actually need.

This leads to cleaner and more focused code.

5. Dependency Inversion Principle (DIP)

High-level modules should not depend on low-level modules. Both should depend on abstractions.

This means you should rely on interfaces or abstract classes rather than concrete implementations. It reduces tight coupling between components and makes your system more flexible.

Why SOLID Matters

Applying SOLID principles leads to:

Better code organization
Easier testing and debugging
Improved scalability
Reduced risk when making changes
More reusable components

Final Thoughts

SOLID principles do not tell you how many classes to create. Instead, they guide how those classes should behave and interact with each other.

By applying these principles consistently, you move from writing code that simply works to building systems that are robust, maintainable, and ready to grow with changing requirements.

Understanding AI Agents: Autonomous vs Semi-Autonomous Systems

Sospeter Mong'are — Wed, 08 Apr 2026 12:21:22 +0000

As Artificial Intelligence continues to evolve, the concept of an "agent" has become central to how intelligent systems are designed and deployed. From chatbots and virtual assistants to automated financial systems and robotics, agents are the building blocks behind many modern applications. To fully understand how these systems operate, it is important to start with a clear definition of what an AI agent is, and then explore the difference between autonomous and semi-autonomous agents.

What Is an AI Agent

An AI agent is a software system or program that is designed to perceive its environment, make decisions, and take actions in order to achieve a specific goal.

At its core, an agent has three main components:

Perception: The ability to gather information from its environment. This could be user input, API responses, sensor data, or database queries.
Decision-making: The logic or intelligence that allows the agent to analyze information and determine what action to take.
Action: The execution of tasks, such as sending a message, updating a database, calling an API, or triggering another process.

A simple example is a chatbot. It receives a message from a user, processes the input, decides on a response, and sends a reply. More advanced agents can handle complex workflows, learn from data, and adapt over time.

Agents can also be goal-driven, meaning they are designed not just to respond to inputs, but to actively pursue objectives. For instance, an agent might be tasked with increasing sales conversions, monitoring system health, or automating customer engagement.

Autonomous AI Agents

Autonomous AI agents are systems that operate independently with minimal or no human intervention. Once they are given a goal or set of objectives, they can plan, make decisions, and execute actions on their own.

Characteristics of Autonomous Agents

Autonomous agents are defined by a high level of independence. They can:

Make decisions without human approval
Adapt to changing environments
Continuously operate without supervision
Optimize their actions based on feedback and data

These agents often rely on advanced techniques such as machine learning, reinforcement learning, and real-time data processing to improve their performance over time.

Examples of Autonomous Agents

Automated trading systems that analyze markets and execute trades instantly
Self-driving vehicles that navigate roads and respond to traffic conditions
Network monitoring systems that detect and respond to threats without human input

Advantages

High efficiency and speed
Ability to operate at scale
Reduced need for human labor in repetitive tasks

Challenges

Higher risk due to lack of human oversight
Difficulty in handling unexpected or ambiguous situations
Ethical and accountability concerns

Because of these challenges, fully autonomous systems are often deployed in controlled environments or where the risks are manageable.

Semi-Autonomous AI Agents

Semi-autonomous AI agents operate with a combination of machine intelligence and human involvement. They can perform many tasks independently, but they require human input, validation, or approval at key stages.

Characteristics of Semi-Autonomous Agents

These agents are designed to assist rather than fully replace human decision-making. They typically:

Provide recommendations or suggestions
Execute tasks up to a certain point
Require human confirmation for critical actions
Work collaboratively with users

Examples of Semi-Autonomous Agents

Code assistants that suggest implementations while developers decide what to use
Customer support systems that draft replies for human agents to review
Financial systems that flag suspicious transactions for manual verification

Advantages

Lower risk due to human oversight
Better handling of complex or sensitive scenarios
Increased trust and accountability

Challenges

Slower than fully autonomous systems due to human involvement
Requires well-designed interaction between human and machine
May not scale as easily in high-demand environments

Semi-autonomous systems are widely used in real-world applications because they strike a balance between efficiency and control.

Key Differences Between Autonomous and Semi-Autonomous Agents

The distinction between these two types of agents lies primarily in control, decision-making, and risk management.

Aspect	Autonomous Agents	Semi-Autonomous Agents
Human involvement	Minimal or none	Required at key points
Decision-making	Fully independent	Shared with humans
Speed	High	Moderate
Risk level	Higher	Lower
Use cases	Automation at scale	Human-assisted workflows

When to Use Each Type

Choosing between autonomous and semi-autonomous agents depends on the context in which the system will operate.

Use Autonomous Agents When:

Tasks are repetitive and well-defined
Decisions are based on clear data patterns
Speed and scalability are critical
The risk of errors is low or manageable

Use Semi-Autonomous Agents When:

Decisions require human judgment or context
The system operates in sensitive domains such as finance or healthcare
Accountability and trust are important
Errors could have significant consequences

Practical Perspective for Developers

For developers building systems such as APIs, backend services, or automation platforms, understanding this distinction is crucial.

Autonomous agents are ideal for background processes such as data synchronization, automated notifications, or system monitoring. These tasks benefit from speed and do not usually require human validation.

Semi-autonomous agents are better suited for user-facing features such as messaging platforms, financial transactions, or content generation tools. In these cases, allowing a human to review or approve actions helps prevent costly mistakes.

For example, in a WhatsApp API platform, an autonomous agent might automatically send scheduled messages or respond to frequently asked questions. A semi-autonomous agent, on the other hand, might generate message drafts that a user reviews before sending to customers.

Conclusion

AI agents are powerful tools that enable systems to act intelligently and achieve goals with minimal manual effort. The distinction between autonomous and semi-autonomous agents lies in how much control is given to the system versus the human.

Autonomous agents focus on independence, efficiency, and scalability, while semi-autonomous agents emphasize collaboration, oversight, and safety. Understanding when and how to use each type is essential for building reliable, effective, and responsible AI-driven systems.

Testing M-PESA STK Push Callbacks Locally Without Exposing Your Server

Sospeter Mong'are — Wed, 18 Mar 2026 13:02:35 +0000

If you've ever built an M-PESA STK Push integration, you've probably hit this wall: M-PESA needs a publicly accessible callback URL to send payment confirmations, but your app is running on localhost. How do you test this without deploying every single time?

In this guide I'll show you a simple approach using webhook.site and a small Node.js poller script that automatically forwards M-PESA callbacks to your local machine.

What We're Building

When a user completes an STK Push payment, M-PESA sends a POST request to your callback URL with the payment result. Normally that URL has to be publicly accessible. Since localhost isn't public, we'll use webhook.site as a middleman - it catches the callback from M-PESA, and our poller script picks it up and forwards it to our local app automatically.

The flow looks like this:

M-PESA → webhook.site → our poller script → localhost

Prerequisites

Node.js installed on your machine
Your Laravel app running locally
An M-PESA Daraja API account (sandbox or production)
Basic understanding of how STK Push works

Step 1 - Get a webhook.site URL

Go to webhook.site and you'll immediately get a unique URL that looks like this:

https://webhook.site/f5d500b7-1196-42ef-8ecd-c906e49f7df36

The part after the last slash is your token. Copy it - you'll need it shortly. Keep this tab open so you can see incoming requests.

Step 2 - Store the Callback URL in Your .env

Instead of hardcoding the webhook.site URL in your code, store it in your .env file so you can swap it out easily without touching any code:

MPESA_CALLBACK_URL=https://webhook.site/f5d500b7-1196-42ef-8ecd-c906e49f7df36

On production you simply leave this variable out and it falls back to your real callback URL automatically.

Step 3 - Update Your ProcessController

In your M-PESA ProcessController where you build the STK Push request, find the CallBackURL line and update it like this:

"CallBackURL" => env('MPESA_CALLBACK_URL') ?: route('ipn.MPesa'),

What this does is simple. If MPESA_CALLBACK_URL is set in your .env it uses that. If it's not set, it falls back to your real route. This means locally it points to webhook.site, and on production it uses your actual callback route - no code changes needed when you deploy.

Step 4 - Create the Poller Script

This is the magic piece. Create a file called forwarder.js anywhere on your machine - I put mine in the project root. Paste this in:

const WEBHOOK_TOKEN = 'f5d500b7-1196-42ef-8ecd-c906e49f7df36'; // your token here
const LOCAL_URL = 'http://localhost:8000/ipn/mpesa';
const POLL_INTERVAL = 5000; // check every 5 seconds

let lastSeenId = null;

async function poll() {
    try {
        const res = await fetch(`https://webhook.site/token/${WEBHOOK_TOKEN}/requests?sorting=newest&per_page=1`);
        const data = await res.json();

        if (!data.data || data.data.length === 0) return;

        const latest = data.data[0];

        if (latest.uuid === lastSeenId) return; // already processed this one

        lastSeenId = latest.uuid;

        const body = latest.content;
        console.log('New callback received! Forwarding to local app...');
        console.log(body);

        const forward = await fetch(LOCAL_URL, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: body
        });

        console.log('Done. Local app responded with status:', forward.status);

    } catch (err) {
        console.error('Error:', err.message);
    }
}

setInterval(poll, POLL_INTERVAL);
console.log('Watching webhook.site for incoming callbacks...');

Replace the WEBHOOK_TOKEN value with your own token from Step 1. The LOCAL_URL should match whatever route your app uses for the M-PESA IPN.

Step 5 - Run Everything

You'll need two terminals open.

Terminal 1 - start your Laravel app:

php artisan serve

Terminal 2 - start the poller:

node forwarder.js

You should see this message in Terminal 2:

Watching webhook.site for incoming callbacks...

Step 6 - Trigger a Test Payment

Go through your app's deposit flow and trigger an STK Push. Enter your phone number and hit pay. You'll get the prompt on your phone.

Once you complete the payment, here's what happens automatically:

M-PESA sends the callback to webhook.site
Your poller picks it up within 5 seconds
It forwards the full payload to your local app
Your local app processes it and updates the database

You'll see something like this in Terminal 2:

New callback received! Forwarding to local app...
{"Body":{"stkCallback":{"ResultCode":0,"CheckoutRequestID":"ws_CO_xxxxx",...}}}
Done. Local app responded with status: 200

And your database gets updated just like it would in production.

Why Not Just Use ngrok?

Ngrok is the most common answer to this problem and it works well. However if you're running a licensed script, adding a new public URL can trigger a second domain detection and invalidate your license. The webhook.site approach avoids this completely since your app never gets a new public URL - only the callback endpoint changes temporarily, and only in your local .env.

Cleaning Up After Testing

When you're done testing, remove MPESA_CALLBACK_URL from your .env or comment it out:

# MPESA_CALLBACK_URL=https://webhook.site/f5d500b7-1196-42ef-8ecd-c906e49f7df36

Your app will fall back to the real route automatically. Stop the forwarder.js script and you're done. Nothing was changed in your codebase, nothing gets pushed to production.

Summary

The whole setup takes about 5 minutes and gives you a proper local testing loop for M-PESA callbacks without ngrok, without deploying, and without touching your production environment. The poller script is lightweight, requires no dependencies beyond Node.js, and you can reuse the same approach for any other payment gateway callback - just change the LOCAL_URL to point to the right IPN route.

How to Run Multiple PHP Versions on Windows and Switch Easily

Sospeter Mong'are — Sun, 15 Mar 2026 12:45:08 +0000

When working on modern PHP projects like those built with Laravel, you will eventually run into version conflicts.

One project may require PHP 8.3, while another older project may still run on PHP 8.1 or 8.2. If your system only has one PHP version installed, you will constantly run into errors like:

Composer detected issues in your platform:
Your Composer dependencies require a PHP version ">= 8.3.0".
You are running 8.2.12.

Instead of reinstalling PHP every time you switch projects, the better solution is to install multiple PHP versions and switch between them instantly.

One of the easiest ways to achieve this on Windows is by using Scoop, a lightweight package manager designed for developers.

Below is a simple and clean setup.

1. Install Scoop

Open PowerShell and run:

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex

Confirm installation:

scoop --version

Scoop installs tools into your user directory and avoids the common permission problems that occur with traditional installers.

2. Add the Versions Bucket

Scoop organizes packages using "buckets". To install multiple PHP versions, you need the versions bucket.

scoop bucket add versions

This bucket contains packages like:

php81
php82
php83

3. Install Multiple PHP Versions

You can now install any PHP version you need.

Example:

scoop install php82
scoop install php83

Check installed packages:

scoop list

At this point both PHP versions exist on your system, but only one will be active at a time.

4. Switch Between PHP Versions

To switch to PHP 8.3:

scoop reset php83

To switch to PHP 8.2:

scoop reset php82

Verify the active version:

php -v

This instantly updates your terminal environment.

5. Running Your Laravel Project

Once the correct version is active, you can start your project normally:

php artisan serve

If the project requires PHP 8.3, switching to php83 will resolve the platform check error.

Why This Approach Is Powerful

Modern development environments rarely use a single runtime version.

You may have projects such as:

Legacy project running PHP 8.1
Production system using PHP 8.2
New Laravel 11 applications requiring PHP 8.3

Using Scoop allows you to move between these environments instantly without reinstalling anything.

Bonus: Install Other Developer Tools

Scoop can also install common development tools:

scoop install composer
scoop install nodejs
scoop install git

This creates a clean development environment that is easy to maintain and update.

Final Thoughts

Managing multiple PHP versions used to be complicated on Windows. With Scoop, the process becomes simple and developer friendly.

Instead of fighting your environment, you can focus on building applications and switching versions only when necessary.

For backend developers working with frameworks like Laravel, this setup saves time and prevents version related errors during development.

M-PESA DARAJA API - C2B Integration Guide

Sospeter Mong'are — Fri, 13 Mar 2026 09:42:47 +0000

Introduction

If you are building a web or mobile app that needs to receive payments from M-PESA customers in Kenya, the Safaricom Daraja API is the tool you need. This guide will walk you through everything from scratch no prior API experience required.

By the end of this guide, you will understand:

What the C2B API is and how it works
How to set up and test it in the sandbox using Postman
What ValidationURL and ConfirmationURL do
How to take your integration live

What is C2B?

C2B stands for Customer to Business. It refers to the flow of money from an individual customer to your business. When a customer pays your Paybill or Till number via M-PESA, that is a C2B transaction.

The C2B API allows your application to receive real-time notifications every time a payment comes in, so you can automate things like:

Marking an order as paid
Sending a payment receipt to the customer
Updating your accounting system automatically

What is Daraja?

Daraja (which means "bridge" in Swahili) is Safaricom's developer portal that gives you access to the M-PESA API. It provides a sandbox (testing) environment where you can simulate payments without using real money, and a production environment for real transactions.

Portal URL: https://developer.safaricom.co.ke

PART ONE: SANDBOX TESTING

Before using real money, Daraja gives you a sandbox environment to safely test your integration. This is where you should always start.

STEP 1 - Create a Daraja Account & App

Set up your developer profile

Go to https://developer.safaricom.co.ke and click Sign Up
Fill in your details and verify your email address
Once logged in, click "My Apps" in the top navigation menu
Click "Create Sandbox App" - give it any name (e.g. "MyShopC2B")
Under the products section, check "M-Pesa Sandbox" to enable sandbox APIs
Click "Create App"

Your app will now appear in the "My Apps" section. Click on it and you will see two important values:

Key	Description
Consumer Key	Acts like your app's username for the API
Consumer Secret	Acts like your app's password for the API

💾 Save These! Copy your Consumer Key and Consumer Secret somewhere safe. You will need them for every API call.

STEP 2 - Get an Access Token

Authenticate before making any API call

Every single API request to Daraja requires an access token. Think of it like a temporary password that proves your identity. It expires after 1 hour and you need to generate a new one.

In Postman:

Method: GET
URL: https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials

Go to the Authorization tab in Postman:

Auth Type: Basic Auth
Username: paste your Consumer Key
Password: paste your Consumer Secret

Click Send. You should get a response like this:

{
  "access_token": "SGWcJPtNtYNPGm1DqBNqZZZZZZ",
  "expires_in": "3599"
}

📋 Copy It! Copy the access_token value. You will paste it in the Authorization header of every request below.

STEP 3 - Understanding Your Callback URLs

The heart of how C2B notifications work

Before registering your URLs, it is important to understand what each one does. When a customer makes a payment, Safaricom contacts your server at two different points in the payment flow:

📱 Customer Pays  →  🔍 ValidationURL  →  ✅ ConfirmationURL
  (Sends money)      ("Should I allow    ("Payment done,
                          this?")          record it!")

ValidationURL - "Should I allow this payment?"

This is called before the payment is processed. Safaricom sends you the payment details and waits for your response. You can accept or reject the payment based on your own business logic - for example, checking if the account number the customer entered actually exists in your system.

You respond with one of the following:

// Accept the payment
{ "ResultCode": "0", "ResultDesc": "Accepted" }

// Reject the payment
{ "ResultCode": "C2B00012", "ResultDesc": "Rejected" }

⚠️ Note: ValidationURL is optional. If you set ResponseType to "Completed" when registering, Safaricom skips validation and auto-accepts all payments. This is recommended for beginners.
Validation URL is the URL that receives the validation request from API upon payment submission. The validation URL is only called if external validation on the registered short code is enabled.
(By default, External Validation is disabled)

ConfirmationURL - "Payment went through, save the details"

This is called after the payment has been successfully processed. At this point, you cannot reject the payment - it has already gone through. This is where your app should record the transaction, update a database, send a receipt, or trigger any other business logic.

Feature	ValidationURL	ConfirmationURL
When called	BEFORE payment is processed	AFTER payment is processed
Purpose	Accept or reject the payment	Record and act on the payment
Your response matters?	YES - can block the payment	NO - informational only
Required?	Optional	Yes, always required

🏪 Real-world analogy: Think of it like a supermarket checkout. The ValidationURL is the cashier checking if your loyalty card is valid before ringing up. The ConfirmationURL is the receipt printer - it just records that the sale happened.

STEP 4 - Get a Free Callback URL for Testing

Use webhook.site to capture callbacks

Your ValidationURL and ConfirmationURL must be publicly accessible HTTPS endpoints. For sandbox testing, you do not need a real server - you can use a free tool called webhook.site.

Go to https://webhook.site in your browser
You will instantly get a unique URL like: https://webhook.site/abc-123-xyz
Copy that URL - you will use it as both your ValidationURL and ConfirmationURL for testing
Leave the webhook.site tab open. Callbacks from Safaricom will appear here in real time

🚫 URL Rules: Never use words like "MPesa", "M-Pesa", or "Safaricom" in your URLs - the system will block them. Also, localhost URLs will not work. Always use a proper HTTPS URL.

STEP 5 - Register Your Callback URLs

Tell Safaricom where to send payment notifications

Now you will call the Register URL API to link your callback URLs to your Paybill shortcode.

In Postman:

Method: POST
URL: https://sandbox.safaricom.co.ke/mpesa/c2b/v1/registerurl

Headers tab - add these two headers:

Header Key	Header Value
Authorization	`Bearer YOUR_ACCESS_TOKEN` (paste the token from Step 2)
Content-Type	`application/json`

Body tab - select "raw" and "JSON", then paste:

{
  "ShortCode": "600584",
  "ResponseType": "Completed", // Either Cancelled or Completed
  "ConfirmationURL": "https://webhook.site/your-unique-url",
  "ValidationURL": "https://webhook.site/your-unique-url"
}

Field	Explanation
ShortCode	The sandbox test Paybill number (600584 is the default sandbox shortcode)
ResponseType	"Completed" means skip validation and auto-accept all payments
ConfirmationURL	Your webhook.site URL - where Safaricom sends payment confirmations
ValidationURL	Your webhook.site URL - where Safaricom asks for approval (optional here)

A successful response looks like:

{
  "OriginatorCoversationID": "...",
  "ResponseCode": "0",
  "ResponseDescription": "success"
}

STEP 6 - Simulate a C2B Payment

Pretend a customer is paying you

Now for the fun part - you will simulate a customer sending money to your Paybill. Safaricom provides a test phone number you can use.

In Postman:

Method: POST
URL: https://sandbox.safaricom.co.ke/mpesa/c2b/v1/simulate

Use the same Authorization header as before, then paste this JSON body:

{
  "ShortCode": "600584",
  "CommandID": "CustomerPayBillOnline",
  "Amount": "100",
  "Msisdn": "254708374149",
  "BillRefNumber": "INV001"
}

Field	Explanation
ShortCode	Your sandbox Paybill number
CommandID	Use `"CustomerPayBillOnline"` for Paybill, or `"CustomerBuyGoodsOnline"` for Till
Amount	The amount the simulated customer is paying (in KES)
Msisdn	The test customer phone number - always use `254708374149` in sandbox
BillRefNumber	The account reference - e.g. an invoice number or order ID

STEP 7 - Check Your Callback

See what your app would receive

After sending the simulation request, go to your webhook.site tab. Within a few seconds, you should see a POST request arrive. This is exactly the payload your real server would receive when a customer pays.

It will look something like this:

{
            "TransactionType": "Pay Bill",
            "TransID": "UCB030CBG1",
            "TransTime": "20260311161727",
            "TransAmount": "1.00",
            "BusinessShortCode": "600991",
            "BillRefNumber": "account001",
            "InvoiceNumber": "",
            "OrgAccountBalance": "4635316.60",
            "ThirdPartyTransID": "",
            "MSISDN": "bbff37cea44ac0b2d964ee0dfb8d2df8513dc7ba1b36129a929fc3fbd6dd4af4",
            "FirstName": "John"
}

Field	Value	Explanation
`TransactionType`	`Pay Bill`	The type of transaction. Will be "Pay Bill" for Paybill or "Buy Goods" for Till numbers
`TransID`	`UCB030CBG1`	Unique M-PESA transaction ID. Use this as your reference to avoid processing the same payment twice
`TransTime`	`20260311161727`	Timestamp of the transaction in `YYYYMMDDHHmmss` format. This one means 11 March 2026 at 16:17:27
`TransAmount`	`1.00`	The amount the customer paid in KES
`BusinessShortCode`	`600991`	Your Paybill or Till number that received the payment
`BillRefNumber`	`account001`	The account number the customer entered when paying. Use this to identify which customer or order the payment belongs to
`InvoiceNumber`	(empty)	Optional invoice number. Usually empty for most C2B transactions
`OrgAccountBalance`	`4635316.60`	Your Paybill account balance after this transaction was processed
`ThirdPartyTransID`	(empty)	Used in some integrations for a third-party reference. Usually empty
`MSISDN`	`bbff37c...`	The customer's phone number. In sandbox it is returned as a hashed/masked value for privacy.
`FirstName`	`John`	The first name of the customer as registered on M-PESA

💡 Tip: The three most important fields to save in your database are TransID (to prevent duplicate processing), BillRefNumber (to identify the customer/order), and TransAmount (to confirm the correct amount was paid).

In a real application, you would read this JSON payload and use the TransAmount, BillRefNumber, and MSISDN fields to update your database and send a receipt to the customer.

⚠️ Sandbox Note: Sandbox callbacks can sometimes be unreliable. If your webhook.site does not receive anything after 30 seconds, try the simulation again. This is a known sandbox issue.

Full C2B Flow Recap

Step	Action	What Happens
1	Get Token	You authenticate with your Consumer Key & Secret and receive a temporary access token
2	Register URLs	You tell Safaricom where to send payment notifications
3	Customer Pays	A real or simulated customer sends money to your Paybill or Till number
4	Validation	Safaricom hits your ValidationURL asking "should I accept this?" (optional)
5	Confirmation	Safaricom hits your ConfirmationURL with the full payment details
6	Your App Acts	Your server reads the payload and updates the database, sends a receipt, etc.

PART TWO: GOING LIVE

Once your sandbox integration is working correctly, you are ready to go live and process real M-PESA transactions.

Prerequisites Before Going Live

Make sure you have all of the following before applying for live credentials:

A working sandbox integration - all steps above tested and confirmed working
A registered and verified Paybill or Till Number from Safaricom
An active Safaricom G2 Business Admin account (used to verify your shortcode)
A real publicly accessible HTTPS server URL (not localhost, not webhook.site) for your callback URLs
Company documentation: Certificate of incorporation, KRA PIN, and directors' IDs (for businesses)

🏢 Get a Paybill First: To get a Paybill number, visit a Safaricom shop with your company registration documents. For a Till number, you can apply via the Safaricom self-onboarding portal. Processing takes 24–72 hours.

Step 1 - Register on the Safaricom G2 Portal

The G2 portal (https://org.ke.mpesa.com) is Safaricom's business management platform. You need an account here so Daraja can verify you own the Paybill or Till number you want to use.

Send an email to M-PESABusiness@safaricom.co.ke requesting a Business Admin account
Attach required documents: company registration certificate, KRA PIN, directors' IDs, and a signed board resolution
Safaricom will create your G2 account and send login credentials
Log in, change your password, and create an "assistant role" user - these credentials will be used in the next step

Step 2 - Confirm Your Sandbox Integration is Solid

Before applying to go live, make sure all of the following are working in sandbox:

Access token generation is working
URL registration returns a success response
Simulated payments are triggering callbacks to your server
Your server is responding with the correct 200 OK responses
Your database or backend is correctly parsing and saving the callback payload

Step 3 - Click "Go Live" on the Daraja Portal

Log into https://developer.safaricom.co.ke
Go to "My Apps" and open your app
Click the "Go Live" button
Select "Verification by Shortcode" as the method
Enter your Paybill/Till shortcode and your G2 assistant user credentials
Select the API products you need (e.g. C2B)
Upload your test cases - a document showing what you tested and the results
Submit your request

⏱️ Approval Time: Safaricom typically takes 24–72 hours to review and approve your live request. You will receive your production credentials by email once approved.

Step 4 - Replace Sandbox Credentials with Live Ones

Once approved, update your application to use production values:

What to Change	Sandbox → Production
API Base URL	`sandbox.safaricom.co.ke` → `api.safaricom.co.ke`
Consumer Key	Sandbox key → New live Consumer Key
Consumer Secret	Sandbox secret → New live Consumer Secret
ShortCode	`600584` (test) → Your actual Paybill/Till number
Callback URLs	webhook.site URLs → Your real HTTPS server URLs

Step 5 - Test a Small Live Transaction

After switching to production credentials, do a small test with real money (e.g. KES 1) to confirm everything works end to end:

Pay your Paybill from a real M-PESA number
Confirm your ConfirmationURL receives the callback
Verify your database is updated correctly
Check that the customer receives the expected response or receipt

📝 Keep Logs: Always log every transaction in the early stages of going live. Implement retry logic in case of failed callbacks - Safaricom may occasionally retry if your server is slow to respond.

Common Mistakes to Avoid

#	❌ Do NOT do this	✅ Do this instead
1	Include "MPesa" or "Safaricom" in your callback URLs	Use neutral words in your URLs e.g. `/payment/confirm`
2	Use localhost or 127.0.0.1 as your callback URL	Host your app or use a tunneling tool like Ngrok (sandbox only)
3	Use webhook.site/ngrok URLs in production	Use a real, stable HTTPS server in production
4	Apply for all products without knowing what you need	Plan ahead - decide which APIs you need before going live
5	Forget to renew your access token every hour	Generate a fresh token on each session or add auto-renewal logic
6	Ignore the callback response format	Always respond with `200 OK` and valid `ResultCode`/`ResultDesc`

Useful Resources

Resource	URL
Daraja Developer Portal	https://developer.safaricom.co.ke
Daraja API Documentation	https://developer.safaricom.co.ke/APIs
Safaricom G2 Business Portal	https://org.ke.mpesa.com
Test Callback Tool	https://webhook.site
M-PESA Business Email	M-PESABusiness@safaricom.co.ke

If you need payment integrations, You can reach out to me on email.

Happy building!

DEV Community: Sospeter Mong'are

Installing and Testing Docker on WSL with MobaXterm on Windows Os

Introduction

1. What Are WSL and MobaXterm?

WSL — Windows Subsystem for Linux

MobaXterm — A Better Terminal for WSL

2. Prerequisites

3. Opening Your WSL Session in MobaXterm

4. Installing Docker Engine on WSL

Step 1: Add Docker's Official GPG Key

Step 2: Add the Docker Repository

Step 3: Install Docker Packages

Step 4: Start Docker

Step 5: Add Your User to the Docker Group (Optional but Recommended)

5. Verifying Docker with hello-world

6. Building and Running a Real Node.js App

Step 1: Create a Project Folder

Step 2: Create the Application File

Step 3: Create the Dockerfile

Step 4: Build the Docker Image

Step 5: Run the Container

Step 6: Test the Running App

7. Managing Your Containers

Cleaning Up Your Test App

Stopping Docker Engine

8. Troubleshooting Common Issues

9. Quick Reference Cheat Sheet

Conclusion

How to Install dbt with SQL Server on WSL (Windows Subsystem for Linux)

What is dbt?

Prerequisites

Step 1: Activate Your Virtual Environment

Step 2: Install dbt with the SQL Server Adapter

Step 3: Install the Microsoft ODBC Driver for SQL Server

Step 4: Clone Your dbt Project Repository

Step 5: Install dbt Project Dependencies

Step 6: Configure Your profiles.yml

Step 7: Test the Connection

Step 8: Run Your dbt Models

Other Database Adapters

Quick Reference: Most Used dbt Commands

Summary of Installation Commands

How to Install Apache Airflow 2.9.1 on WSL (Windows Subsystem for Linux)

What is Apache Airflow?

Prerequisites

1. Windows Subsystem for Linux (WSL) installed

2. MobiXterm or Windows Terminal (optional but recommended)

3. Basic familiarity with the Linux terminal

Step 1: Update Your System

Step 2: Install Python 3 and Check the Version

Step 3: Install python3.12-venv

Step 4: Create a Project Directory and Virtual Environment

Step 5: Upgrade pip

Step 6: Install Apache Airflow 2.9.1

Step 7: Initialize the Airflow Database

Step 8: Create an Admin User

Step 9: Start the Airflow Web Server and Scheduler

Step 10: Access the Airflow UI

Quick Reference: Starting Airflow After a Reboot

Summary of All Commands

What's Next?

How to Install `python-dotenv` in Python

What is python-dotenv?

Benefits of Using python-dotenv

Step 1: Install python-dotenv

Step 2: Create a .env File

Step 3: Load Environment Variables

Step 4: Using python-dotenv in Django

Step 5: Using python-dotenv in Flask

Step 6: Keep Your .env File Out of Git

Common Environment Variables

Troubleshooting

1. ModuleNotFoundError

2. Variables Returning None

Best Practices

Conclusion

AI Workflows vs AI Agents: Understanding the Difference and When to Use Each

What is an AI Workflow?

Key idea

Example of an AI workflow

Step 6: Configure Your `profiles.yml`

Step 3: Install `python3.12-venv`

What is `python-dotenv`?

Benefits of Using `python-dotenv`

Step 1: Install `python-dotenv`

Step 2: Create a `.env` File

Step 4: Using `python-dotenv` in Django

Step 5: Using `python-dotenv` in Flask

Step 6: Keep Your `.env` File Out of Git

2. Variables Returning `None`