DEV Community: Alan Varghese

How I Slashed a Docker Image from 442 MB to 56 MB (87% Cut) and Hardened It for Production

Alan Varghese — Thu, 10 Sep 2026 22:17:59 +0000

We've all been there: you whip up a simple microservice in Python, write a quick Dockerfile, run docker build, and suddenly your container image weighs almost half a gigabyte (or 1.75 GB uncompressed on disk!).

For a 15-line Flask application with two routes? That felt unacceptable.

Bloated Docker images slow down CI/CD pipelines, increase registry storage bills, consume unnecessary bandwidth during deployment, and—worst of all—expand the security attack surface with packages that have no business being in a production container.

In this project, I took a bloated baseline image and systematically redesigned it. The outcome?

🔥 Image Content Size: Reduced from 442 MB to 56.6 MB (87.19% reduction)

💾 Disk Usage: Dropped from 1.75 GB to 256 MB (85.37% reduction)

🛡️ Security: Transitioned from running as root to a hardened, non-root system user

⚡ Build Time: Dramatically improved iterative build speeds using Docker layer caching

🚀 Runtime: Replaced Flask's single-threaded dev server with a production WSGI server (Gunicorn)

Here is the full breakdown of how I did it, the pitfalls I ran into, and the key lessons you can apply to your own containers today.

🛑 The "Before": A Naive, Bloated Baseline

Here is what our initial Dockerfile.baseline looked like:

FROM python:3.12

WORKDIR /app

COPY . .

RUN apt-get update
RUN apt-get install -y curl git vim

RUN pip install --no-cache-dir -r requirements.txt

EXPOSE 5000

CMD ["python", "app.py"]

At first glance, it looks familiar. It sets a workdir, copies files, installs tools, installs dependencies, and runs the app.

Let's build it and inspect the damage:

docker build -f Dockerfile.baseline -t myapp:baseline .
docker images myapp:baseline

Output:

REPOSITORY   TAG        IMAGE ID       CREATED          SIZE
myapp        baseline   a1b2c3d4e5f6   10 seconds ago   442MB

Checking uncompressed disk usage with Docker desktop / inspect: 1.75 GB!

What Went Wrong Here?

The Base Image: python:3.12 is built on a full Debian distribution packed with compilers, header files, and utilities our web app will never call.
Unnecessary Packages: We installed curl, git, and vim. Why does a production container need a text editor and a version control tool?
Separate RUN instructions: RUN apt-get update and RUN apt-get install created two separate filesystem layers, storing temporary cache files forever in the image layer history.
Poor Layer Caching: COPY . . came before RUN pip install. Any tiny change to app.py busted Docker's cache and forced pip install to execute again from scratch.
No .dockerignore: Test files, git history, and local virtual environments were beamed right into the Docker daemon context.
Insecure Execution: The app runs as root (UID 0).
Development Server: Flask’s built-in server is not built for production workloads.

Let's fix this step-by-step.

🛠️ The 6-Step Optimization Playbook

Step 1: Switch to a Minimal Base Image (`-slim`)

The single highest-leverage change you can make is picking the right base image.

Instead of the full python:3.12, we switched to python:3.12-slim:

FROM python:3.12-slim

Why not Alpine (python:3.12-alpine)?

Alpine uses musl libc instead of glibc. While Alpine is tiny, Python packages with C extensions (like numpy, cryptography, etc.) frequently lack pre-compiled wheels for musl, triggering slow compilation during build or subtle runtime bugs. Debian slim is the sweet spot for Python: rock-solid compatibility with standard glibc wheels and a tiny footprint.

Step 2: Ruthlessly Prune Unnecessary OS Packages

Running docker history myapp:baseline exposed where the bloat lived:

apt-get update layer: ~21.3 MB
curl git vim layer: ~53.1 MB

Neither git nor vim belong in a running container. If you need to debug a running container, use ephemeral debugging sidecars or mount volumes—don't permanently ship development utilities to production.

We dropped the apt-get commands entirely.

Step 3: Add a Scrupulous `.dockerignore`

Whenever you run docker build, Docker first transfers the entire directory (the "build context") to the Docker daemon.

Without .dockerignore, you're sending .git logs, .venv, .pytest_cache, and temporary files.

We added .dockerignore:

.git
.gitignore
__pycache__
.pytest_cache
.venv
tests
*.pyc
README.md
Dockerfile*

This trimmed build context overhead and ensured sensitive or extraneous files could never leak into the container.

Step 4: Master Layer Caching (Order Matters!)

Docker caches image layers. A layer is invalidated as soon as the files it depends on change.

In our baseline:

# ❌ BAD: Edits to app.py invalidate pip install cache
COPY . .
RUN pip install --no-cache-dir -r requirements.txt

In our optimized build:

# ✅ GOOD: Dependencies change rarely, application code changes frequently
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY --chown=appuser:appuser app.py .

Now, during local development, editing app.py results in a rebuild that finishes in under a second because the heavy pip install layer is pulled straight from cache!

Step 5: Adopt a Production WSGI Server (Gunicorn)

Flask's built-in server warns you right in the logs:

"WARNING: This is a development server. Do not use it in a production deployment."

We added gunicorn to requirements.txt and updated our entrypoint:

CMD ["gunicorn", "--bind", "0.0.0.0:5000", "app:app"]

Gunicorn gives us process management, worker concurrency, and resilient request handling without bloating image size.

Step 6: Hardening Security — Run as Non-Root

By default, Docker containers run as root. If an attacker discovers a Remote Code Execution (RCE) vulnerability inside your app, they are root inside the container, making container breakout attacks significantly easier.

We created an unprivileged system user and switched to it:

RUN useradd --create-home --shell /bin/bash appuser

COPY --chown=appuser:appuser app.py .

USER appuser

We can verify this directly on the running container:

docker exec docker-opt-optimized whoami
# Output: appuser

🏆 The "After": Hardened & Optimized Dockerfile

Here is our final, production-ready Dockerfile.optimized:

FROM python:3.12-slim

WORKDIR /app

# 1. Leverage layer caching for dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 2. Security: Create dedicated unprivileged user
RUN useradd --create-home --shell /bin/bash appuser

# 3. Copy application code with proper ownership
COPY --chown=appuser:appuser app.py .

# 4. Drop root privileges
USER appuser 

EXPOSE 5000

# 5. Production WSGI server
CMD ["gunicorn", "--bind", "0.0.0.0:5000", "app:app"]

Total lines: 18. Clean, readable, and lightning-fast.

📊 The Scorecard: Baseline vs. Optimized

Metric	Baseline	Optimized	Difference
Base Image	`python:3.12`	`python:3.12-slim`	Streamlined
Content Size	442 MB	56.6 MB	-385.4 MB (-87.2%)
Uncompressed Disk	1.75 GB	256 MB	-1.49 GB (-85.4%)
Extra OS Tools	`curl`, `git`, `vim` (~74 MB)	Zero	Clean runtime
Layer Caching	Broken on every commit	Optimized	Instant rebuilds
User	`root` (UID 0)	`appuser`	Least privilege
Web Server	Dev server	Gunicorn WSGI	Production ready

🥊 Real-World Gotchas & Lessons Learned

Optimization isn't just about shaving megabytes in a spreadsheet—here are real obstacles encountered during the project:

1. The "Host Port Already in Use" Trap

When launching the container:

docker run -p 5000:5000 myapp:optimized
# Error: bind: address already in use

On macOS, port 5000 is frequently taken by the OS AirPlay Receiver service.

Solution: Understand Docker's port mapping format (HOST_PORT:CONTAINER_PORT).

We mapped -p 5001:5000, letting the internal app stay on 5000 while exposing it cleanly on host port 5001.

docker run -d --name docker-opt-optimized -p 5001:5000 docker-image-optimization:optimized
curl http://localhost:5001/health
# {"status":"healthy"}

2. "Disk Usage" vs "Content Size"

When running docker images, Docker may report one size, while docker system df -v or registry push reports another.

Content Size: The compressed size of layers transferred across networks/registries (56.6 MB).
Disk Usage: The uncompressed layer footprint unpacked on the host filesystem (256 MB vs 1.75 GB). Always use consistent metrics when publishing benchmarks!

3. Never Optimize Without Validation

An image with 0 MB size that crashes is useless. After trimming the image, always test both endpoints and run automated test suites:

# Automated tests via pytest
mise exec -- pytest

tests/test_app.py ..                             [100%]
====================== 2 passed in 0.08s =======================

💡 Quick Docker Optimization Checklist for Your Projects

Save this checklist for your next Dockerfile:

[ ] Use -slim or minimal official base images.
[ ] Maintain a .dockerignore containing .git, caches, virtual environments, and tests.
[ ] Copy requirements.txt / package.json before copying application code.
[ ] Remove curl, vim, git, and build tools from final production images.
[ ] Use --no-cache-dir (Python) or --no-cache / clean commands when installing dependencies.
[ ] Create and switch to a non-root USER.
[ ] Replace development servers with production application servers (Gunicorn, Uvicorn, Nginx).
[ ] Validate image behavior with health checks and unit tests.

💬 Over to You!

Have you ever inspected your production Docker images with docker history and found unexpected surprises? What's your favorite trick for shrinking containers? Drop your thoughts in the comments below! 👇

Building a Multi-Container App with Docker Compose: 10 Real-World Gotchas and Lessons Learned

Alan Varghese — Tue, 08 Sep 2026 21:07:27 +0000

When you read basic Docker Compose tutorials, orchestrating a multi-tier application looks effortless: write a quick docker-compose.yml, run docker-compose up, and everything just magically talks to each other.

Then you actually build a full-stack project with Nginx (Frontend), Flask (Backend API), and PostgreSQL (Database) inside a modern containerized environment like DevPod / Dev Containers—and reality sets in.

Suddenly, you're wrestling with:

Docker socket permission errors inside your dev container.
Host port vs. container port confusion across multiple environments.
Browser CORS errors on requests that returned HTTP 200.
Database connections reporting "disconnected" despite PostgreSQL running fine.
Containers starting before the database is actually ready to accept queries.
Data disappearing because of a single careless CLI flag.

In this post, I will walk you through the architecture of a resilient multi-container web application and break down 10 critical bugs, troubleshooting workflows, and practical lessons learned while building it.

🏗️ The Application Architecture

The stack consists of three isolated services running on an internal Docker bridge network:

                         Host Machine (Browser / curl)
                                     |
               +---------------------+---------------------+
               |                                           |
               | http://localhost:8081                     | http://localhost:5002
               v                                           v
       +---------------+                           +---------------+
       |   Frontend    |  (Client-side Fetch)      |    Backend    |
       |  Nginx Alpine |-------------------------->|  Flask (Py3)  |
       |  (Port: 80)   |                           |  (Port: 5000) |
       +---------------+                           +-------+-------+
                                                           |
                                                           | database:5432
                                                           v
                                                   +---------------+
                                                   |   Database    |
                                                   | PostgreSQL 16 |
                                                   |  (Port: 5432) |
                                                   +-------+-------+
                                                           |
                                                           v
                                                  [ postgres_data ]
                                                   (Named Volume)

Port Mappings at a Glance

Service	Container Port	Host Port	Purpose
Frontend (`Nginx`)	`80`	`8081`	Serves static HTML/JS UI
Backend (`Flask`)	`5000`	`5002`	REST API (`/health`, `/db-health`, `/users`)
Database (`Postgres`)	`5432`	Internal	Data persistence

💥 10 Real-World Gotchas & Lessons Learned

1. The DevPod / Docker Socket Permission Trap

When developing inside a containerized dev environment (like DevPod or VS Code Dev Containers) that mounts the host Docker socket (/var/run/docker.sock), running docker ps can throw this classic roadblock:

permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock

Why It Happens

The non-root container user (vscode) doesn't belong to the group that owns the mounted socket file on the host.

The Wrong Fix vs. The Right Fix

❌ Don't do: sudo chmod 777 /var/run/docker.sock. Changing permissions on the host socket punches a major security hole into your host daemon.

✅ Do: Add the dev container user to the group ID matching /var/run/docker.sock. In our .devcontainer/Dockerfile:

RUN usermod -aG root vscode

2. Host Port vs. Container Port Confusion

In our docker-compose.yml, the backend configuration was:

ports:
  - "5002:5000"

