DEV Community: John Afariogun

The Hidden Life of a Container: A Complete Lifecycle

John Afariogun — Thu, 21 May 2026 12:37:05 +0000

The anatomy of a container tells you what the walls are made of. This article tells you when they go up, what happens inside them, and what the kernel does the moment they come down.

In the previous article, we dissected a running container at a single moment in time: the namespaces building the illusion of isolation, the cgroups enforcing the resource constitution, OverlayFS merging layers into a coherent filesystem, the veth pair wiring the container into the network. A cross-section. A photograph.

But a photograph doesn't tell you how the subject got there, or what happens after the shutter closes.

That's what this piece is for. We'll follow a single container from before it exists to after it's gone — and at each transition, we'll look at what actually changes at the kernel level. The machinery is the same as before. Now we watch it move.

We'll also cover the three places where production systems quietly break in ways that monitoring won't catch until it's too late: signal handling, zombie processes, and the OOM killer.

Before the Container: The Image as a Promise

Before anything runs, the runtime needs something to run from. An image isn't a virtual machine disk or a binary blob — it's a stack of read-only filesystem layers, each one a delta on the last, stored under /var/lib/docker/overlay2/ and identified by SHA256 digest rather than name.

When you run docker pull, the daemon fetches a manifest first: a JSON document listing every layer by digest. It then checks which of those digests already exist locally and downloads only the missing ones. This is why pulling a new version of an image that shares a base layer with one you already have takes seconds — the common layers are already there. The registry protocol is content-addressed, which means layers are inherently deduplicated across every image on the host that uses them.

Each downloaded layer is verified against its digest before being committed to the store. A tampered or corrupted layer fails this check before it touches anything.

The image at rest is inert. It's a promise of what the container's filesystem will look like when it starts — nothing more. The OverlayFS that merges those layers into a live, writable filesystem doesn't exist yet. That comes with create.

Stage 1: `docker create` — Assembling the Environment

Here is something most engineers don't know: docker run is not a single operation. It is docker create followed immediately by docker start. Knowing this distinction is practically useful — but more importantly, it clarifies when each piece of kernel infrastructure comes into existence.

docker create builds the complete environment the container will inhabit. Nothing executes. No process runs. It is pure allocation.

The OverlayFS mount. The runtime creates a new upperdir — an empty, writable directory unique to this container instance. The image's read-only layers become the lowerdir. The OverlayFS is configured to present both as a single unified filesystem: reads fall through to the lower layers, writes land in the upper layer, and the container will see a seamless root filesystem when it starts. The layers you read about in the anatomy piece are present here. The writable layer that captures everything your container does is created here.

The namespace allocation. The six namespaces — PID, NET, MNT, IPC, UTS, USER — are prepared. At this point they're reserved but not yet active. There's nothing to isolate, so isolation hasn't started.

The cgroup hierarchy. A cgroup is created for this container under /sys/fs/cgroup/. The memory limit from --memory 512m and the CPU quota from --cpus 0.5 are written into the cgroup's control files right now. The cgroup exists. The limits are set. But with no processes inside it, it enforces nothing — a constitution with no citizens.

The network configuration. The veth pair is created: one end destined for the container's network namespace, one end connecting to the docker0 bridge on the host. An IP is assigned. NAT rules are written to iptables for port mappings. The virtual cable exists, but nothing is plugged in on the container end yet.

After docker create, the container is a complete kernel data structure — every wall built, every rule written, every wire run — with no tenant. Its state is "created". Nothing has been charged to the CPU. Nothing has touched the writable layer.

The practical implication: you can pre-warm containers during off-peak hours and start them in milliseconds when demand arrives. The expensive work of building the environment is already done.

Stage 2: `docker start` — Crossing the Threshold

This is the moment the environment becomes inhabited. Three components work in sequence: dockerd, containerd, and containerd-shim.

dockerd instructs containerd to start the container. containerd forks a containerd-shim — the small, dedicated supervisor we covered in the daemon article — which then calls runc.

