DEV Community: James Ngandu

Field notes from running small services

James Ngandu — Tue, 06 Oct 2026 12:46:34 +0000

I keep a running list of the things I do on every small service I run. None of it is clever. All of it has saved me at least once. I wrote up the full setup in You probably do not need Kubernetes. These are the notes I actually come back to.

Harden the box before anything else

Before the app goes anywhere near a server, the server has to be safe to expose. No root login. Key-only SSH. A firewall open on 80, 443, and SSH, and nothing else. Something like fail2ban to cut down the noise.

The step people skip is disabling password authentication. Do it only after you have confirmed key login works in a second session. I have locked myself out doing it the fast way, and it is a bad hour.

Bind the app to localhost

One line, worth more than most of the architecture decisions I make:

ports:
  - "127.0.0.1:3000:3000"

The app port is reachable only from the machine itself, so the reverse proxy is the only door in. If the proxy config breaks, you have a broken site, not an exposed service.

Check the certificate now, not later

certbot renew --dry-run

Five seconds. If it fails, I want to know today rather than the morning a certificate expires and the site goes red.

A deploy you can reverse is a deploy you will actually do

If deploying feels dangerous, you avoid it, and then you ship one scary change. The fix is small and reversible deploys. On a push, run the tests, and if they pass, update the box. Keep secrets in the platform, never in the repo. Keep the previous version one step away.

Minimum observability

A server you cannot see is a server you are guessing about. For a small service that means a health check that reflects real readiness, an external monitor that pages you when it stops answering, and logs you can read. That is enough. Collecting more than that, before there is a question to answer, is procrastination wearing a dashboard.

Reach for Kubernetes late

Kubernetes earns its keep when there are several services that scale independently, or a team that deploys without you, or a scheduler with real work to do. Until then it is a second job you volunteered for. I would rather run one box I understand than a cluster I have to look up.

The part that is not technical

The same shape of work shows up outside infrastructure. Leading the IEEE student branch at university was the same problem: limited time, unclear requirements, people with different goals. The clarity is the job. The tools are secondary.

None of these notes are original. They are just the ones that keep being true. If you run a small service, the boring version you understand will almost always beat the impressive version you do not.

Infrastructure was not where I started

James Ngandu — Tue, 06 Oct 2026 12:43:45 +0000

Infrastructure was not where I started.

I started in C. Pointers, arrays, strings, then memory allocation, linked lists, and eventually a shell. For months the work was small and low level: read a line, parse it, fork, exec, wait. Debug a segfault until it finally made sense. Recompile.

At the time it did not feel like infrastructure. It felt like fighting the machine. The compiler disagreed with me constantly. Memory had to be handed back by hand. Almost nothing was convenient.

Then I moved into Linux administration, Docker, CI/CD, and running production systems. And I kept noticing that the hard part was familiar.

When a container exits with code 137, that is the OOM killer, and it helps that I once had to think about how memory is actually used. When a process will not die, signals stopped being mysterious back in the shell project. When a service will not start, reading the log and following the failure chain is the same skill as tracing why a pointer wrote to the wrong place.

The language changed. The habit did not. The habit is this: understand the layer below the one you work in, so that when something breaks you can reason about why instead of guessing.

That is the thing ALX actually gave me, more than any single technology. It made being lost normal, and it made me comfortable opening the box.

If you are in the middle of the low level work right now, and it feels disconnected from the jobs you want, this is what I would say. The specific skills transfer less than you expect. The instincts transfer more. And the instincts are the part nobody can take from you.

Still learning. Still running small things on a single box more often than not.

You probably do not need Kubernetes

James Ngandu — Tue, 06 Oct 2026 12:42:16 +0000

Every few months I talk to someone who wants to put a small app on Kubernetes. Usually the app is one container, a database, and a handful of users. Often it is not even in production yet.

Kubernetes is excellent at a specific job: running many services, across many machines, with a team that deploys independently. If that is not your situation, it is a large amount of complexity you are taking on for a problem you do not have.

Most of my services run on a single VPS, and this is roughly how I set one up.

Harden the box first

Before anything runs, the server needs to be safe to expose. That means no root login, no password authentication, a firewall with only the ports I need, and something like fail2ban to cut down the noise. It is ten minutes of work, once.

The step people skip is disabling password authentication, because it is the one that can lock you out. Confirm your key login works in a second session before you close the first. I have gotten that wrong, and it is a bad hour.

The app runs in a container, bound to localhost

I run almost everything in Docker. One detail matters more than the rest: I bind the app port to 127.0.0.1 instead of exposing it.