This syntax always means: <Host Port>:<Container Port>.

Flask listens on 0.0.0.0:5000 inside the container.
Docker forwards connections from port 5002 on the host machine to port 5000 in the container.

The Trap

Running curl http://localhost:5002/health worked directly from the host Mac terminal, but failed inside the DevPod dev container.

Why? localhost is scoped to your current network namespace:

On the host Mac: localhost:5002 reaches the published Docker port.
Inside DevPod: localhost is the DevPod container itself, which isn't listening on 5002!

Lesson: Always know which network namespace your command is executing in.

3. Frontend-to-Backend Port Mismatch

Our frontend static index.html originally had:

fetch("http://localhost:5000/health")

When opened in the browser at http://localhost:8081, clicking the button failed with a connection error.

Why? The browser is running on the host machine. The backend isn't exposed on localhost:5000 on the host; it was published on port 5002.

The Fix

Update the browser fetch call:

const response = await fetch("http://localhost:5002/health");

4. The CORS Paradox: When HTTP 200 Still Fails

Once the port was corrected, the network tab showed HTTP 200 OK, but the browser console threw this error:

Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at http://localhost:5002/health. 
(Reason: CORS header 'Access-Control-Allow-Origin' missing). Status code: 200.

The Insight

An HTTP status of 200 OK means the backend successfully received and processed the request. However, because the frontend is served from http://localhost:8081 and the backend is at http://localhost:5002, they are different origins (different ports = different origins). The browser's Same-Origin Policy blocks client-side JavaScript from reading the response unless the backend explicitly provides CORS headers.

The Fix

Install flask-cors in backend/requirements.txt and wrap the Flask app:

from flask import Flask
from flask_cors import CORS

app = Flask(__name__)
CORS(app)

5. The Phantom Disconnection: Environment Variable Misalignment

Testing the database health check endpoint (curl http://localhost:5002/db-health) returned:

{"database": "disconnected", "error": "fe_sendauth: no password supplied"}

Yet running a manual test using docker exec worked seamlessly:

docker exec -it multi-container-backend python -c "
import psycopg2
conn = psycopg2.connect(host='database', dbname='appdb', user='appuser', password='apppassword')
print('Connected!')
"

The Culprit

We inspected the environment using docker-compose config and found:

docker-compose.yml was injecting DB_NAME, DB_USER, DB_PASSWORD.
Flask's app.py was looking for POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD.

Only DB_HOST matched; the user and password fell back to non-matching defaults!

The Fix

Always ensure your variable names match seamlessly across .env, docker-compose.yml, and application source code:

def get_db_connection():
    return psycopg2.connect(
        host=os.getenv("DB_HOST", "database"),
        dbname=os.getenv("DB_NAME", "appdb"),
        user=os.getenv("DB_USER", "appuser"),
        password=os.getenv("DB_PASSWORD", "apppassword"),
    )

6. Container-to-Container DNS vs. `localhost`

Inside a container, localhost refers strictly to that container.
If your Flask backend tries to connect to localhost:5432, it attempts to find PostgreSQL inside the Flask container and fails.

The Docker Solution

Docker Compose automatically creates an internal bridge network and sets up DNS records using the service names:

Backend connects to host="database", port 5432.
Docker resolves database directly to the PostgreSQL container IP.

7. Verifying True Data Persistence (and the Dangerous `-v` Flag)

A common mistake in Docker development is assuming your database data is safe without testing container destruction.

To verify persistence:

Insert a user:

   curl -X POST http://localhost:5002/users -H "Content-Type: application/json" -d '{"name":"Alan Turing"}'

Stop and remove the database container:

   docker-compose stop database
   docker-compose rm -f database

Spin up a brand new container:

   docker-compose up -d database

Query /users: Alan Turing is still there!

Because we declared a named volume in docker-compose.yml:

volumes:
  - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

⚠️ Warning: Never use docker-compose down -v when testing persistence. The -v flag deletes all named volumes, wiping out your database!

8. Health Checks: Running vs. Ready

If service A depends on service B, using only depends_on: [database] is not enough. Docker starts the backend as soon as the PostgreSQL container process spawns—which is seconds before the database is actually initialized and accepting connections.

The Solution: Healthcheck + `condition: service_healthy`

In docker-compose.yml:

services:
  database:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5

  backend:
    build: ./backend
    depends_on:
      database:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:5000/health')"]
      interval: 10s
      timeout: 5s
      retries: 5

Now, Docker delays starting Flask until pg_isready returns exit code 0.

9. Pytest in Dev Environments vs. Docker Integration Tests

When running pytest in your local or dev-container environment, you might be tempted to test database endpoints directly. However:

Your local Python interpreter isn't inside the Compose bridge network.
database:5432 won't resolve locally unless PostgreSQL's port is published to the host.

Strategy

Keep your test tiers clear:

Unit/API Tests (Pytest): Test business logic and mock external network calls. Verify /health via Flask's test_client().
Integration Tests (cURL/HTTP client): Execute queries against the live, running Compose stack.

10. The Systematic 6-Step Debugging Workflow

When multi-container stacks misbehave, resist the urge to randomly change settings. Follow this deterministic sequence:

Check Status & Health:

   docker-compose ps

Check Logs:

   docker-compose logs backend
   docker-compose logs database

Check Resolved Configuration:

   docker-compose config

(Catches 90% of missing .env variable substitutions!)

Inspect Live Container Environment:

   docker exec -it multi-container-backend env | grep DB_

Direct Endpoint Testing:

   curl -i http://localhost:5002/health
   curl -i http://localhost:5002/db-health

Browser Developer Tools: Inspect the Network & Console tabs for CORS headers and origin mismatches.

🚀 Key Takeaways

Containers are disposable; volumes are permanent. Treat containers as ephemeral compute instances.
Service names are hostnames. Inside the Docker network, use database, backend, and frontend.
HTTP 200 doesn't mean your frontend works. Always account for CORS when frontend and backend run on different ports.
depends_on needs condition: service_healthy. Never assume a running container is a ready service.
docker-compose config is your best friend. Run it whenever environment variables behave unpredictably.

💬 Discussion

Have you run into CORS surprises or database startup race conditions in Docker Compose? What is your favorite healthcheck pattern? Let me know in the comments below!

From Code to Container: What Building & Debugging My First Dockerized App Taught Me About Real-World DevOps

Alan Varghese — Tue, 08 Sep 2026 21:03:58 +0000

We’ve all heard the timeless developer cliché:

"It works on my machine!"

"Well, then we'll ship your machine!"

...and that is practically how Docker was born.

Recently, I set out on a DevOps homelab project to containerize a Python Flask web application. On the surface, the tutorial playbook sounded deceptively simple: write an app.py, slap together a Dockerfile, run docker build, run docker run, and celebrate.

Except in real-world DevOps, getting the app to run is only 20% of the battle.

The real learning happened when things broke: when Unix socket permissions locked me out inside DevPod, when port conflicts greeted me on macOS, when containers exited unexpectedly, and when network interfaces refused to talk to each other.

Here is a comprehensive breakdown of my journey, the architecture, the "aha!" moments, and the systematic troubleshooting mindset that completely changed how I look at containerization.

🛠️ The Architecture & The Environment

Before writing any code, I wanted a modern, reproducible setup rather than polluting my personal macOS host machine.

Here is the tech stack I used:

Host Machine: macOS (Apple Silicon / aarch64) running Docker Desktop
Development Environment: DevPod (using Docker as its provider) with an Ubuntu 24.04 container
Toolchain Manager: Mise (managing Python, pipx, and Docker CLI)
Application Framework: Flask (Python 3.12)
Container Engine: Docker

How the Pieces Fit Together

Here is the mental model of how the host, DevPod, the Docker daemon, and the containerized app communicate:

┌─────────────────────────────────────────────────────────────┐
│ macOS Host (Docker Desktop Engine & Daemon)                 │
│                                                             │
│   ┌──────────────────────────────────────────────────────┐  │
│   │ DevPod Development Container (Ubuntu 24.04)          │  │
│   │   - Managed with Mise (Python 3.12, Docker CLI)      │  │
│   │   - Connected via /var/run/docker.sock bind mount     │  │
│   │   - Builds and controls containers                   │  │
│   └──────────────────────┬───────────────────────────────┘  │
│                          │ Controls via Docker API          │
│                          ▼                                  │
│   ┌──────────────────────────────────────────────────────┐  │
│   │ Application Container: containarize-web-app          │  │
│   │   - Python 3.12-slim base                            │  │
│   │   - Flask app listening on 0.0.0.0:5000              │  │
│   └──────────────────────▲───────────────────────────────┘  │
│                          │                                  │
│                 Port Mapping (-p 5001:5000)                 │
│                          │                                  │
│   Browser / Curl ────────┴───────────────────────────────   │
│   http://localhost:5001                                     │
└─────────────────────────────────────────────────────────────┘

🐍 1. The Application & The Dockerfile

The web application itself is a minimal Flask service in app.py:

from flask import Flask

app = Flask(__name__)


@app.route("/")
def hello():
    return "Hello from my containerized application!"


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)

Notice host="0.0.0.0". More on why that is critical in a moment!

Next came the Dockerfile:

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .

RUN pip install --no-cache-dir -r requirements.txt

COPY app.py .

EXPOSE 5000

CMD ["python", "app.py"]

💡 Lesson 1: Build Order & Layer Caching Matter

Notice that I didn’t just do COPY . . at the top.

Docker builds images in sequential, cacheable layers. By copying only requirements.txt and running pip install before copying app.py, Docker caches the installed packages. If I tweak a single string or route inside app.py, Docker re-uses the cached dependency layer and rebuilds in milliseconds instead of re-downloading packages every single time.

I also added a .dockerignore to ensure .git, __pycache__, and local .venv folders never bloat the Docker build context.

⚡ 2. The DevPod Challenge: The "Docker-in-Docker" Socket Mystery

Because I was developing inside a DevPod devcontainer, running docker info initially spat out a fatal error:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

What was happening?

The Docker CLI is just a client—a messenger. It doesn't actually build or run containers; the Docker Daemon does. My devcontainer had the Docker CLI installed, but the daemon lived outside on my Mac (Docker Desktop).

To fix this, I needed to bind-mount the Docker Unix socket in .devcontainer/devcontainer.json:

{
  "build": {
    "context": "..",
    "dockerfile": "Dockerfile"
  },
  "mounts": [
    "source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind"
  ]
}

The Permissions Curveball: `srw-rw---- root root`

Once the socket was mounted, I ran docker info again, only to be stopped by another error:

permission denied while trying to connect to the Docker API

Checking the socket with ls -la /var/run/docker.sock revealed:

srw-rw---- 1 root root 0 /var/run/docker.sock

Unix sockets obey standard Linux file permission bits. The socket was owned by root:root, but DevPod runs as the non-root vscode user.

Instead of doing an insecure chmod 777, the clean fix was getting my active shell to recognize root/docker group privileges:

newgrp root

Immediately after running newgrp root, docker info connected cleanly, outputting:

Server Version: 29.7.2
Operating System: Docker Desktop
Architecture: aarch64

The bridge between DevPod and Docker Desktop was live! 🚀

🌐 3. Networking Lessons: The Tale of Two IP Addresses & Port Mapping

Once my image was built with:

docker build -t containarize-web-app .

it was time to run the container. That’s when container networking fundamentals kicked in.

Why `0.0.0.0` vs. `127.0.0.1`?

When developing locally, you usually bind to 127.0.0.1 (localhost). But inside a container:

127.0.0.1 is the loopback interface of the container itself. Any request originating from outside the container (even from the host through Docker's bridge) gets discarded at the door.
Binding to 0.0.0.0 tells Flask: "Listen on all network interfaces inside this container." This allows traffic forwarded by Docker to actually reach the application.

The Port Conflict: `5001:5000`

When I tried running:

docker run --name containarize-web-app -p 5000:5000 containarize-web-app

I got hit with:

bind: address already in use

Port 5000 was already occupied on my macOS host (often taken by macOS AirPlay Receiver or another local daemon).

Here is the beauty of Docker port mapping: You do not need to change your application code or container configuration.

The -p syntax represents:

-p <HOST_PORT>:<CONTAINER_PORT>

By changing the mapping to -p 5001:5000, requests hitting my Mac on port 5001 get transparently routed to port 5000 inside the container:

docker run -d \
  --name containarize-web-app \
  -p 5001:5000 \
  containarize-web-app

🧪 4. Testing at Every Layer

One huge habit I developed during this project was testing layer-by-layer rather than guessing when something failed.

Step 1: Test directly inside the container

First, verify whether Flask is alive inside its own container boundary using docker exec:

docker exec containarize-web-app \
  python -c "import urllib.request; print(urllib.request.urlopen('http://127.0.0.1:5000').read().decode())"

Output:

Hello from my containerized application!

(Flask is alive and answering on port 5000!)

Step 2: Test from the host via published port

Now, test through Docker’s network port forwarder from the host terminal:

curl http://localhost:5001

Output:

Hello from my containerized application!

And opening http://localhost:5001 in the browser yielded the same greeting. The end-to-end network chain was completely validated!

🧠 5. The Golden Rule of DevOps Debugging: Isolate the Layers

When an error strikes in containerized environments, our natural instinct is often to frantically change five things at once: modify app.py, change the Dockerfile, restart Docker Desktop, and tweak host settings.

This project taught me a much more structured debugging ladder:

 1. Application Layer   ──> Does Python/Flask run locally? Check syntax & deps.
          ↓
 2. Container Lifecycle ──> Did the container start or crash? (docker ps -a, docker logs)
          ↓
 3. Process Binding     ──> Is Flask listening on 0.0.0.0 (not 127.0.0.1)?
          ↓
 4. Port Forwarding     ──> Is the host port conflicting? Is HOST:CONTAINER mapped right?
          ↓
 5. Daemon & Socket     ──> Is the Docker socket mounted and readable? (newgrp root)
          ↓
 6. Host Ingress        ──> Can curl or the browser reach localhost:HOST_PORT?

By moving down the ladder one rung at a time, finding the root cause becomes deterministic rather than a guessing game.

🧰 My Essential Docker Toolkit

Here are the commands I found myself relying on constantly:

Command	What it does
`docker build -t <name> .`	Builds the image using the current directory context
`docker run -d --name <name> -p <host>:<container> <image>`	Runs the container detached in the background
`docker ps -a`	Lists all containers, including stopped/exited ones
`docker logs <container>`	Prints stdout/stderr logs from the container
`docker inspect <container>`	Inspects IP addresses, network settings, and state
`docker exec -it <container> sh`	Drops you into an interactive shell inside the running container
`docker rm -f <container>`	Stops and removes a container in one shot

🔮 What’s Next on the Roadmap?

This project gave me solid operational foundations, but real-world production setups go even further. Here is what I plan to build next:

Production WSGI Server: Replace Flask’s development server with Gunicorn.
Security Hardening: Add a non-root USER appuser in the Dockerfile.
Container Healthchecks: Add Docker HEALTHCHECK instructions.
CI/CD Pipeline: Automate builds and test suites with GitHub Actions.
Orchestration: Expand to multi-container setups using Docker Compose and eventually deploy to Kubernetes!

💬 Over to You!

If you're starting your DevOps journey, what was the first weird Docker error that made you pull your hair out? Was it socket permissions, port collisions, or dangling volumes?

Drop a comment below—I’d love to hear your container war stories! 👇

Zero to Published: Building an Automated Release Pipeline with GitHub Actions, Mise, and DevPod

Alan Varghese — Tue, 08 Sep 2026 20:58:18 +0000

We've all been there: you finish implementing a new feature, run a quick manual check in your terminal, zip up the build directory by hand, navigate to GitHub, click Releases, upload your zip file, and write a release note on the fly.

Then, ten minutes later, a user opens an issue: "The release package is missing a critical config file," or "The build fails on Python 3.12 because of an untracked dependency mismatch."

Manual releases are slow, error-prone, and painful to reproduce. In modern software engineering, every step between writing code and shipping a release should be automated, deterministic, and protected by quality gates.

In this article, I'll walk you through how I built an end-to-end automated release pipeline for a Python project hosted inside a multi-project monorepo (alanvarghese-dev/lab). We’ll cover:

Deterministic Development Environments using DevPod and Mise.
Quality Gates with Ruff (linting) and Pytest (unit testing).
CI/CD Pipeline Orchestration using GitHub Actions.
Automated Release Packaging & Publishing triggered seamlessly by Git tags.
Real-World Gotchas encountered along the way (and how to solve them).

🏗️ Architecture & Monorepo Layout

Before jumping into the code, let’s look at the structure. This project resides as a subproject within a larger DevOps lab repository (alanvarghese-dev/lab). This setup allows multiple DevOps experiments and pipelines to coexist without cluttering separate repositories.

Here is how the repository is structured:

/workspaces/ (Repository Root)
├── .github/
│   └── workflows/
│       └── automated-release.yml      # Root CI/CD workflow
│
└── automated-release-pipeline/        # Subproject Directory
    ├── .devcontainer/
    │   ├── Dockerfile                 # DevPod container specification
    │   └── .devcontainer.json         # DevContainer build context
    ├── tests/
    │   └── test_app.py                # Automated Pytest suite
    ├── app.py                         # Core application entrypoint
    ├── mise.toml                      # Declarative tool & version manager
    ├── pytest.ini                     # Pytest discovery & module search path
    ├── .gitignore                     # Clean repository boundaries
    └── dist/
        └── automated-release-pipeline.tar.gz  # Generated release artifact

💡 Monorepo Tip: Because the Git root is at /workspaces while our application lives under /workspaces/automated-release-pipeline/, our GitHub Actions workflow is defined at the root .github/workflows/ directory, while workflow steps target the subproject folder.

📦 Step 1: Isolated Environment with DevPod & Mise

One of the biggest friction points in developer velocity is the classic "works on my machine" problem. To achieve 100% parity between local development and CI runners, we combine DevPod (containerized development) with Mise (modern polyglot tool manager).

1. DevPod Configuration

Using a DevContainer specification based on Ubuntu 24.04, we bake mise directly into the container image:

# .devcontainer/Dockerfile
FROM mcr.microsoft.com/devcontainers/base:ubuntu-24.04

# Copy Mise binary directly from official image
COPY --from=jdxcode/mise /usr/local/bin/mise /usr/local/bin/

# Auto-activate Mise in interactive shells
RUN echo 'eval "$(mise activate bash)"' >> /home/vscode/.bashrc && \
    echo 'eval "$(mise activate zsh)"' >> /home/vscode/.zshrc

And configure the DevContainer manifest:

// .devcontainer/devcontainer.json
{
  "name": "automated-release-pipeline",
  "build": {
    "context": "..",
    "dockerfile": "Dockerfile"
  },
  "remoteUser": "vscode"
}

2. Declarative Tooling with `mise.toml`

Instead of relying on whatever Python version is globally installed on your host OS, mise.toml locks down the exact runtimes, package managers, and CLI tools:

# mise.toml
[tools]
python = "3.12"
pipx = "latest"
"pipx:pytest" = "latest"
"pipx:ruff" = "latest"

With one command:

mise install

Mise downloads and configures Python 3.12, Pytest, and Ruff in an isolated sandbox.

🧪 Step 2: Application Code & Quality Gates

To validate the release workflow, we have a clean Python application with corresponding unit tests and linter configurations.

1. The Application (`app.py`)

# app.py
def add(a, b):
    return a + b


if __name__ == "__main__":
    print(f"2 + 3 = {add(2, 3)}")

2. Unit Testing with Pytest (`tests/test_app.py`)

# tests/test_app.py
from app import add


def test_add():
    assert add(2, 3) == 5


def test_add_negative_numbers():
    assert add(-2, -3) == -5

3. Configuring Pytest (`pytest.ini`)

When tests reside in a subdirectory (tests/) separate from the root source files, Python's import engine needs to know where to find top-level modules. We declare this cleanly in pytest.ini:

# pytest.ini
[pytest]
testpaths = tests
pythonpath = .

4. Local Verification Commands

Before pushing any commit, we verify our quality gates locally using mise exec:

# 1. Run the application
mise exec -- python app.py

# 2. Run Ruff linter (code quality)
mise exec -- ruff check .

# 3. Run Pytest suite
mise exec -- pytest

⚡ Step 3: CI/CD Pipeline Orchestration with GitHub Actions

Now comes the core automation engine. We want GitHub Actions to:

Trigger automatically whenever a release tag (e.g. v*) or commit is pushed.
Spin up Mise and install our pinned toolset.
Enforce Quality Gates (Ruff + Pytest). If either fails, immediately halt the pipeline.
Package the application assets into a clean .tar.gz distribution archive.
Upload the artifact to the GitHub workflow run.
Publish a formal GitHub Release with auto-generated changelogs and the release tarball attached.

The Pipeline Architecture

flowchart TD
    A["Developer pushes Git Tag (e.g., v1.0.0)"] --> B["GitHub Actions Triggered"]
    B --> C["Checkout Repo (actions/checkout@v4)"]
    C --> D["Setup Mise (jdx/mise-action@v3)"]
    D --> E["Install Dependencies (mise install)"]
    E --> F["Lint Gate (mise exec -- ruff check .)"]
    F --> G["Test Gate (mise exec -- pytest)"]
    G --> H["Build Release Archive (dist/automated-release-pipeline.tar.gz)"]
    H --> I["Upload CI Artifact (actions/upload-artifact@v4)"]
    I --> J["Publish GitHub Release (softprops/action-gh-release@v2)"]
    J --> K["🎉 Release Published with Tarball Attached"]

    F -.->|Linter Error| L["❌ Halt Pipeline"]
    G -.->|Test Failure| L

The GitHub Actions Workflow File (`.github/workflows/automated-release.yml`)

name: Automated Release Pipeline

on:
  push:
    branches:
      - main
    tags:
      - 'v*'
  pull_request:
    branches:
      - main

permissions:
  contents: write

jobs:
  validate-and-release:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: ./automated-release-pipeline

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4

      - name: Setup Mise
        uses: jdx/mise-action@v3

      - name: Install Tools via Mise
        run: mise install

      - name: Code Quality Check (Ruff)
        run: mise exec -- ruff check .

      - name: Run Test Suite (Pytest)
        run: mise exec -- pytest

      - name: Package Release Tarball
        if: startsWith(github.ref, 'refs/tags/v')
        run: |
          mkdir -p dist
          tar -czvf dist/automated-release-pipeline.tar.gz app.py mise.toml pytest.ini

      - name: Upload Build Artifact to Workflow Run
        if: startsWith(github.ref, 'refs/tags/v')
        uses: actions/upload-artifact@v4
        with:
          name: automated-release-pipeline-dist
          path: automated-release-pipeline/dist/automated-release-pipeline.tar.gz

      - name: Create GitHub Release
        if: startsWith(github.ref, 'refs/tags/v')
        uses: softprops/action-gh-release@v2
        with:
          files: automated-release-pipeline/dist/automated-release-pipeline.tar.gz
          generate_release_notes: true

🏷️ Step 4: The Tag-Driven Release Flow in Action

With the workflow in place, cutting a new release is completely frictionless. Here is the exact end-to-end developer workflow:

1. Test and Stage Locally

# Verify all quality checks pass
mise exec -- ruff check .
mise exec -- pytest

# Stage and commit your changes
git add .
git commit -m "feat: complete automated release pipeline setup"
git push origin main

2. Cut and Push an Annotated Release Tag

# Create an annotated Git tag
git tag -a v1.0.0 -m "Release v1.0.0"

# Explicitly push the tag reference
git push origin refs/tags/v1.0.0

3. The Result

Once pushed:

GitHub Actions detects refs/tags/v1.0.0.
Tools are provisioned via jdx/mise-action.
Ruff and Pytest execute in seconds.
dist/automated-release-pipeline.tar.gz is built and uploaded.
A GitHub Release v1.0.0 is published with the tarball attached and release notes automatically generated from commit history!

🐛 Troubleshooting & War Stories

Real engineering is never without bumps. Here are three common issues encountered during this project and how to fix them:

1. Pytest `ModuleNotFoundError: No module named 'app'`

Problem: Running pytest from the root directory failed to import app.py inside tests/test_app.py.
Root Cause: By default, pytest does not always add the current working directory to sys.path.
Solution: Create a pytest.ini file in the project root containing:

  [pytest]
  testpaths = tests
  pythonpath = .

2. Git Tag Push Error: `src refspec v1.0.0 does not match any`

Problem: Running git push origin v1.0.0 failed with a refspec mismatch error.
Root Cause: The tag had not been created as an annotated tag or was ambiguous in local refs.
Solution: Verify the local tag exists with git tag, create an annotated tag with git tag -a v1.0.0 -m "Release v1.0.0", and push explicitly using the full reference path:

  git push origin refs/tags/v1.0.0

3. Monorepo Path Context in GitHub Actions

Problem: Actions failed when looking for mise.toml at the repository root.
Root Cause: The pipeline is inside /workspaces/automated-release-pipeline/, but GitHub Actions defaults to the root of the Git repo.
Solution: Set defaults.run.working-directory: ./automated-release-pipeline in the GitHub Actions job configuration so that every run step executes in the correct subdirectory.

🔮 What's Next? (Future Roadmap)

While this pipeline is rock solid for our Python application, here are great next-level enhancements for enterprise production systems:

[ ] Docker Image Builds & Container Registry: Package the application into a minimal Docker container and push to GitHub Container Registry (GHCR).
[ ] Automated Semantic Versioning: Incorporate tools like semantic-release or commitizen to parse Conventional Commits and auto-bump versions without manual tagging.
[ ] Security Scanning (SAST): Add tools like Bandit and Trivy to scan dependencies and source code for CVEs during CI.
[ ] Deployment Environments: Add deployment stages (Dev -> Staging -> Prod) with approval gates using GitHub Environments.

🧠 Key Takeaways

A release pipeline is much more than a simple build script. A true production-ready release pipeline connects:

$$\text{Source Control} \longrightarrow \text{Tool Management} \longrightarrow \text{Quality Gates} \longrightarrow \text{Artifact Packaging} \longrightarrow \text{Distribution}$$

By combining DevPod for containerized dev environments, Mise for unified tooling, Pytest & Ruff for zero-defect quality gates, and GitHub Actions for tag-driven releases, we eliminated manual errors and turned releases into a one-command celebration. 🎉

💬 How do you manage releases in your projects? Are you using Mise, ASDF, or Docker for tool versioning? Let's discuss in the comments below!

Building a Bulletproof Python CI Pipeline with GitHub Actions, DevPod & Mise (+ the Real-World Bugs We Squashed Along the Way)

Alan Varghese — Tue, 01 Sep 2026 16:07:35 +0000

A complete guide to building reproducible, containerized Python CI pipelines using DevPod, Mise, Ruff, pytest, and GitHub Actions—featuring hard-won lessons from real debugging sessions.

Have you ever uttered the classic developer refrain: "Well, it works on my machine!"?

We have all been there. You write a clean Python script, write a few unit tests that pass locally, push to GitHub, and immediately get greeted by a glowing red ❌ in your CI pipeline. Or even worse: your CI passes with flying colors, only for production to blow up because your CI runner was secretly masking environment mismatches.

In this guide, we will walk through building an end-to-end, production-ready Continuous Integration (CI) pipeline for a Python project from scratch. We combine:

🐳 DevPod & Docker: For fully isolated, reproducible local container environments.
⚙️ Mise-en-place (Mise): For declarative, deterministic tool versioning across local and CI.
⚡ Ruff: For blazingly fast linting and auto-formatting.
🧪 pytest: For rock-solid unit testing.
🚀 GitHub Actions: For automated quality gates on every push.

More importantly, rather than showing only the "happy path," we will dissect the real-world edge cases and debugging hurdles encountered along the way—including Python import path traps, monorepo workflow discovery quirks, toolchain vs. interpreter disconnects, and why you should always deliberately break your CI to verify its integrity.

🏛 The Architecture: How It All Fits Together

A robust development lifecycle requires a clear separation of concerns. Developer ergonomics shouldn't bleed into project dependencies, and local environments should mirror CI as closely as possible.

+-------------------------------------------------------------------------+
|                       LOCAL DEVELOPMENT (DevPod)                        |
|                                                                         |
|  Developer  ──>  DevPod / Docker Container                              |
|                         ├── Dotfiles (Personal Shell / Theme)           |
|                         └── Mise (Declared Tools in mise.toml)          |
|                                  ├── Python 3.12+                       |
|                                  ├── Ruff (Linter/Formatter)            |
|                                  └── pytest (Test Runner)               |
|                                                                         |
|  Local Quality Checks: ruff check .  &&  pytest -vv                     |
+-------------------------------------------------------------------------+
                                   │
                               git push
                                   ▼
+-------------------------------------------------------------------------+
|                       REMOTE CI (GitHub Actions)                        |
|                                                                         |
|  GitHub Actions Runner (Ubuntu Latest)                                  |
|         ├── 1. Checkout Repository                                      |
|         ├── 2. Install Mise (`jdx/mise-action`)                         |
|         ├── 3. `mise install` (Identical Tool Versions)                 |
|         ├── 4. Run Ruff (`mise exec -- ruff check .`)                   |
|         └── 5. Run pytest (`mise exec -- pytest -vv`)                   |
|                                                                         |
|  CI Verdict: PASS ✅ or FAIL ❌                                          |
+-------------------------------------------------------------------------+

Separation of Concerns

Layer	Responsibility	Key Files
Dotfiles	Developer ergonomics, shell prompt, aliases, personal editor config	`.zshrc`, `.bashrc`, personal Git config
Dev Container	OS-level base image, container runtime	`Dockerfile`, `.devcontainer.json`
Mise	Language versions, linters, package runners	`mise.toml`
Application	Business logic, module definitions	`src/`, `pytest.ini`
Test Suite	Unit tests, edge case assertions	`tests/`
CI / CD	Automated validation, branch protection rules	`.github/workflows/github-actions-ci.yml`

📂 1. Setting Up the Project Structure

Let's start with a clean directory layout:

github-actions-devpod-ci/
├── .devcontainer.json         # Dev container configuration
├── Dockerfile                 # Container image definition with Mise
├── .gitignore                 # Cache & environment ignores
├── mise.toml                  # Declarative tool specifications
├── pytest.ini                 # Python path configuration
├── src/
│   ├── __init__.py
│   └── main.py                # Application logic
└── tests/
    └── test_main.py           # Automated unit tests

The Application Code (`src/main.py`)

A simple arithmetic module with explicit error handling:

def add(a, b):
    return a + b


def subtract(a, b):
    return a - b


def multiply(a, b):
    return a * b


def divide(a, b):
    if b == 0:
        raise ValueError("Cannot divide by zero")
    return a / b


if __name__ == "__main__":
    print("GitHub Actions DevPod CI Demo")
    print("2 + 3 =", add(2, 3))

The Test Suite (`tests/test_main.py`)

from src.main import add, divide, multiply, subtract


def test_add():
    assert add(2, 3) == 5


def test_subtract():
    assert subtract(5, 3) == 2


def test_multiply():
    assert multiply(4, 3) == 12


def test_divide():
    assert divide(10, 2) == 5


def test_divide_by_zero():
    try:
        divide(10, 0)
        assert False
    except ValueError:
        assert True

🛠 2. Deterministic Tool Management with Mise

Instead of relying on whatever version of Python or linters happen to be installed on your host machine, we use Mise to declare exact tooling requirements in mise.toml:

[tools]
python = "latest"
"pipx:ruff" = "latest"
"pipx:pytest" = "latest"
pipx = "latest"

Why Mise + pipx?

Mise allows you to manage programming language runtimes (like asdf or nvm) and standalone CLI tools (via pipx, cargo, npm, or standalone binaries) in a single declarative configuration file.

When a developer joins your project or the CI runner fires up, running:

mise install

installs everything in one shot. No manual virtualenv activation dance, no missing binary surprises.

🐳 3. Local Development with DevPod & Dev Containers

To ensure every developer works in a clean, reproducible container, we define a lightweight Dockerfile and .devcontainer.json.

`Dockerfile`

FROM mcr.microsoft.com/devcontainers/base:ubuntu-24.04

# Install Mise binary
COPY --from=jdxcode/mise /usr/local/bin/mise /usr/local/bin/

# Activate Mise automatically in both bash and zsh shells
RUN echo 'eval "$(mise activate bash)"' >> /home/vscode/.bashrc && \
    echo 'eval "$(mise activate zsh)"' >> /home/vscode/.zshrc

`.devcontainer.json`

{
  "build": {
    "context": "..",
    "dockerfile": "Dockerfile"
  }
}

You can spin up this environment locally using DevPod:

devpod up . --provider docker

Once inside the container, personal dotfiles give you your favorite shell customizations, while the project repository provides the exact tooling and application dependencies.

🚀 4. The GitHub Actions CI Pipeline

Now let's automate our checks. In a multi-project or monorepo workspace (e.g., lab/github-actions-devpod-ci), our workflow file lives at .github/workflows/github-actions-ci.yml at the repository root.

name: GitHub Actions DevPod CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  ci-pipeline:
    runs-on: ubuntu-latest

    defaults:
      run:
        working-directory: github-actions-devpod-ci

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install Mise
        uses: jdx/mise-action@v2
        with:
          version: latest
          install: false

      - name: Install Project Tools
        run: mise install

      - name: Run Ruff Linting
        run: mise exec -- ruff check .

      - name: Run pytest Test Suite
        run: mise exec -- pytest -vv

Key Workflow Highlights:

actions/checkout@v4: Pulls the repository code.
jdx/mise-action@v2: Sets up Mise directly on the GitHub Actions runner.
defaults.run.working-directory: Ensures every run step executes inside the specific subproject folder where mise.toml and pytest.ini reside.
mise exec -- <command>: Runs ruff and pytest using the exact tool versions managed by Mise.

🔍 The Debugging Field Guide: 7 Real-World Traps & How We Solved Them

Building pipelines in documentation looks effortless; building them in real projects always exposes subtle edge cases. Here are the real bugs encountered during implementation and the architectural principles behind fixing them.

Trap #1: "Command Not Found: pytest" (Explicit vs. Implicit Tooling)

The Symptom: After running mise install, trying to run pytest returned command not found.
The Root Cause: We assumed pytest would be installed by default because Python was present. But mise.toml only declared python = "latest".
The Fix: Explicitly declare tool requirements in mise.toml:

  "pipx:pytest" = "latest"

Core Takeaway: Never rely on ambient system tools. If your build or test process requires a binary, declare it explicitly in your version control configuration.

Trap #2: Binary Exists vs. Module Exists (`which pytest` vs. `python -m pytest`)

The Symptom: which pytest showed /home/vscode/.local/share/mise/installs/pipx-pytest/..., yet running python -m pytest resulted in No module named pytest.
The Root Cause: Standalone tools installed via pipx or Mise binary shims live in their own isolated virtual environment. The pytest executable is available on $PATH, but it is not installed as an importable package inside the main Python interpreter environment.
The Fix: Standardize on executing the standalone test runner binary directly (pytest -vv or mise exec -- pytest), rather than assuming python -m pytest inside an unbundled interpreter.

Trap #3: `ModuleNotFoundError: No module named 'src'`

The Symptom: Running pytest threw:

  ModuleNotFoundError: No module named 'src'

even though from src.main import add was written in tests/test_main.py.

The Diagnosis: Running a one-liner proved Python could import the module fine when invoked from the root:

  python -c "from src.main import add; print(add(2, 3))"
  # Output: 5

The issue was that pytest does not automatically add the current working directory to sys.path during test execution unless configured.

The Bad Workaround (Avoid This!): Copying the src/ folder into tests/. This makes tests pass temporarily but introduces duplicate code and destroys single-source-of-truth architecture.
The Clean Architectural Solution: Create a standard pytest.ini in your project root:

  [pytest]
  pythonpath = .

This cleanly tells pytest to treat the project root as part of the module search path.

Trap #4: The Relative Import Trap (`from .src.main import ...`)

The Symptom: When trying to fix the import error above, changing the import in tests/test_main.py to:

  from .src.main import add  # ❌ INCORRECT

resulted in:

  ModuleNotFoundError: No module named 'tests.src'

The Root Cause: A leading dot (.) designates a relative import within the current package (tests). Python searched for tests.src, which does not exist.
The Solution: Use standard absolute imports from the project root:

  from src.main import add, divide, multiply, subtract  # ✅ CORRECT

Trap #5: Ruff Linting vs. Guesswork

The Symptom: Ruff flagged multi-line import formatting in test files.
The Anti-Pattern: Spending 15 minutes manually reordering lines and guessing what the linter expects.
The Solution: Let Ruff fix safe formatting and import sorting automatically:

  # Automatically fix safe rule violations
  ruff check . --fix

  # Verify clean state
  ruff check .

Trap #6: Monorepo Workflow Discovery in GitHub Actions

The Symptom: You push commits containing .github/workflows/ci.yml inside a nested subproject (my-repo/subproject/.github/workflows/ci.yml), but GitHub Actions never triggers!
The Root Cause: GitHub Actions only scans the root directory of the repository for workflow files (.github/workflows/*.yml). Subdirectory workflow files are completely ignored.
The Solution: Place your workflow file at the repository root and use defaults.run.working-directory:

# Located at: .github/workflows/github-actions-ci.yml
jobs:
  ci-pipeline:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: github-actions-devpod-ci

Trap #7: Git Index & Monorepo History Mismatches

The Symptom: When staging subproject changes in a repository with existing commits, Git reported No commits yet or threw index conflicts.
The Fix: Never delete .git in frustration! Instead, inspect remote state and align:

  git status
  git remote -v
  git log --oneline --all --max-count=5
  git fetch origin
  git reset origin/main
  git restore <unmodified-sibling-folders>
  git add <project-folder>
  git commit -m "feat: add CI pipeline"

💥 5. Validating CI with Intentional Failure Injection

Here is an uncomfortable truth: A CI pipeline that only ever passed is not a proven CI pipeline.

How do you know your pipeline isn't returning a false positive because of an incorrect exit code or a misconfigured test glob?

To prove our CI pipeline actually guards the codebase, we performed a deliberate Failure Injection Test:

Step 1: Inject a Failing Assertion

In tests/test_main.py, we temporarily added:

def test_ci_failure():
    # Intentionally broken test: 2 + 2 != 5
    assert add(2, 2) == 5

Step 2: Push to GitHub & Inspect the Run

GitHub Actions immediately triggered:

✅ Checkout repository: PASSED
✅ Install Mise: PASSED
✅ Install Project Tools: PASSED
✅ Run Ruff Linting: PASSED
❌ Run pytest Test Suite: FAILED (Exit code 1)

FAILED tests/test_main.py::test_ci_failure - assert 4 == 5
========================= 1 failed, 5 passed in 0.04s =========================
Error: Process completed with exit code 1.

Step 3: Revert and Observe Recovery

After deleting the broken test and pushing again, the pipeline turned green (5/5 tests passed).

Rule of Thumb: Before shipping any CI configuration, always break a test or lint rule on purpose to ensure the pipeline halts execution with a non-zero exit code.

🧭 The 10-Step Systematic Troubleshooting Protocol

When debugging containerized environments, Python import errors, or CI runner failures, don't guess. Follow this structured protocol:

 1. Read the full error message and traceback (don't skim just the last line).
 2. Identify the exact command and working directory that failed.
 3. Determine which layer is failing (Host, Docker, DevPod, Mise, Python, Git, or CI).
 4. Verify binary paths (`which <tool>`, `mise which <tool>`).
 5. Verify runtime versions (`<tool> --version`, `python --version`).
 6. Isolate and test the smallest reproducible unit (e.g. `python -c "from src.main import ..."`).
 7. Make exactly ONE change at a time.
 8. Re-run the command under identical conditions.
 9. Confirm the fix preserves architectural clean boundaries (no copy-pasting code into test dirs!).
10. Proceed only after the root cause is resolved and verified.

🏁 Summary & Key Takeaways

Explicit is better than implicit: Declare all runtimes and tools in mise.toml rather than assuming host availability.
Decouple your layers: Keep personal dotfiles, container configurations, tool definitions, and application code in their proper places.
Use pytest.ini for import path resolution: Avoid import path hacks or relative submodule mangling.
Mind monorepo pathing in GitHub Actions: Workflows must live in .github/workflows/ at the repository root, but commands can target subdirectories via working-directory.
Always test failure modes: A quality gate is only reliable when it has been observed catching real errors.

Useful Commands Cheat Sheet

# Mise Management
mise install                # Install all tools in mise.toml
mise ls                     # List installed tools and active versions
mise which python           # Inspect active Python binary path

# Local Quality Verification
ruff check .                # Lint checks
ruff check . --fix          # Auto-fix safe lint errors
pytest -vv                  # Verbose test run
pytest --collect-only -vv   # Inspect test discovery without execution

# Python One-Liner Sanity Check
python -c "from src.main import add; print(add(2, 3))"

[github]
[linkedin]

Have you experienced tricky import bugs or CI configuration headaches in your Python projects? How do you manage tool versioning across your team? Drop your thoughts and experiences in the comments below!

From Zero to Green Build: How I Built a Jenkins + DevPod CI Pipeline with Mise (+ 10 Real Errors That Taught Me Everything)

Alan Varghese — Tue, 01 Sep 2026 15:50:41 +0000

A complete hands-on guide to building an isolated, reproducible CI pipeline with Jenkins Controller, SSH-connected DevPod agents, and Mise runtime management.

Continuous Integration (CI) setups frequently suffer from a classic problem: the "Works on My Machine" dilemma. Local development happens in nicely customized containers or modern toolchains, while CI build servers either drift into giant "snowflakes" full of globally installed packages, or run bloated custom VMs that take forever to configure and maintain.

In this project, I set out to build a modern, isolated, and fully reproducible CI lab environment:

Jenkins Controller handles scheduling and orchestration.
DevPod (Containers via SSH) provides isolated, reproducible build agents.
Mise acts as a declarative polyglot toolchain manager (mise.toml) to deterministically manage runtimes (Python, Java 21, Node.js, and Jenkins CLI) without polluting global paths.

Along the way, things did not work on the first try. I hit subtle shell differences, monorepo path traps, SSH agent quirks, and environment activation edge cases.

Here is the complete walkthrough of how the architecture works, how every file is configured, and the 10 real-world errors that taught me foundational DevOps lessons.

🏗️ Architecture & High-Level Flow

The goal was simple: separate the orchestrator from the execution environment. The Jenkins Controller should never execute heavy compilation or test tasks directly; it should delegate build execution to an ephemeral DevPod container agent over SSH.

flowchart TD
    subgraph GitHub["GitHub Repository (alanvarghese-dev/lab)"]
        Repo["Source Code & Jenkinsfile"]
    end

    subgraph Jenkins_Master["Jenkins Controller"]
        JC["Jenkins Controller\n(Scheduler & Orchestrator)"]
    end

    subgraph DevPod_Agent["DevPod Build Agent (Container)"]
        Agent["Jenkins Agent Node\n(Label: 'devpod')"]
        Mise["Mise Runtime Manager\n(mise.toml)"]
        Python["Python Runtime\n(Latest via Mise)"]
        Pytest["pytest\n(Test Suite Runner)"]
        App["Application Build\n(app.py / test_app.py)"]
    end

    Repo -->|SCM Trigger / Poll| JC
    JC -->|SSH Connection| Agent
    Agent --> Mise
    Mise --> Python
    Python --> Pytest
    Pytest --> App

Complete End-to-End Flow

GitHub (alanvarghese-dev/lab/jenkins-pipeline)
   ↓
Jenkins Controller (Orchestrates Job & evaluates Jenkinsfile)
   ↓ [SSH]
DevPod Jenkins Agent (Container with label: 'devpod')
   ↓
Mise (Resolves toolchain from mise.toml)
   ↓
Python & pip (Installs dependencies from requirements.txt)
   ↓
pytest (Executes unit test suite)
   ↓
Build Status: SUCCESS ✅

🛠️ The Tech Stack

Component	Technology	Purpose
CI Orchestrator	Jenkins	Job orchestration, pipeline stage execution, reporting
Build Agent	DevPod (Docker)	Isolated, disposable containerized build execution environment
Base Image	`mcr.microsoft.com/devcontainers/base:ubuntu-24.04`	Clean, standardized Linux environment
Tool Version Manager	Mise	Polyglot runtime versioning (Python, Java 21, Node.js, Jenkins CLI)
App Runtime & Tests	Python 3 + `pytest`	Application code (`app.py`) & unit tests (`test_app.py`)
Transport	SSH	Controller-to-Agent communication channel

📁 Repository Structure

The project lives in a monorepo setup (alanvarghese-dev/lab) designed to house multiple DevOps learning projects side by side:

lab/
└── jenkins-pipeline/
    ├── .devcontainer.json      # Devcontainer build definition
    ├── Dockerfile              # DevPod agent image with Mise
    ├── Jenkinsfile             # Declarative Jenkins CI pipeline
    ├── mise.toml               # Tool versions (Java, Python, Node, CLI)
    ├── app.py                  # Sample Python application
    ├── test_app.py             # Pytest test suite
    ├── requirements.txt        # Python dependencies (pytest)
    └── README.md               # Project documentation

⚙️ Step-by-Step Configuration

1. Devcontainer Agent Image (`Dockerfile` & `.devcontainer.json`)

To build our DevPod agent with Mise pre-baked, we copy the binary directly from the official Mise multi-stage Docker image:

# Dockerfile
FROM mcr.microsoft.com/devcontainers/base:ubuntu-24.04

COPY --from=jdxcode/mise /usr/local/bin/mise /usr/local/bin/

# Activate mise in interactive shells
RUN echo 'eval "$(mise activate bash)"' >> /home/vscode/.bashrc && \
    echo 'eval "$(mise activate zsh)"' >> /home/vscode/.zshrc

And configure the .devcontainer.json:

{
  "build": {
    "context": "..",
    "dockerfile": "Dockerfile"
  }
}

2. Declarative Toolchain (`mise.toml`)

Instead of installing packages globally via apt-get or installing random pythons across system directories, we declare all required tooling in mise.toml:

[tools]
"aqua:jenkins-zh/jenkins-cli" = "latest"
python = "latest"
java = "21"
node = "latest"

Because this file is checked into version control, any developer opening the container with DevPod or any CI agent running Jenkins gets the exact same runtime versions.

3. The Application & Pytest Suite

Keep the application minimal so you can focus 100% on pipeline predictability:

# app.py
def hello():
    return "Hello from Jenkins + Devpod!"

if __name__ == "__main__":
    print(hello())

# test_app.py
from app import hello

def test_hello():
    assert hello() == "Hello from Jenkins + Devpod!"

# requirements.txt
pytest

4. The Declarative Jenkins Pipeline (`Jenkinsfile`)

Here is the complete Jenkinsfile. Notice two critical patterns:

dir('jenkins-pipeline'): Because this is a monorepo, we explicitly change into the project directory so Mise can find mise.toml.
mise exec python -- ...: We avoid brittle shell activation scripts and let Mise directly wrap command execution.

pipeline {
    agent {
        label 'devpod'
    }

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Setup Python') {
            steps {
                dir('jenkins-pipeline') {
                    sh '''
                        set -e
                        echo "Project directory:" && pwd
                        echo "Mise configuration:" && ls -la mise.toml
                        mise install
                        echo "Python version:"
                        mise exec python -- python --version
                    '''
                }
            }
        }

        stage('Install Dependencies') {
            steps {
                dir('jenkins-pipeline') {
                    sh '''
                        set -e
                        mise exec python -- python -m pip install -r requirements.txt
                    '''
                }
            }
        }

        stage('Test') {
            steps {
                dir('jenkins-pipeline') {
                    sh '''
                        set -e
                        mise exec python -- python -m pytest
                    '''
                }
            }
        }
    }

    post {
        success { echo 'Python CI build successful! 🚀' }
        failure { echo 'Python CI build failed! ❌' }
    }
}

💥 10 Real Errors Encountered & What They Taught Me

Building CI pipelines is 10% writing code and 90% debugging subtle environment mismatches. Here are the 10 errors I hit during this lab and the lessons behind them:

1. DevPod Container Created, but Features Failed

Symptom: The container was created in Docker, but DevPod reported connection and tunneling errors.
Lesson: Container creation and DevPod connectivity are distinct stages. Always ensure: Container Running ➔ DevPod SSH Access ➔ Shell Available before troubleshooting build tools.

2. "No SSH session / exited"

Symptom: DevPod SSH tunneling abruptly dropped.
Lesson: This was an infrastructure/connection issue, not a Jenkins or Python failure. Once devpod ssh succeeded reliably from the terminal, the underlying transport was proven stable.

3. Dotfiles Were Not Applied

Symptom: The agent container spun up without customized shell dotfiles.
Lesson: DevPod’s automated dotfiles mechanism requires setup scripts to be located in conventional locations.

4. "Setup not found"

Symptom: DevPod searched for bootstrap files (install.sh, bootstrap.sh, setup.sh) and couldn't find them.
Lesson: Automation tools depend on strict conventions. Always verify standard entry points when integrating dotfiles repositories into devcontainers.

5. GitHub SSH Authentication Confusion

Symptom: Output showed: Hi username! You've successfully authenticated, but GitHub does not provide shell access.
Lesson: This is actually a success message from GitHub confirming that your SSH public key is valid. GitHub explicitly denies interactive PTY shells, so don't mistake this for an authentication failure!

6. `java: command not found` (The Non-Interactive Shell Trap)

Symptom: Java 21 was installed inside DevPod, but Jenkins reported java: command not found.
Lesson: Installed on disk ≠ Available to the Jenkins process. When you log in via devpod ssh, your .zshrc / .bashrc loads your PATH. Jenkins launches a non-interactive /bin/sh shell that skips interactive rc files.

Interactive Login:   .zshrc / .bashrc loaded ➔ PATH configured ➔ Tools work
Jenkins Non-Login:   /bin/sh launched        ➔ Minimal PATH    ➔ Command not found

7. "Python is installed but not activated"

Symptom: Mise reported that Python was installed on the machine, but not active.
Lesson: Mise relies on discovering a valid mise.toml in the current directory or parent tree. If you are in a directory without a config, Mise will not activate the tool by default.

8. `Syntax error: "(" unexpected` on `eval "$(mise activate bash)"`

Symptom: Attempting to evaluate Mise activation inside a Jenkins sh step blew up with a syntax error.
Lesson: Jenkins defaults to /bin/sh (often Debian/Ubuntu dash), which does not support certain Bash/Zsh process substitution or subshell syntax.
Solution: Instead of hacking shell startup scripts, use mise exec <tool> -- <command> directly in pipeline steps!

9. Mise Could Not Find Python in Monorepo Root

Symptom: mise exec -- python --version failed in Jenkins.
Root Cause: Jenkins checked out the entire monorepo (lab/), and executed commands at the root. The mise.toml was inside lab/jenkins-pipeline/.
Fix: Use Jenkins' dir('jenkins-pipeline') { ... } block so the working directory matches where mise.toml lives.

10. Git "Does not have a commit checked out"

Symptom: Git commands failed unexpectedly inside the agent.
Root Cause: Commands ran from /workspaces instead of /workspaces/jenkins-pipeline.
Lesson: Always verify your working directory before running Git operations: pwd && git status.

🔍 The 5-Step CI Troubleshooting Checklist

Whenever your Jenkins build fails with a "command not found" or tool version issue, run through this checklist before touching code:

flowchart TD
    A["1. Is the tool installed?\n(mise ls)"] -->|Yes| B["2. Where is the binary?\n(mise which <tool>)"]
    B --> C["3. Is mise.toml in the directory?\n(ls -la mise.toml)"]
    C --> D["4. Is Jenkins in the right folder?\n(pwd)"]
    D --> E["5. Can Mise execute it?\n(mise exec <tool> -- <cmd>)"]
    A -->|No| F["Run: mise install"]

Is the tool installed?

   mise ls

Where is the binary located?

   mise which python
   mise which java

Is mise.toml present in the current folder?

   ls -la mise.toml

What is Jenkins' current working directory?

pwd

Can Mise execute the tool directly?

   mise exec python -- python --version

💡 Key Architectural Takeaways

Infrastructure First, Application Second: Get your container running, SSH passing, and agent labeled before spending time configuring application test suites.
Separate Orchestration from Execution: Keep the Jenkins Controller lean. Run builds inside disposable agents.
Embrace Deterministic Toolchains: Using mise.toml ensures that both local devcontainer sessions and remote CI builds use the exact same runtime versions.
Never Rely on Interactive Shell Environments in CI: Avoid complex .bashrc / .zshrc sourcing in CI. Use explicit CLI wrappers like mise exec to execute binaries cleanly.

🗺️ What's Next on the DevOps Roadmap?

This Jenkins + DevPod CI lab is the foundation of my broader homelab DevOps monorepo (alanvarghese-dev/lab):

lab/
├── jenkins-pipeline/    # ✅ Jenkins + DevPod SSH CI Pipeline (Completed!)
├── docker/              # 🔜 Multi-stage builds & container optimization
├── kubernetes/          # 🔜 K8s deployment manifests & Helm charts
├── terraform/           # 🔜 Infrastructure as Code (IaC)
└── gitops/              # 🔜 GitOps automated delivery with ArgoCD / Flux

💬 Discussion

Have you tried using DevPod or containerized SSH agents with Jenkins? How do you handle tool versioning in your CI runners? Let me know in the comments below!

[github]

[linkedin]

Automate Your Linux Updates Like a Pro (with Rollbacks!) 🚀

Alan Varghese — Tue, 01 Sep 2026 15:27:22 +0000

Running sudo apt-get update && sudo apt-get upgrade -y is fine for your local dev machine. But when you're managing multiple Ubuntu or Debian servers, manual updates are a recipe for disaster.

One day, a kernel update will break a driver, or a library conflict will brick a service. If you don't have a history of what was installed or a way to roll back, you're in for a long night of troubleshooting.

I built System Update Manager, a production-ready Bash tool that treats system updates like a CI/CD pipeline.

The Problem with "Yolo-Upgrading"

No Audit Trail: Did that server crash because of an update 2 hours ago or a config change?
The "Point of No Return": Once apt finishes, knowing exactly which versions were upgraded is a pain.
Concurrency Issues: Running multiple update scripts at once can lock the dpkg database.

My Solution: System Update Manager

This isn't just a wrapper for apt. It’s a full management suite designed for reliability.

Key Features 🛠️

SQLite History Tracking: Every update attempt is logged in a local database. You can see the start time, duration, exit codes, and exactly which packages changed.
Pre-update Snapshots: Before touching a single byte, it snapshots your package list.
Automated Rollback Scripts: If an update fails, the tool generates a standalone .sh script that uses apt-get install --allow-downgrades to bring your system back to its previous state.
Native Automation: It ships with Systemd timer and Cron configurations out of the box.
Lock Management: Uses file-based locking to ensure only one instance is running.

How It Works

The script follows a strict lifecycle for every update:

Pre-flight Check: Validates root privileges and disk space.
Locking: Acquires a lock file to prevent concurrent runs.
Snapshot: Records current package versions in SQLite.
Update: Executes apt-get update and upgrade with configurable retries.
Recovery: If a failure occurs, it immediately generates a rollback script.
Logging: Records the outcome and duration.

A Peek at the Status UI

I wanted the CLI to be readable at a glance:

╔══════════════════════════════════════════════════════╗
║          SYSTEM UPDATE MANAGER - STATUS              ║
╠══════════════════════════════════════════════════════╣
║ Status: SUCCESS                                     ║
║ Start Time:  2024-03-24 03:00:00                    ║
║ End Time:    2024-03-24 03:05:23                    ║
║ Exit Code:   0                                      ║
╚══════════════════════════════════════════════════════╝

Getting Started

If you want to try it out (or use it in your own homelab/prod environment), here is the quick start:

# Clone it
git clone https://github.com/yourusername/automated_system_update_manager.git
cd automated_system_update_manager

# Check for updates without changing anything
./update_manager.sh --check

# Run a manual install
sudo ./update_manager.sh --install

Automation via Systemd

The cleanest way to run this is via a Systemd timer. It’s more modern than Cron and integrates perfectly with journalctl.

sudo cp systemd/update-manager.* /etc/systemd/system/
sudo systemctl enable --now update-manager.timer

Now your system will update daily at 3 AM, and you can sleep soundly knowing there's a rollback script waiting if things go south.

Lessons Learned

Building this project reminded me that Bash is still a superpower. By combining simple Unix tools like grep, awk, and sqlite3, you can build incredibly robust infrastructure tools without the overhead of a heavy Python or Go binary.

What do you use to manage updates on your servers? Let me know in the comments! 👇

From 'src refspec' Errors to Clean PRs: The Practical Git Branching Workflow You Need

Alan Varghese — Thu, 20 Aug 2026 04:38:46 +0000

We’ve all been there: pushing straight to main, writing commit messages like "fix stuff", and dreading the moment someone mentions merge conflicts or branch topology.

When you're building solo, you can get away with git add . and git push origin main. But the moment you collaborate with a team, work in an open-source project, or maintain production software, messy Git habits quickly turn into broken builds and lost code.

In this post, I’ll walk you through a practical, lightweight Git branching workflow modeled on real-world team practices (often called Git Flow Light). We'll set up a project, create feature branches, use the GitHub CLI (gh) for Pull Requests, intentionally create and resolve a merge conflict, and cover the most common Git errors you will face along the way.

🧠 1. The Mental Model: What's Actually Happening in Git?

Before typing commands into the terminal, let’s demystify two core Git mechanics that make everything click:

The Three-Tree Architecture

Git doesn’t just copy your files to the cloud; it manages changes across three distinct zones:

[ Working Directory ]  --->  `git add`  --->  [ Staging Area (Index) ]  --->  `git commit`  --->  [ Repository History ]
 (Live files on disk)                           (The box you're packing)                             (Committed snapshots)

Working Directory: The actual physical files you are editing in VS Code.
Staging Area (Index): The draft snapshot. It holds a copy of your staged changes, not a live reference.
Repository (.git): The permanent history of committed snapshots.

Branches Are Just Cheap Pointers

In Git, creating a branch does not duplicate your entire codebase or take up disk space. A branch is merely a 40-character text file containing the commit SHA it points to.

When you create a branch, Git creates a new pointer.
HEAD simply indicates which pointer your working directory is currently tracking.

(develop) ─── [ C1 ] ─── [ C2 ] ─── [ C3 ] (HEAD -> feature/todo-ui)

🌳 2. The Branching Strategy (Git Flow Light)

For most teams and personal projects, a 3-tier structure provides the perfect balance between stability and agility without the over-engineering of full Git Flow:

Branch	Purpose	Rule
`main`	Production-ready releases	Only receives tested code from `develop`. Tagged with version numbers (e.g., `v1.0.0`).
`develop`	Integration branch	Where all finished features land and are tested together.
`feature/*`	Isolated task or component	Forked from `develop`, merged back via Pull Request, and deleted after merge.

🚀 3. Step-by-Step Workflow in Action

Let’s trace a real project scenario: setting up a clean repository and building a small Todo App.

Step 1: Initialize and Configure

# Initialize git in your project directory
git init

# Configure identity (if not already set globally)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Step 2: Establish `main` and `develop`

Always make sure you have an initial commit before trying to manage branches:

# Create the initial files
touch index.html style.css app.js

# Stage and commit baseline
git add .
git commit -m "feat: initial project structure"

# Ensure main is the active branch
git branch -M main

# Connect to GitHub remote
git remote add origin https://github.com/your-username/todo-app.git

# Push main and set upstream
git push -u origin main

# Create and switch to develop branch
git checkout -b develop
git push -u origin develop

Step 3: Work on an Isolated Feature Branch

Never write code directly on develop or main. Whenever you start a new task, fork a feature branch from develop:

# Ensure you are on latest develop
git checkout develop
git pull origin develop

# Cut a new feature branch
git checkout -b feature/add-task-ui

Make your code updates in index.html:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>To-Do List</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>
    <div class="app">
        <h1>My To-Do List</h1>
        <input type="text" id="new-task" placeholder="Add a new task...">
        <button id="add-btn">Add</button>
        <ul id="task-list"></ul>
    </div>
    <script src="app.js"></script>
</body>
</html>

Stage and commit with a descriptive message:

# Check what changed
git status

# Stage & commit
git add index.html
git commit -m "feat(ui): add basic task input structure and markup"

# Push feature branch to remote
git push -u origin feature/add-task-ui

📬 4. Pull Requests as Quality Gates (Using GitHub CLI)

Instead of manually clicking through the GitHub web UI, you can streamline the review process using the GitHub CLI (gh):

Creating the PR to `develop`:

gh pr create --base develop --head feature/add-task-ui --title "feat: Add Task UI" --body "Implements initial HTML structure for task input and listing."

Merging and Cleaning Up:

Once the PR passes checks (or code review):

# Merge with a merge commit to preserve branch topology and delete the remote branch
gh pr merge --merge --delete-branch

# Switch back locally and sync
git checkout develop
git pull origin develop

# Clean up the local feature branch
git branch -d feature/add-task-ui

💥 5. Merge Conflicts: Demystified & Conquered

Merge conflicts occur when Git cannot automatically reconcile two different changes made to the same lines of a file across different branches.

The Conflict Setup Scenario

Imagine two developers (or two branches) modify the heading in index.html at the same time:

Branch develop has:

  <h1>My Daily To-Do List</h1>

Branch feature/update-ui has:

  <h1>My To-Do Tasks</h1>

When you attempt to merge feature/update-ui into develop:

git checkout develop
git merge feature/update-ui

Git halts the process and warns:

CONFLICT (content): Merge conflict in index.html
Automatic merge failed; fix conflicts and then commit the result.

Anatomy of Conflict Markers

Open index.html, and you will see Git's conflict markers:

<<<<<<< HEAD (Current change on develop)
        <h1>My Daily To-Do List</h1>
=======
        <h1>My To-Do Tasks</h1>
>>>>>>> feature/update-ui (Incoming change)

How to Resolve It:

Decide on the correct code (e.g., combine or pick one version).
Delete the marker lines (<<<<<<<, =======, >>>>>>>).
Save the file:

   <h1>My Daily To-Do Tasks</h1>

Stage and commit the resolution:

   git add index.html
   git commit -m "fix(merge): resolve heading text conflict between develop and feature/update-ui"

🏷️ 6. Releasing to Production (`main`) & Tagging

Once develop contains a stable set of merged features and has been tested, merge it into main and tag the release:

# Switch to main and merge develop
git checkout main
git pull origin main
git merge develop --no-ff -m "chore(release): merge develop into main for v1.0.0"

# Tag the milestone
git tag -a v1.0.0 -m "Release version 1.0.0 - Initial working Todo App"

# Push main and tags to remote
git push origin main
git push origin v1.0.0

⚠️ 7. The Wall of Common Git Errors (& Exact Fixes)

Save this cheat sheet for when terminal errors strike:

Error Message	Why It Happened	How to Fix It
`fatal: not a git repository`	You ran a git command outside the project folder.	`cd` into your actual repository root directory.
`src refspec main does not match any`	You tried to push `main` before creating at least one commit.	Create an initial commit: `git commit --allow-empty -m "init"` then push.
`base ref must be a branch` / `base sha can't be blank`	Opening a PR to `--base develop` when `develop` hasn't been pushed to remote.	Push the base branch first: `git push -u origin develop`.
`no commits between dev and feat`	The feature branch has no unique commits ahead of `develop`.	Make changes and commit them on the feature branch first.
`CONFLICT (content): Merge conflict in <file>`	Concurrent edits to the exact same lines across branches.	Open the file, remove `<<<<<<<`/`=======`/`>>>>>>>`, pick the final code, `git add .`, and `git commit`.
`default branch is invalid`	Tried to change default branch to `main` before `main` exists remotely.	Push `main` to remote first: `git push -u origin main`, then update repo settings.
`git diff` shows nothing after editing	You forgot to save the file in your code editor.	Hit `Ctrl+S` / `Cmd+S` in your editor, then re-run `git diff`.

💡 Pro Tips for a Smoother Git Life

git status is your reflex: Run it before git add and before git commit. Always know what is staged versus unstaged.
Use visual history logs: Run git log --oneline --graph --all to see a ASCII branch tree of your entire repository history.
Keep branches short-lived: Large, long-living feature branches are conflict magnets. Break work into small, bite-sized PRs.
Prune stale remote references: Run git fetch --prune periodically to remove local references to branches that were deleted on GitHub.
Write semantic commit messages: feat:, fix:, docs:, refactor:. Your future self and teammates will thank you.

💬 Over to You!

What is your team's favorite Git workflow? Have you ever had a legendary merge conflict disaster? Drop your thoughts or questions in the comments below! 👇

Build a Lightweight File Integrity Monitor with Bash, SQLite, and Docker

Alan Varghese — Tue, 24 Mar 2026 10:57:51 +0000

In the world of server security, File Integrity Monitoring (FIM) is a critical layer of defense. It's the "silent alarm" that tells you when a configuration file, a system binary, or a sensitive database has been tampered with.

While there are enterprise grade tools like Tripwire or OSSEC, sometimes you need something lightweight, transparent, and easy to deploy.

In this post, I’ll walk you through a project I built: a Bash based File Integrity Checker that uses SQLite for baseline storage and Docker for a fully isolated testing environment.

🚀 The Core Concept: Baseline vs. Reality

The tool works on a simple but powerful principle:

Initialize (--init): Scan your critical files, calculate their SHA-256 hashes, and store them in a persistent SQLite database. This is your "known-good" state.
Check (--check): Periodically re-scan those same files. If a single bit has changed, the hashes won't match, and an alert is triggered.

🛠️ The Tech Stack

Bash: The engine. It handles the file traversal, hashing logic, and alerting.
SQLite3: Instead of messy text files, I used SQLite to store the baseline. It’s fast, structured, and handles hundreds of files with ease.
Docker & Docker Compose: To make testing easy, I containerized the entire app.
MailHog: A "superpower" for development. It's a mock SMTP server that catches all outgoing alert emails so you can verify them in a web UI without spamming your real inbox.

🔍 A Deep Dive into the Code

1. The Hashing Logic

We use sha256sum to ensure high cryptographic security. Even a tiny change to a file (like adding a space) results in a completely different hash.

# Calculate hash and store in database
current_hash=$(sha256sum "$file_path" | awk '{print $1}')
sqlite3 "$DB_PATH" "INSERT INTO file_hashes (file_path, hash) VALUES ('$file_path', '$current_hash');"

2. Multi Layered Alerting

One of the biggest challenges in shell scripting is ensuring email delivery. My script uses a "fallback" strategy:

Primary: ssmtp (sendmail) via the local system.
Secondary: curl to talk directly to the MailHog API.
Last Resort: Standard mail command.

🐳 The Docker Testing Workflow

Testing a security tool can be nerve wracking you don't want to accidentally modify your host's /etc/ files! That’s where Docker shines.

I created a docker-compose.yml that spins up:

An Ubuntu-based checker container with mock system files.
A MailHog container for email visualization.

How to test a "Malicious" change:

Start the environment:

   docker-compose up -d

Create the baseline:

   docker exec -it file_integrity_checker bash /app/file_integrity_checker.sh --init

Simulate a hack:

   docker exec -it file_integrity_checker bash -c "echo 'MALICIOUS_CODE' >> /etc/myapp/config/app.yaml"

Run the check:

   docker exec -it file_integrity_checker bash /app/file_integrity_checker.sh --check

See the alert: Open http://localhost:8025 and watch the security alert arrive in your MailHog inbox!

💡 Key Lessons Learned

Volume Mounts & Permissions: When mounting files from macOS to a Linux container, file permissions (like the execute bit) can be tricky. I learned that executing via bash <script> is often more robust than relying on the +x bit in a shared volume.
Architecture Matters: Adding platform: linux/amd64 to the docker-compose.yml was essential for ensuring the MailHog image (which is AMD64 only) runs smoothly on modern ARM64 chips like the Apple M1/M2.

🏁 Conclusion

Building your own security tools is one of the best ways to understand how systems work. This project taught me about hashing, database persistence in shell, and the power of Docker for creating reproducible security labs.

What's next for this project? I'm looking into adding Slack/Discord webhook support and real time monitoring via inotify.

Thanks for reading! If you have questions about Bash security or Docker setups, let's chat in the comments! 🛡️

Monitoring Remote Network Health: Building a Lightweight Connectivity Tool with Bash and Docker

Alan Varghese — Mon, 09 Mar 2026 12:26:06 +0000

Have you ever needed to verify if your remote servers have outbound internet access? Whether you're managing a cluster of web servers or a set of edge devices, ensuring they can "talk to the world" is a fundamental task.

In this post, I'll walk you through a lightweight Network Connectivity Monitoring Tool I built using Bash. It's simple, portable, and comes with a Docker-based test environment to get you started safely.

The Problem

Manually SSH-ing into dozens of servers to run a ping command is tedious and error-prone. I needed a way to:

Check connectivity from multiple servers at once.
Support non-standard SSH ports.
Log results for historical tracking.
Get a quick summary of which hosts are "Reachable" vs "Unreachable."

The Solution: A Bash-Powered Monitor

The core of this tool is a Bash script that uses SSH to execute a ping command on remote targets. Here's a look at the key features and how it works.

1. Robust Scripting with `set -euo pipefail`

To make the script reliable, I used strict error handling:

-e: Exit immediately if a command fails.
-u: Treat unset variables as errors.
-o pipefail: Ensure that if any part of a pipeline fails, the whole pipeline fails.

2. Intelligent Connectivity Checks

The script doesn't just check if the server is "up"; it distinguishes between an SSH failure (can't connect to the box) and a Network failure (connected to the box, but the box can't reach the internet).

# A snippet of the core logic
if ssh -o StrictHostKeyChecking=no -o BatchMode=yes -p "${port}" "${ssh_target}" \
       "ping -c 3 8.8.8.8 > /dev/null 2>&1"; then
    log_result "$host" "REACHABLE" "$TIMESTAMP"
    echo "  ✓ $host - REACHABLE"
else
    log_result "$host" "UNREACHABLE" "$TIMESTAMP"
    echo "  ✗ $host - UNREACHABLE (network issue)"
fi

3. Automated Logging & Summaries

Every run generates a timestamped log in connectivity_log.txt, making it easy to spot patterns over time. At the end of each run, you get a clean summary:

========================================
  Summary
========================================
  Total hosts checked: 3
  Reachable:          2
  Unreachable:        1
========================================

Testing Safely with Docker

One of the best parts of this project is the included Test Lab. Using docker-compose, you can spin up three Ubuntu-based SSH servers locally to test the script without risking your production environment.

I've included a setup.sh script that:

Starts the containers.
Installs ping (not present in minimal Ubuntu images).
Configures SSH keys for passwordless login.
Validates the environment.

How to Try It Out

Clone the project.
Generate an SSH key if you haven't already: ssh-keygen -t rsa.
Launch the test lab:
```
./setup.sh
```
Run the monitor:
```
./monitor_connectivity.sh
```

Lessons Learned

While building this, I ran into a few classic Bash "gotchas":

Loops vs set -e: Using a while read loop with set -e can cause the script to exit prematurely when it hits the end of a file. Switching to a for loop with grep solved this.
Docker Ephemerality: Since containers reset on restart, I automated the SSH key injection into the setup.sh script to ensure a smooth developer experience.

Conclusion

Sometimes, the simplest tools are the most effective. This Bash script provides a no-nonsense way to monitor network health across your infrastructure.

Check out the full source code here! github

What are your favorite "mini-tools" for server management? Let me know in the comments!

How I Built a Lightweight Cron Job Health Monitor with Bash and Docker

Alan Varghese — Sun, 08 Mar 2026 18:16:58 +0000

Tired of silent cron failures? Here's a lightweight Bash-based solution to monitor and alert on your scheduled tasks across multiple servers.

Why Your Cron Jobs Need Monitoring

We’ve all been there. You set up a "mission-critical" backup or data sync as a cron job, and then you forget about it. Six months later, you realize it hasn't run in weeks because of a silent failure, a disk space issue, or an SSH key change.

Cron is great for execution, but it's terrible at visibility.

In this post, I'll walk through a lightweight, Bash-powered monitoring solution I built to keep tabs on cron jobs across multiple servers without needing a heavy agent like Zabbix or Datadog.

🛠 The Architecture

The goal was simple:

Discover jobs automatically from remote servers via SSH.
Monitor their last execution time.
Alert via Slack or Email if a job is "missed" or overdue.
Test everything locally using Docker.

┌───────────────────────────────┐
│        Monitoring Host        │
│  (Bash + cron_health_monitor) │
└───────────────┬───────────────┘
                │
        ┌───────┴───────┐
        ▼               ▼
  ┌──────────┐    ┌──────────┐
  │ Server A │    │ Server B │
  │ (Docker) │    │ (Docker) │
  └──────────┘    └──────────┘

🚀 Key Features

1. Automated SSH Discovery

The script scans crontab -l on remote servers, parses the schedules, and automatically adds them to its tracking list. No more manual entry for every single task.

2. State-Based Tracking

Instead of checking logs (which can be messy), the monitor looks at "last run" timestamps. Jobs can report their own completion via a simple CLI command:

./cron_health_monitor.sh record backup_job server1

3. Dockerized Testing Environment

To ensure the monitor works before deploying it to production, I included a docker-compose.yml that spins up three Ubuntu servers. This allows you to simulate real-world cron failures in a safe sandbox.

🧩 The "Aha!" Moments (and Bugs)

While building this, I ran into a few classic engineering hurdles:

The Date Dilemma: I initially used BSD-style date commands (macOS default), which broke completely on the Linux target servers. I had to switch to the more universal GNU date -d syntax.
Docker Networking: On macOS, connecting to localhost inside a container can be tricky. Switching to 127.0.0.1 fixed several "Host not found" errors.
Silent Failures: I learned that if the SSH connection fails, the script should alert on the connection failure, not just the missing cron job.

🛠 Quick Start

If you want to try it out:

Clone & Setup:

   ./setup.sh # Generates keys & starts Docker test servers

Discover Jobs:

   ./cron_health_monitor.sh discover

Run Health Check:

   ./cron_health_monitor.sh check

💡 Lessons Learned

Bash is incredibly powerful for infrastructure glue code. By combining standard tools like ssh, awk, and grep, you can build a monitoring system that is:

Zero-agent: Nothing to install on target servers.
Low-overhead: Runs in milliseconds.
Portable: Works on almost any Linux distro.

Check out the full source code and my "bug log" in the repository!

https://github.com/alanvarghese-dev/Bash_Scripting/tree/main/cron_job_health_monitor

What are you using to monitor your legacy cron jobs? Let's discuss in the comments!

Stop SSH-ing One by One: Building a Parallel Command Executor in Bash

Alan Varghese — Thu, 05 Mar 2026 20:29:19 +0000

Learn how to build a robust, multi-server SSH command runner using Bash, Docker, and parallel processing.

As developers or system administrators, we've all been there: You need to check the disk space, uptime, or service status on 10 different servers.

The "manual" way is painful:

ssh user@server1 -> df -h -> exit
ssh user@server2 -> df -h -> exit
...repeat 8 more times. 😫

Sure, tools like Ansible exist, but sometimes you just want a lightweight, zero-dependency script to fire off a quick command and see what's happening right now.

In this post, I'll walk you through how I built a Multi-Server SSH Executor using pure Bash. We'll explore parallel processing, robust file parsing, and how to simulate a server cluster locally using Docker.

🎯 The Goal

We want a script that takes a command (e.g., uptime) and runs it on a list of servers defined in a config file.

Requirements:

Parallel Execution: Use threading (background processes) so checking 10 servers takes as long as the slowest one, not the sum of all of them.
Robust Config Parsing: Handle comments, weird whitespace, and different ports/users.
Local Testing Ground: A way to test this without buying 5 VPS instances (spoiler: we use Docker).

🏗️ The Architecture

The project consists of three main parts:

servers.conf: A simple file defining our target servers.
multi_ssh.sh: The brains of the operation.
docker-compose.yml: A simulated lab environment with 4 SSH-enabled containers.

1. The Configuration

I wanted a simple format that's easy to read but flexible:
name:hostname:port:username

# Production Servers
web01:192.168.1.10:22:admin
db01:192.168.1.20:22:dbadmin

# Docker Lab (Localhost mapped ports)
web1:localhost:2221:root
web2:localhost:2222:root

2. The Simulation (Docker Lab)

Testing SSH scripts on production servers is... brave. Instead, I used docker-compose to spin up lightweight Ubuntu containers running sshd.

services:
  web1:
    image: rastasheep/ubuntu-sshd:18.04
    ports: ["2221:22"]
  web2:
    image: rastasheep/ubuntu-sshd:18.04
    ports: ["2222:22"]

Now I have "real" servers running on localhost ports 2221, 2222, etc.

⚡ The "Secret Sauce": Parallelism in Bash

The core challenge is running commands simultaneously. In Bash, we do this by putting a command in the background with &.

Here is the simplified logic:

# Loop through servers
for server in "${servers[@]}"; do
    # Run SSH in the background
    ssh $user@$host "$command" > "/tmp/result_$server.txt" &

    # Save the Process ID (PID)
    pids+=($!)
done

# Wait for all background jobs to finish
wait

This simple trick reduces execution time from (N * Timeout) to (Max(Timeout)).

🧠 Lessons Learned & "Gotchas"

Writing the script revealed a few common Bash pitfalls that I had to fix to make it production-ready.

Lesson 1: `for` loops vs. `while read`

Initially, I used a for loop to read lines from the config file.
The Trap: If a line has spaces (like a description), for splits it into multiple items.
The Fix: Use a while loop with a custom Internal Field Separator (IFS).

# Robust way to read lines
while IFS=':' read -r name hostname port username || [[ -n "$name" ]]; do
    # Process server...
done < "$config_file"

Note the || [[ -n "$name" ]] part—this ensures we don't skip the last line if the file doesn't end with a newline character!

Lesson 2: Race Conditions & Temp Files

When running parallel jobs, you can't just write to output.txt. Multiple processes will write at the same time, garbling the text.
The Fix: Give each process its own temporary file (e.g., /tmp/ssh_result_web1.txt), let them finish, and then aggregate the results sequentially.

I used mktemp to ensure my temporary files never collided with other running instances of the script.

SERVERS_LIST_TMP=$(mktemp /tmp/ssh_multi_servers.XXXXXX)

Lesson 3: SSH is picky

Running SSH non-interactively requires specific flags to avoid hanging:

-o BatchMode=yes: Fail instead of asking for a password.
-o ConnectTimeout=X: Don't wait forever if a server is down.
-o StrictHostKeyChecking=no: Crucial for automated environments where IPs might change (like Docker containers).

🚀 The Result

Running ./multi_ssh.sh "df -h" gives me a beautiful, color-coded summary of disk space across my entire fleet in seconds.

📥 Try It Yourself

I've open-sourced this tool along with the setup script that automatically generates SSH keys and configures the Docker containers for you.

Prerequisites:

Docker & Docker Compose
sshpass (for the initial setup script)

Installation:

git clone https://github.com/alanvarghese-dev/Bash_Scripting/tree/main/ssh_multi_server_executor.git

cd ssh-multi-server-executor
./ssh_install.sh  # Sets up the Docker lab
./multi_ssh.sh "uptime"

Let me know in the comments if you prefer Bash for these tasks or if you stick to heavier tools like Ansible!

Happy scripting! 💻✨

DEV Community: Alan Varghese

How I Slashed a Docker Image from 442 MB to 56 MB (87% Cut) and Hardened It for Production

🛑 The "Before": A Naive, Bloated Baseline

What Went Wrong Here?

🛠️ The 6-Step Optimization Playbook

Step 1: Switch to a Minimal Base Image (-slim)

Step 2: Ruthlessly Prune Unnecessary OS Packages

Step 3: Add a Scrupulous .dockerignore

Step 4: Master Layer Caching (Order Matters!)

Step 5: Adopt a Production WSGI Server (Gunicorn)

Step 6: Hardening Security — Run as Non-Root

🏆 The "After": Hardened & Optimized Dockerfile

📊 The Scorecard: Baseline vs. Optimized

🥊 Real-World Gotchas & Lessons Learned

1. The "Host Port Already in Use" Trap

2. "Disk Usage" vs "Content Size"

3. Never Optimize Without Validation

💡 Quick Docker Optimization Checklist for Your Projects

💬 Over to You!

Building a Multi-Container App with Docker Compose: 10 Real-World Gotchas and Lessons Learned

🏗️ The Application Architecture

Port Mappings at a Glance

💥 10 Real-World Gotchas & Lessons Learned

1. The DevPod / Docker Socket Permission Trap

Why It Happens

The Wrong Fix vs. The Right Fix

2. Host Port vs. Container Port Confusion

The Trap

3. Frontend-to-Backend Port Mismatch

The Fix

4. The CORS Paradox: When HTTP 200 Still Fails

The Insight

The Fix

5. The Phantom Disconnection: Environment Variable Misalignment

The Culprit

The Fix

6. Container-to-Container DNS vs. localhost

The Docker Solution

7. Verifying True Data Persistence (and the Dangerous -v Flag)

8. Health Checks: Running vs. Ready

The Solution: Healthcheck + condition: service_healthy

9. Pytest in Dev Environments vs. Docker Integration Tests

Strategy

10. The Systematic 6-Step Debugging Workflow

🚀 Key Takeaways

💬 Discussion

From Code to Container: What Building & Debugging My First Dockerized App Taught Me About Real-World DevOps

🛠️ The Architecture & The Environment

How the Pieces Fit Together

🐍 1. The Application & The Dockerfile

💡 Lesson 1: Build Order & Layer Caching Matter

⚡ 2. The DevPod Challenge: The "Docker-in-Docker" Socket Mystery

What was happening?

The Permissions Curveball: srw-rw---- root root

🌐 3. Networking Lessons: The Tale of Two IP Addresses & Port Mapping

Why 0.0.0.0 vs. 127.0.0.1?

The Port Conflict: 5001:5000

🧪 4. Testing at Every Layer

Step 1: Test directly inside the container

Step 2: Test from the host via published port

🧠 5. The Golden Rule of DevOps Debugging: Isolate the Layers

🧰 My Essential Docker Toolkit

🔮 What’s Next on the Roadmap?

💬 Over to You!

Zero to Published: Building an Automated Release Pipeline with GitHub Actions, Mise, and DevPod

🏗️ Architecture & Monorepo Layout

📦 Step 1: Isolated Environment with DevPod & Mise

1. DevPod Configuration

2. Declarative Tooling with mise.toml

🧪 Step 2: Application Code & Quality Gates

1. The Application (app.py)

2. Unit Testing with Pytest (tests/test_app.py)

3. Configuring Pytest (pytest.ini)

4. Local Verification Commands

⚡ Step 3: CI/CD Pipeline Orchestration with GitHub Actions

The Pipeline Architecture

The GitHub Actions Workflow File (.github/workflows/automated-release.yml)

🏷️ Step 4: The Tag-Driven Release Flow in Action

1. Test and Stage Locally

2. Cut and Push an Annotated Release Tag

Step 1: Switch to a Minimal Base Image (`-slim`)

Step 3: Add a Scrupulous `.dockerignore`

6. Container-to-Container DNS vs. `localhost`

7. Verifying True Data Persistence (and the Dangerous `-v` Flag)

The Solution: Healthcheck + `condition: service_healthy`

The Permissions Curveball: `srw-rw---- root root`

Why `0.0.0.0` vs. `127.0.0.1`?

The Port Conflict: `5001:5000`

2. Declarative Tooling with `mise.toml`

1. The Application (`app.py`)

2. Unit Testing with Pytest (`tests/test_app.py`)

3. Configuring Pytest (`pytest.ini`)

The GitHub Actions Workflow File (`.github/workflows/automated-release.yml`)

1. Pytest `ModuleNotFoundError: No module named 'app'`

2. Git Tag Push Error: `src refspec v1.0.0 does not match any`

The Application Code (`src/main.py`)

The Test Suite (`tests/test_main.py`)

`Dockerfile`

`.devcontainer.json`

Trap #2: Binary Exists vs. Module Exists (`which pytest` vs. `python -m pytest`)

Trap #3: `ModuleNotFoundError: No module named 'src'`

Trap #4: The Relative Import Trap (`from .src.main import ...`)

1. Devcontainer Agent Image (`Dockerfile` & `.devcontainer.json`)

2. Declarative Toolchain (`mise.toml`)

4. The Declarative Jenkins Pipeline (`Jenkinsfile`)

6. `java: command not found` (The Non-Interactive Shell Trap)

8. `Syntax error: "(" unexpected` on `eval "$(mise activate bash)"`