runc is where the kernel call happens. It takes the container's prepared configuration and calls clone() with the namespace flags: CLONE_NEWPID, CLONE_NEWNET, CLONE_NEWNS, and the rest. The namespaces activate. The OverlayFS is mounted. The cgroup begins accounting. The veth pair connects. Then runc calls execve() with whatever you specified as ENTRYPOINT or CMD.

That process — your application — becomes PID 1 inside the container.

Once execve() returns, runc exits. It has done its job. The containerd-shim stays behind, holding the container's stdin/stdout file descriptors and watching PID 1. If dockerd crashes, the shim keeps the container alive — which is the architecture we walked through in detail previously.

The moment docker start completes, everything the anatomy article described is live and active: the isolated process tree, the private network stack, the merged filesystem, the cgroup enforcing limits. The photograph is now a film.

And this is the first place things go quietly wrong. PID 1 carries obligations that your application almost certainly doesn't know about. We'll come back to that shortly.

Stage 3: Running — What the Commands Actually Do

A running container looks opaque from the outside. Under the hood, every docker command in this state is a thin wrapper over kernel operations you already understand.

docker exec is the most commonly misunderstood. When you run docker exec -it myapp-prod /bin/sh, Docker doesn't create a new container. It calls setns() — a system call that lets a process join existing namespaces. Your shell enters the container's PID and network namespaces and sees the same environment the application sees. Nothing new is created. You're walking into an existing apartment, not building a new one.

docker logs reads from the file descriptors the containerd-shim has been holding since start. The shim inherited the container's stdout and stderr pipes and has been buffering them since the first byte was written. No daemon magic — the shim is just a persistent pipe holder.

docker stats reads cgroup control files directly: /sys/fs/cgroup/memory.current for RSS, CPU accounting files for usage. The numbers you see in the terminal are the same numbers the kernel is maintaining to enforce your limits.

docker pause is the most elegant operation in this set. It uses the cgroup freezer subsystem to send SIGSTOP to every process in the container simultaneously — not one at a time, but atomically, via the cgroup. They freeze mid-instruction with no opportunity to catch the signal or react. docker unpause sends SIGCONT through the same path and they resume exactly where they stopped. In-flight operations, open sockets, memory contents — all preserved.

Stage 4: `docker stop` — The Two-Phase Shutdown

This is where most production problems originate, and where the PID 1 decision made at start time comes due.

docker stop is a two-phase protocol. Phase one: SIGTERM is sent to PID 1. The application has a grace period — ten seconds by default, adjustable with -t — to finish what it's doing and exit cleanly. Close database connections. Drain in-flight requests. Flush logs. Phase two: if PID 1 is still alive when the timer expires, SIGKILL is sent. There is no negotiation with SIGKILL. The kernel terminates the process immediately and unconditionally.

The failure mode that bites teams most often: the shell wrapper.

Many containers are launched like this: CMD ["sh", "-c", "node server.js"]. The shell becomes PID 1. When Docker sends SIGTERM to PID 1, the shell receives it — and by default, shells do not forward signals to their children. Your Node.js process never sees SIGTERM. Ten seconds pass. SIGKILL arrives. The server dies mid-request, connections drop, and the exit code suggests a crash rather than a clean shutdown.

The fix is to make your application PID 1 directly. Use the exec form: CMD ["node", "server.js"]. Or, if you need a shell script for setup, end it with exec node server.js — the exec replaces the shell process rather than forking a child, so your application inherits PID 1.

Ten seconds is also almost always too short. An application with database connection pools to drain and requests to finish needs more. Set -t 30 as a floor. For services handling long-lived connections, -t 60 or higher is appropriate. The grace period is your only window for a clean shutdown — size it honestly.

After a successful stop, the container's state becomes "exited". Crucially, the writable OverlayFS layer is preserved — every file the application created or modified is still there. The container can be restarted with docker start and will resume from exactly the filesystem state it stopped in.

The First Danger Zone: Zombie Processes