ports:
  - "127.0.0.1:3000:3000"

That single choice means the container is never directly reachable from the internet. Only the reverse proxy in front of it can talk to it. If I misconfigure the proxy, the worst case is a broken site, not an open service.

Nginx sits in front and terminates TLS

Nginx does three jobs for me. It proxies to the app, it terminates HTTPS, and it is the layer I edit when routing changes or a new domain shows up. Certbot handles the certificates, including the renewal timer, so I am not the renewal timer.

The one check I run on every new server is certbot renew --dry-run. If that fails, I want to know today rather than the morning a certificate expires.

Deploys should not need me

The pipeline is short on purpose. On a push to main, GitHub Actions runs the tests, and if they pass it updates the box and restarts the container. Secrets live in GitHub, never in the repository, and the change is small enough that rolling back is just pointing at the previous commit.

A deploy I can reverse in a minute is a deploy I am willing to run often. That matters more than any particular tool.

Can I see it?

A server I cannot observe is a server I am guessing about. I want a health check that reflects real readiness, an external monitor that pings it and shouts at me when it stops answering, and logs I can actually read. That is enough for a small service. Collecting more than that, before there is a question to answer, is usually procrastination wearing a dashboard.

When I would actually reach for Kubernetes

When there are several services that scale independently, or a team that needs to deploy without asking me, or a scheduler with real work to do. When the complexity is buying something I need.

Until then: one box, a few containers, a proxy, and a pipeline I understand end to end. It runs, I can reason about it at 2am, and I can replace it when the requirements change.

That is usually the right trade. The impressive setup can wait until the boring one stops being enough.

My ALX journey: from Hello World in C to a load balancer and my own shell

James Ngandu — Tue, 06 Oct 2026 12:35:24 +0000

ALX is the software engineering programme that half of tech Twitter in Africa either went through or is currently grinding through. It is run by ALX Africa, built on the Holberton School curriculum, sponsored through the Mastercard Foundation, and it does not cost the learner anything. Twelve months, no lectures, project after project, and a peer learning model that takes a few weeks to get used to.

This is what that year looked like for me, and what is sitting in my repos to show for it.

How the programme works

It runs in sprints. You start with foundations, then move into a specialization. You advance by finishing projects, not by passing an exam. There is a completion cutoff around 80 percent of the projects across the sprints, with a minimum average in each one. Nobody stands in front of a class. You read the material, you attempt the project, you get stuck, you ask the people around you, and you submit.

The curriculum is deliberately vague in places, and that is the point. The phrase they use is owning your own learning, and after a few months it stops sounding like a slogan.

Foundations: Git, the command line, and C

The first thing you learn is that the terminal is not scary. Git and command line basics come before any real code, then Bash, and then C, which is where the real work started.

My alx-low_level_programming repo is the record of that stretch. It starts with a Hello World and works through variables, conditions, loops, and functions. Then debugging. Then the thing that humbles everyone: pointers. Pointers, arrays, and strings get four separate project sets. After that come recursion, static and dynamic libraries, command line arguments, malloc and free, the preprocessor, structs, function pointers, variadic functions, singly and doubly linked lists, bit manipulation, file I/O, hash tables, Makefiles, and search algorithms.

Somewhere in there you also reimplement formatted output, which is the moment variadic functions stop being a curiosity, and later you build a working shell: read a line, parse it, fork, exec, wait, and loop. That shell project is where all the small pieces suddenly have to work together in one program, and it is the closest the low level work gets to feeling like an actual system.

Higher level: Python and JavaScript

Then the language changes and the ideas stay the same. My alx-higher_level_programming repo goes from Python fundamentals (loops, imports, modules) into data structures, exceptions, classes, inheritance, test driven development, and a project called almost a circle that builds a small shape hierarchy from scratch. Later it moves into object relational mapping, network requests, and then JavaScript: the warm up, then objects, scopes, and closures, then web scraping and jQuery.

The interesting part is not learning a second language. It is noticing how much of C follows you into Python. Memory, references, and what an object actually is stop being abstract once you have spent months managing all of it by hand.

System engineering and DevOps

The third thread is the one that changed how I think about software the most. My alx-system_engineering-devops repo covers shell basics, permissions, redirections, variables, loops, conditions and parsing, processes and signals, and regular expressions. From there it goes where most beginner courses never do:

Networking, in two parts.
Web infrastructure design, the diagrams that explain how a request actually reaches an application.
SSH, and hardening it.
A web server, then an application server.
A load balancer, and later HTTPS and SSL certificates.
MySQL, including primary and replica setups.
APIs, and then advanced API work.
Web stack debugging, four separate rounds of it.
Webstack monitoring.

The web stack debugging projects are brutal, and I mean that as a compliment. You get a broken server and no description of what is wrong, and you have to find it. That is closer to the real job than any tutorial.

What ALX actually taught me

Less about any single language, and more about process. How to read documentation, how to break a big problem into pieces, how to ask a good question, and how to keep going when a project makes no sense for the first two hours. The deadlines are real and the volume is high, so you also learn to ship something that works instead of something perfect.

The other thing is people. The peer model is not decoration. A lot of what I know came from sitting with someone late at night tracing a segfault until one of us saw it. A lecture does not give you that.

If you are in ALX right now

A few things I would tell anyone in the middle of it:

Do not skip the low level work. It is the foundation everything else sits on.
Write down what broke and how you fixed it. It becomes your own documentation.
Ask for help earlier. Suffering for six hours before asking is not discipline, it is wasted time.
Push your work to GitHub as you go. Those repos are a portfolio at the end, and they are the reason people believe you when you describe what you can do.
Do not compare your progress to the person next to you. The sprints are hard for everyone, in different places.

The repos

alx-low_level_programming: C, from Hello World to a working shell.
alx-higher_level_programming: Python and JavaScript.
alx-system_engineering-devops: shell, networking, servers, and the debugging that comes with them.

If you are going through ALX, or thinking about starting, and you want to compare notes, the comments are open.

I built ARN.IO, a reading companion that keeps your place and your notes

James Ngandu — Tue, 06 Oct 2026 12:26:33 +0000

Browsers are good at showing you a page and bad at remembering it. Read a book online, close the tab, and a week later you are scrolling to find your place and wondering what you highlighted. ARN.IO is a small attempt to fix that.

It is a digital library and reading companion. You browse a collection, read chapter by chapter in the browser, and the app keeps track of where you are, so picking a book back up does not start with hunting for your place.

What it does

A curated library you can search by title, author, or genre.
Reading in the browser, one chapter at a time.
Progress per book, with the current chapter and a percentage, plus reading streaks that count minutes and pages.
Notes attached to a specific book and chapter, so the note lives next to the thing it is about instead of in a separate app.
Upload your own documents. PDF, Word, TXT, Markdown, HTML, and RTF are accepted and split into chapters automatically.
An AI reading assistant you can ask about themes, characters, summaries, or what to read next.

About the AI part, honestly

The assistant works out of the box. It ships with built-in keyword matched responses, so there is no API key to paste and nothing to pay for, and it still answers the common questions about a book. That was deliberate. I wanted someone to clone the repo, run it, and have the assistant actually reply instead of showing a configuration error. The chat is per book and the history is kept, so if you want to wire it to a real model later the interface is already there.

How it is put together

It is split into a client and a server. There is a run.sh at the root if you want to start everything at once.

chmod +x run.sh
./run.sh

There is also a docker-compose.yml with separate Dockerfiles for the client and the server, if you would rather not install anything locally.

Notes on the upload

Splitting a document into chapters across six formats is the fiddliest part of the feature. A PDF and a Markdown file do not agree on what a chapter even is, so the splitting is a best effort and you can always fix it by hand afterwards.

What it is not

There is no feed, no recommendations pushing you toward the next purchase, and no social layer. It is a reading tool, and it tries to stay out of the way.

Try it

Repo: https://github.com/mukuvi/ARN.IO

It is JavaScript end to end and it runs locally in a couple of commands. If you read and you lose track like I do, or you just want a small project to poke at the document parsing, the issues are open.

Also on DEV: if you are trying to make your first open source contribution, I wrote about a repo where contributing means adding yourself to it.

I built a site where your first open source contribution is adding yourself to it

James Ngandu — Tue, 06 Oct 2026 12:26:31 +0000

Plenty of people never make their first pull request. The commands are rarely the reason. You can learn git add, git commit, and git push in an afternoon. What stops people is that the repo they pick has no reason to care whether they showed up, and nothing visibly changes when they are finished.

So I built FREE-OPEN. It is a small React site, and the contribution is literally you. You fork it, add yourself to one JSON file, and open a pull request. When it is merged, your card appears on the contributors page of the live site. That is the whole thing. No issue to claim, no build system to learn, no review gauntlet waiting for you.

What your first contribution looks like

Fork the repo, clone your fork, and install dependencies:

git clone https://github.com/<YOUR-USERNAME>/FREE-OPEN.git
cd FREE-OPEN
npm install

Create a branch, open src/data/contributors.json, and add yourself to the end of the array:

{
  "name": "Your Full Name",
  "github": "your-github-username",
  "linkedin": "your-linkedin-slug",
  "twitter": "your-twitter-handle"
}

Run npm run dev, check that your card shows up at /contributors, then commit, push, and open the pull request. Once it is merged your card is on the live site.

Why a JSON file

I wanted the first contribution to be as small as possible. Adding one object to one file means you cannot really break anything, and if two people do it at the same time the conflict is a one-line fix. The point is not the JSON. The point is that you run the whole loop once, fork, branch, commit, push, pull request, merge, and then you look at the site and your name is there.

The stack

React 18, Vite, Tailwind CSS, and React Router. Nothing exotic. Vite because the dev server is fast enough that a newcomer does not sit around wondering if something is broken. Tailwind because the site has a dark mode and I did not want to hand-write a second stylesheet. React Router for the contributors and about pages.

What the repo is for

The repo has picked up 19 forks, and it has become a place to practise the boring, real parts of contributing: writing a branch name, writing a commit message that says what you did, writing a PR description that a maintainer can act on. Those are the things that get you through your first job, and you can practise them here without a deadline.

The lesson I keep coming back to is simple. People will contribute if the barrier is one file and the reward is visible. A lot of projects get the first half right and forget the second.

It is not finished

There is a CONTRIBUTING.md, a code of conduct, and issue templates for bugs, features, and improvements, so there is more to do than just add a card. The site itself is plain on purpose. I would rather it stay readable than clever.

Try it

Live site: https://free-open.vercel.app/
Repo: https://github.com/mukuvi/FREE-OPEN

If you have never opened a pull request, this is a good place to start and I will review it. If you maintain a repo and you are trying to get first-timers through the door, take the idea. Make the first step tiny and make the result visible.

Also on DEV: I wrote about ARN.IO, a reading companion that keeps your place and your notes, if you want another look at how I build things end to end.

Touch Grass Birder: a bird call identifier that works with no signal

James Ngandu — Tue, 06 Oct 2026 05:11:27 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass.

What I Built

Touch Grass Birder identifies bird calls, and it does the whole thing on your own machine.

You tap Listen, hold your phone up while a bird sings for about six seconds, and it tells you what you are hearing. Then you put the phone away and go look for the bird. That is the point: the screen is only in the way for a moment.

I built it for the places where phone apps tend to fall over. A trailhead with one bar. A tent before sunrise. A park where the warblers are moving through and you have no idea what you are listening to.

What it does:

Records six seconds of audio in the browser and encodes it to WAV on the device.
Identifies the species locally with BirdNET, the open acoustic classifier from the Cornell Lab of Ornithology.
Writes a short field note about the bird with Gemma 3 1B, an open-weight model running through llama.cpp.
Keeps a field log of everything you have heard, in a plain JSON Lines file you own.
Installs as a PWA and keeps working with the network turned off.

There is no API key, no audio upload, and no network round trip.

Demo

Live demo: https://touch-grass-birder.onrender.com

The hosted demo runs BirdNET, so you can point it at a recording right now. Gemma field notes only work when you run it yourself, because a free Render instance is too small for the 0.8 GB model. Run make models && make run for those.

Code

https://github.com/mukuvi/touch-grass-birder (MIT licensed).

How I Built It

Two open models run on the device, wired together behind a small FastAPI server.

flowchart LR
  A[Phone browser<br/>records 6s, encodes WAV] --> B[FastAPI]
  B --> C[ffmpeg<br/>decode to 16-bit mono WAV]
  C --> D[BirdNET acoustic model<br/>open, local inference]
  D --> E[species + confidence]
  E --> F[Gemma 3 1B<br/>open-weight via llama.cpp]
  F --> G[plain-language field note]
  E --> H[(data/sightings.jsonl<br/>your field log)]
  G --> A
  H --> A

The pieces:

Browser side: the MediaRecorder API captures six seconds, an AudioContext decodes it, and a small function in app.js writes a real 16-bit mono WAV Blob before it is sent. The server never has to touch the audio to get a usable clip.
BirdNET does the acoustic work. It is trained on thousands of species for passive acoustic monitoring, and it is the reason this works offline at all. It loads through the LiteRT runtime and stays warm in memory after the first call.
Gemma 3 1B (Q4_K_M, about 0.8 GB) runs through the llama.cpp CLI to write a two or three sentence field note: what the bird sounds like, where and when you would hear it, and one field mark to look for. If the model is not on disk, the app skips the note and still identifies the bird.
FastAPI ties it together with four endpoints (/api/identify, /api/sightings, /api/health, and the static app). The field log is data/sightings.jsonl.