On a normal Linux host, PID 1 is the init system. One of init's core responsibilities — one so fundamental it's baked into the kernel's design — is reaping dead child processes. When a process exits, it doesn't fully disappear. Its kernel entry stays open, holding its exit code, until its parent calls wait() to collect that code. Until then, it sits in state Z: a zombie. Dead, but not yet buried.

Init's job is to call wait() on every process that loses its parent, so the kernel slot gets freed. Without init doing this, zombie entries accumulate indefinitely.

In a container, your application is PID 1. And your application — a web server, an API, a worker — was written to serve requests, not to supervise processes. It almost certainly never calls wait().

The scenario: your web server forks a worker to handle a long request. The worker finishes and calls exit(). It waits for its parent to acknowledge the exit. The parent never does. The worker's kernel entry sits in Z state. Do this at scale, over days of production traffic, and the PID table fills. Eventually fork() fails — the container cannot spawn new processes — and the application breaks in a way that looks nothing like its actual cause.

docker stats will show the container as healthy throughout. CPU and memory are fine. The zombie count isn't surfaced by any standard metric.

The fix is a proper init process sitting in front of your application. tini is the canonical choice — purpose-built for containers, less than a thousand lines of C, does one thing: reap zombies and forward signals correctly.

RUN apt-get install -y tini
ENTRYPOINT ["/tini", "--", "/usr/local/bin/myapp"]

If you don't want to touch the image, docker run --init injects a bundled init binary automatically. Use one or the other on every production container, as a default, without exception.

To check for zombies in a running container:

docker exec myapp-prod ps aux | grep ' Z '

Any output means you have a problem. The fix is tini. The time to add it is before the deployment, not during the incident.

The Second Danger Zone: The OOM Killer

The cgroup memory limit — set at create time, written to memory.max in cgroup v2 — is not a suggestion. When a container's resident memory usage reaches that ceiling, the kernel's Out-Of-Memory killer activates.

The OOM killer scores every process in the cgroup by a "badness" calculation: how much memory the process uses relative to total system memory, adjusted by that process's oom_score_adj value. The highest scorer is sent SIGKILL. In a single-process container, there is exactly one candidate. PID 1 always loses.

The critical distinction from docker stop: the OOM killer sends no SIGTERM. There is no grace period. No warning, no chance to flush state, close connections, or write a final log line. The process simply stops existing. Docker records this as OOMKilled: true in the container's inspect output:

docker inspect myapp-prod --format '{{.State.OOMKilled}}'
true

The kernel also logs it to dmesg:

dmesg | grep -i "oom\|killed process"

Mitigation works at two levels. The first is setting a soft limit below the hard limit:

docker run --memory 512m --memory-reservation 400m myapp

--memory-reservation tells the kernel to apply gentle memory pressure — nudging the container's garbage collector, encouraging page reclamation — before the hard ceiling is reached. It's an early warning system rather than a wall. The container can still exceed the reservation temporarily; only --memory is the hard stop.

The second level is treating OOM kills as bugs, not tuning parameters. A container that is repeatedly OOM-killed has either a memory leak or limits set below its actual working set. Raising the limit is a short-term fix. Finding the leak is the real work.

Stage 5: `docker rm` — Dismantling the Environment

docker rm is the exact inverse of docker create. Every kernel structure that create allocated is released in reverse.

The OverlayFS upper layer is deleted. Every file your application created, modified, or deleted since the container started — the entire writable history — is gone. If your application wrote logs or state directly to the container filesystem, it's unrecoverable. This is the reason containerised applications should write persistent data to mounted volumes, not the container filesystem: docker rm treats the writable layer as ephemeral by design.

The veth pair is removed. The IP address returns to Docker's pool. The iptables NAT rules for port mappings are deleted. The network configuration from create is fully unwound.

The cgroup hierarchy is destroyed. The entries under /sys/fs/cgroup/ that tracked this container's memory and CPU are removed. The kernel stops accounting for this container entirely.

What survives: the image layers. The read-only lowerdir that formed the container's base filesystem is untouched — available immediately for the next container. And named volumes survive unless you pass --volumes to docker rm. Persistent data stored in volumes outlives the container that created it, which is the intended design.

The Full Picture

The anatomy article showed you the ingredients. This one showed you the recipe — the same namespaces, cgroups, OverlayFS, and veth pairs assembled in sequence, operated during a container's life, and dismantled at its end.

The mental model to carry forward:

Create is allocation, start is execution. Every kernel structure — namespaces, cgroups, OverlayFS, veth pairs — exists before your application runs a single instruction. This is why pre-warming works and why restart is fast.

PID 1 is a contract, not just a position. The kernel gives PID 1 responsibilities that init normally handles: signal forwarding and zombie reaping. If your application holds that position, it inherits those responsibilities. Use tini or --init by default.

SIGTERM is your only warning. The grace period between SIGTERM and SIGKILL is the only window you get for a clean shutdown. Your application must handle the signal, and the window must be sized for your actual workload. Ten seconds is almost always too short.

The OOM killer gives no warning at all. There is no SIGTERM, no grace period, no log line from your application. If OOMKilled: true appears in production, treat it as a bug — because it is one.

The writable layer is temporary. docker rm destroys it completely. Write persistent state to volumes. Treat the container filesystem as scratch space that disappears when the container does.

docker run looks like a single command. It is actually the sequential execution of eight distinct kernel operations, each with observable state and specific failure modes. The engineers who debug containers fastest aren't the ones who know the most flags — they're the ones who can trace a problem back to the operation where the kernel did something unexpected.

Now you can.

Part of an ongoing series on container internals. Previous: A Deep Dive into Docker: What Ticks Under the Hood?

The Middle Child Syndrome: Why Your Frontend might not be able to Talk to it's Docker Siblings

John Afariogun — Fri, 20 Feb 2026 15:58:08 +0000

Containerizing full-stack apps reveals a harsh reality—your React frontend is the awkward middle child that can't speak to its Docker siblings.

Containerizing a full-stack application is a rite of passage for every DevOps-leaning engineer. You successfully get your Node.js backend talking to PostgreSQL, your Python ML service crunching data, and Redis caching everything in between.

But then, the "Middle Child" enters the room: The Frontend.

Despite being part of the docker-compose.yml family, the frontend often feels isolated, unable to speak the same internal language as its Docker siblings. Here's why it happens and how to solve it.

The Family Reunion That Excluded Frontend

I recently orchestrated a multi-service e-commerce app with:

Backend (Node.js/Express)    ✅ Connected
ML Service (Python/Flask)    ✅ Connected  
PostgreSQL Database          ✅ Connected
Redis Cache                  ✅ Connected
React Frontend               ❌ Left outside in the cold

Inside the Docker bridge network, life was beautiful. My backend could reach the ML service simply by using the service name:

// Inside the backend container
const response = await fetch('http://ml-service:5000/recommendations/42');
// ✅ Works perfectly!

The Docker DNS handles the heavy lifting. Services on the same bridge network are family.

# docker-compose.yml - Happy family networking
services:
  backend:
    networks: [app-network]
  ml-service:
    networks: [app-network]
  postgres:
    networks: [app-network]
  redis:
    networks: [app-network]

networks:
  app-network:
    driver: bridge

Frontend Got Kicked Out (The Harsh Reality)

Then I tried the same thing from my React frontend:

// React frontend trying to join the family...
fetch('http://backend:8080/api/products')
  .then(res => res.json())
  .catch(err => console.error('Sibling rivalry:', err));

Browser Console:

net::ERR_NAME_NOT_RESOLVED

Why Did This Fail?

The "Middle Child Syndrome" stems from a fundamental misunderstanding of where the code actually runs:

Backend code runs inside the Docker container → uses Docker's internal DNS
Frontend code is delivered by Docker, but executes in the user's browser

The browser lives on your host machine (your device), not inside the Docker bridge network. Your device's DNS has no idea what http://backend is. The Docker network is a private club your browser doesn't have membership for.

Browser ←─── HTTP ───► ??? ──── Docker Network ───► Services
  │                              (backend, ml, db, redis)
  │
  └── Can't reach Docker DNS directly ❌

The Solutions: Pick Your Poison