Everything is overridable with environment variables (LLAMA_BIN, GEMMA_MODEL, MIN_CONF, LLAMA_THREADS, BIRDER_DATA_DIR), so the same code runs on a laptop, a Raspberry Pi, or something sitting next to a phone.

Why Does Open Innovation Matter?

The short version: this project only exists because the models are open.

The best places to hear birds are the places with no signal, and a cloud API cannot run there at all. Every closed identifier needs a round trip to a server. Running BirdNET on the device means the app is not a worse version of a cloud tool in the backcountry. It is the only version that works there. The recording is six seconds because nothing has to be uploaded and there is no spinner to wait on. The answer is already on the phone.

A rare sighting is sensitive. A closed app can learn where you were and when, which matters if you are near a nesting site or reporting a scarce species. Here the only record is a line in a file you own, on hardware you control. There is no server for it to go to.

Open weights also mean I can change the model. Gemma runs from a local GGUF file, so moving to a larger Gemma, a different quantization, or a different model entirely is a path and an environment variable, not a conversation with a vendor. I can fine-tune on a regional species list later. The classifier itself, BirdNET, is open and inspectable, which feels important when the output is a claim about a living thing.

And it costs nothing to run. No per-identification fee, no rate limit, no key that expires. A birder on a budget, a school group, or a citizen science project can run it as long as they want.

The open parts are the point. For this app the offline, private, zero-cost version is simply the better one.

My Agent Session

I built this with an agent. The session is saved, so you can see how it went:

Building Touch Grass Birder for the HF26 Week 1 challenge

You

Pasted the Hacktoberfest Open-Source AI Challenge Week 1 (Touch Grass) announcement: build something with open-source AI at its core that gets people outdoors, due Oct 11. Can you do this?

Agent

I checked the workspace. There is already a project: Touch Grass Birder, a bird-call identifier (BirdNET + Gemma 3 1B) that runs fully locally. Tests pass. I loaded the challenge skill and confirmed Week 1 is active (id 79, due Oct 12 06:59 UTC).

▸ get_challenges list active DEV challenges

Input

list active DEV challenges

Output

Week 1 (id 79) active: theme Touch Grass, $2450 across 17 winners, judging = writing quality, relevance, creativity, technical execution, partner tech. Requires tag #hf26challenge.

You

Scope: Draft the DEV post, repo polish + commit, deploy to Render, save + embed the agent session, do it all end-to-end.

Agent

Audited the code (identify.py via BirdNET/LiteRT, fieldnotes.py via llama.cpp Gemma 3 1B, FastAPI main.py, PWA static app, 3 passing tests). Drafted the full submission post to docs/dev-submission-draft.md and added an MIT LICENSE.

▸ pytest uv run pytest -q

Input

uv run pytest -q

Output

3 passed in 2.09s

▸ git ls-remote git@github.com:mukuvi/touch-grass-birder.git

Input

git@github.com:mukuvi/touch-grass-birder.git

Output

Repository not found. Found the real repo at mukuvi/-touch-grass-birder (leading dash) with Apache-2.0 LICENSE; README/pyproject declared MIT. Local git history was an unrelated snapshot.

You

Decisions: rename repo to touch-grass-birder, use MIT license, deploy a BirdNET-only demo on Render free tier (Gemma notes run locally).

Agent

Reconciled the local repo onto the real remote, replaced Apache-2.0 LICENSE with MIT (matching README/pyproject), committed the post draft + license, and pushed to GitHub.

▸ git push git push git@github.com:mukuvi/-touch-grass-birder.git main

Input

git push git@github.com:mukuvi/-touch-grass-birder.git main

Output

25ba8b6..40b587d main -> main

You

proceed bro, you got all the keys

Agent

Verified the push landed, pointed local origin at the real repo, and set out the remaining steps: rename on GitHub (needs a one-click settings change from the user - SSH cannot rename repos), deploy the Render blueprint, embed this saved agent session in the post, then publish the draft.

Prize Categories

Best Use of Gemma: Gemma 3 1B runs locally through llama.cpp and writes the field notes.
Best Use of Render: the live demo runs on Render with the included render.yaml.

Built for Hacktoberfest 2026. Files, models, and data stay on the machine, with no key, no upload, and no network.