1. Expose Everything (Security Nightmare ⚠️)

The quickest fix is to expose every service to your host machine:

services:
  backend:
    ports:
      - "8080:8080"  # Now public on localhost
  ml-service:
    ports:
      - "5000:5000"  # Exposed to internet

React calls http://localhost:8080, also calls http://localhost:5000 ✅ Works, but you've just exposed all your internal services to the entire internet. In production, this is a massive security "no-go."

2. Backend Proxy (Secure & Simple)

Route frontend requests through your backend, which can access Docker DNS:

services:
  backend:
    ports:
      - "8080:8080"  # Single exposed port
  ml-service:
    # No ports exposed - internal only

Backend proxies ML requests:

// backend/server.js
app.get('/api/ml/:path*', async (req, res) => {
  const mlUrl = `http://ml-service:5000/${req.params.path}`;
  const response = await fetch(mlUrl);
  res.json(await response.json());
});

React calls /api/ml/recommendations → Backend proxies to ml-service:5000 ✅ Secure + elegant.

3. Nginx Reverse Proxy (Production Ready)

This is the most architecturally sound approach. Put a "Gatekeeper" in front of your family:

services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf

  frontend:
    # No ports exposed

  backend:
    # No ports exposed

  ml-service:
    # No ports exposed

nginx.conf:

server {
    listen 80;

    location /api/ {
        proxy_pass http://backend:8080/;
    }

    location /ml/ {
        proxy_pass http://ml-service:5000/;
    }

    location / {
        proxy_pass http://frontend:3000/;
    }
}

Now your frontend only talks to one place: the Nginx port. Nginx lives inside the Docker network and handles routing to all siblings.

Browser ←─── HTTP ───► Nginx (port 80) ──── Docker Network ───► Services ✅

The Root Cause: Network Architecture Mismatch

Docker bridge networks solve:

✅ Service-to-service communication
✅ Container DNS resolution
❌ Browser-to-container (without port mapping or proxy)

The fix requires understanding execution context:

Code Location	Runs Where?	Can Use Docker DNS?
`backend/server.js`	Inside container	✅ Yes
`ml-service/app.py`	Inside container	✅ Yes
`frontend/src/App.jsx`	In browser	❌ No

Lessons Learned (The Hard Way)

Execution Context is King - Always ask: "Where is this code actually running?" If it's a .jsx file, it runs in the browser, not Docker.
One Ingress Point - Avoid "Swiss Cheese" security. Expose one port (80/443) and route everything internally.
Environment Variables Save Lives:

   const API_URL = import.meta.env.VITE_API_URL || 'http://localhost:8080';

CORS is Your Friend - Configure properly on all services that Nginx proxies:

   app.use(cors({ origin: process.env.ALLOWED_ORIGINS }));

Complete Working Example

version: '3.8'

services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on: [frontend, backend]

  frontend:
    build: ./frontend
    # No ports - accessed via nginx

  backend:
    build: ./backend
    environment:
      DB_HOST: postgres
      REDIS_URL: redis://redis:6379
    # No ports - accessed via nginx

  ml-service:
    build: ./ml-service
    # Internal only

  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: shopmicro

  redis:
    image: redis:alpine

networks:
  default:
    driver: bridge

The frontend middle child finally found its place - behind a proxy, secure, and talking to all its Docker siblings through proper networking architecture.

What's Next?

In my next post, I'll share how I took this ShopMicro architecture and scaled it into a Kubernetes cluster with Ingress controllers—where the networking gets even more "fun."

🔔 Notifycli: A Lightweight Go CLI for Firebase Push Notifications

John Afariogun — Fri, 05 Dec 2025 08:28:00 +0000

Need to send push notifications to your mobile or web clients — from the command line, a backend script, or a CI/CD pipeline — without building a full backend server?
Notifycli is a simple, Go-based CLI that does exactly that: use Firebase Cloud Messaging (FCM) credentials + a device token to send push notifications.

In this post, I unpack the code, show installation and usage, and highlight how it's built — so you can use or extend it for your own projects.

What is Notifycli?

According to the project README:

Notifycli is a “Go CLI for sending push notifications to mobile and web devices using Firebase Cloud Messaging.” (GitHub)
It supports sending to a single device (via FCM device token), and allows custom data payloads — e.g. a title, body, optional URL — which your app can use for deep linking or redirection. (GitHub)
It uses a clean project structure based on the popular CLI framework Cobra for subcommands and flag parsing. (GitHub)

Because it's a standalone binary (no heavy deps, no web server), it works well for automation: cron jobs, server scripts, deployment hooks, or any backend that just needs to “fire-and-forget” an FCM push.

Project Structure & Architecture

Here’s how the repo is structured: (GitHub)

Notifycli/
 ├── cmd/
 │    ├── root.go         # CLI root command definitions
 │    └── notify.go       # “notify” subcommand: sends a notification
 ├── internal/
 │    └── firebase/
 │         └── client.go  # Firebase FCM client wrapper
 ├── main.go              # Entry point
 ├── go.mod / go.sum      # Module definitions
 ├── test/                # (optional) tests
 └── README.md

Highlights:

cmd/: Uses Cobra to define commands and flags.
internal/firebase/client.go: Encapsulates FCM initialization, authentication using a Firebase service-account JSON key, and the logic to send notifications via FCM REST API. (GitHub)
Minimal external dependencies — this keeps the binary lightweight and portable.
Easy to integrate with scripts, cron jobs, CI/CD pipelines — you just call notifcli notify ....

How to Build & Use

1. Clone & Build

git clone https://github.com/johnafariogun/Notifycli.git
cd Notifycli
go build -o notifcli
# optionally:
go install

2. Provide Firebase Credentials

Go to your Firebase project → Project Settings → Service Accounts → Generate new private key.
Download the serviceAccount.json and place it in your project root (or anywhere you like, but pass its path with --creds). (GitHub)

3. Send a Notification via CLI

notifcli notify \
  --token <DEVICE_FCM_TOKEN> \
  --title "Deployment Successful" \
  --body "Your service is live." \
  --creds /path/to/serviceAccount.json

Optional flag: --url, to include a link in the data payload (useful for app deep links or redirect URLs). (GitHub)

That’s all — a simple, one-liner to trigger a push notification from anywhere.

Under the Hood: What’s Going On

The CLI parses flags (token, title, body, url, creds) via Cobra in cmd/notify.go. (GitHub)
The internal/firebase/client.go module: initializes a Firebase app using the provided service account, constructs the FCM message (with title/body, and optional data payload containing link), and sends the request to FCM via HTTPS. (GitHub)
Error handling covers cases like missing credentials, invalid FCM token, or network failures. The CLI prints descriptive error messages. (GitHub)
Because it's a native Go binary, it’s cross-platform (Linux, macOS, etc.) and doesn’t require runtime dependencies beyond Go’s standard library + net/http.

Why This Tool Matters

Simplicity & Speed: No need to build a full backend just to send notifications.
Automation-friendly: Great for deployment scripts, CI/CD, cron jobs, or server-side alerts.
Portable: Build once, deploy anywhere.
Extensible: You can extend internal/firebase/client.go to support more advanced FCM features — e.g. topic messages, batch sends, custom data payloads, image notifications. The architecture is clean and modular. (GitHub)

Wrap-up & Final Thoughts

Notifycli is a great example of how a small, focused tool can do one thing well — in this case: send FCM push notifications — and integrate easily into scripts, automation, or backend workflows.
Its clean Go + Cobra structure and minimal dependencies make it perfect for developers or DevOps workflows that don’t need a full backend server just for notifications.

If you need a lightweight, scriptable, cross-platform tool for mobile/web push notifications — especially useful for deployment alerts, status updates, or automation — give Notifycli a try.

A2A adventures

John Afariogun — Mon, 03 Nov 2025 17:43:20 +0000

Building a GitHub Issues Agent with FastAPI and A2A

This project demonstrates a small agent that receives A2A JSON-RPC messages and returns GitHub issues for a repository. It is intentionally minimal — focusing on clear message schemas, simple HTTP fetch logic, and deterministic behavior.

Motivation

I wanted an agent that can be called by other systems via an A2A JSON-RPC contract and that returns a small, well-formed payload containing issue metadata and a short textual summary.

Architecture

FastAPI for the HTTP server and lifecycle management
Pydantic models (in models/a2a.py) for the message contract
A single agent implementation (agents/github_issues_agent.py) that extracts the repository and calls a tool function utils.fetch_issues to get the data from GitHub

Implementation notes

agents/github_issues_agent.py extracts owner/repo strings from the message parts. It builds a TaskResult that includes a textual summary and an artifact containing the full issues payload.
utils/fetch_issues uses httpx and handles rate-limit behavior by allowing a GITHUB_TOKEN in the environment.

You can check it out at github.com/johnafariogun/github_app
— End

🐱 My HNG 13 Stage 0 Task — Building a Simple Cat Facts API with FastAPI

John Afariogun — Thu, 16 Oct 2025 10:45:06 +0000

After getting to the penultimate stage in HNG12 internship earlier this year, my perfectionist tendencies cropped up again and this time I want to get to the ultimate stage. First though I have to start from the scratch so stage 0 it is.

The goal for Stage 0 was straightforward:

👉 Build a small backend application that returns some personal info — and something extra (Cats facts).

🚀 Project Overview

This project, called Cat Facts API Integration, fetches random cat facts from the public Cat Facts API and combines them with basic user information.

It includes three simple endpoints:

/ → Root welcome route
/health → Health check
/me → My personal info + a random cat fact

All built with FastAPI, httpx, and a bit of structured logging.

🧩 Project Structure


HNG13_simple_rest_stage_0/
├── app.py
├── app.log
├── requirements.txt
└── README.md

The app includes:

FastAPI for routing and documentation
httpx for making async API requests
logging for monitoring
CORS middleware for flexible frontend integration if need be

🧭 Endpoints Documentation

Method	Endpoint	Description
`GET`	`/`	Root endpoint that returns a welcome message.
`GET`	`/health`	Confirms that the API is healthy and reachable.
`GET`	`/me`	Returns user info (email, name, stack) along with a random cat fact.

🧪 Example Response

GET /me

json { "status": "success", "user": { "email": "afariogun.john2002@gmail.com", "name": "John Afariogun", "stack": "Python/FastAPI" }, "timestamp": "2025-10-15T10:00:00Z", "fact": "Cats sleep for around 70% of their lives." }

🧰 Running the App Locally

To test this project on your system:

bash git clone https://github.com/johnafariogun/HNG13_simple_rest_stage_0 cd HNG13_simple_rest_stage_0 pip install -r requirements.txt

Then start the server:

bash python app.py

Visit these URLs in your browser:

http://127.0.0.1:8080
http://127.0.0.1:8080/me
http://127.0.0.1:8080/docs → to explore the auto-generated FastAPI documentation

You can checkout (mine)[https://hng13simplereststage0-production.up.railway.app/me]

📸 OpenAPI Documentation

FastAPI automatically provides Swagger UI for your routes:

🧭 Navigate to /docs
You’ll see your /, /health, and /me routes neatly documented — no extra setup needed!

🌍 Deployment

So I deployed this on Railway

You can check out how to deploy a fastapi app on railway at the official docs

💡 What I Learned

How to set up a simple FastAPI app
How to call external APIs asynchronously using httpx
How to implement logging and error handling
How to structure JSON responses neatly
The power of automatic documentation in FastAPI
How to deploy using Railway

🔚 Conclusion

Stage 0 may look simple, but it’s where the foundation for cleaner, production-ready APIs begins.

This project taught me how small things — like handling timeouts, errors, and logs — make a huge difference when building real backend systems.

Next step? Stage 1 of HNG 13, probably focusing on testing, deployment, and CI/CD 🚀

👨‍💻 Author: John Afariogun
Stack: Python / FastAPI
GitHub: @johnafariogun
Email: afariogun.john2002@gmail.com