DEV Community: Ian Ochieng

# Building SemaKazi Part 3: Adding Tests (and Why I Had to Refactor First)

Ian Ochieng — Mon, 03 Aug 2026 08:02:15 +0000

SemaKazi is a verified reputation platform for Kenya's informal-sector workers — electricians, carpenters, mechanics, tailors — solving the trust gap between a fundi's real skill and a client's ability to verify it before hiring. Backend shipped in Phase 1, frontend (auth, search, profiles, dashboard) shipped in Phase 2. Today was Phase 4: tests.

The problem with testing an Express app that just... runs

My server.js did two jobs at once: configure the Express app and call app.listen() to start it on a fixed port. That's fine for running the app, but it makes it nearly impossible to test cleanly — you can't import "the app" without also starting a real server bound to a real port, which collides with whatever's already running in dev.

The fix is a pattern I'd read about but never actually needed until today: split it in two.

app.js — builds and returns a configured Express app. No listen() call.
server.js — imports that app, calls .listen(), and that's it.

Now tests can import app.js, spin up an instance on port: 0 (which tells the OS "just give me any free port"), run requests against it, and tear it down — no collisions, no fixed ports, no interference with a dev server that might already be running.

What got tested

Seven tests, using Node's built-in test runner and native fetch — no new dependencies:

Health check responds correctly
Registration creates a user and returns a token
Duplicate email registration is rejected
Login succeeds with correct credentials, fails with wrong ones
Protected routes reject requests with no token
Search returns fundis with correct average rating and review count
A user cannot edit another user's profile (ownership check)

Each test run gets its own throwaway SQLite file, cleaned up after — so tests never touch the real dev database.

Why this specific set

Not exhaustive coverage — just the kinds of things that already broke once. The .env/JWT issue from Phase 1 and the profile.js/profiles.js naming mismatch were both only caught by manual curl testing at the time. A real test suite means the next regression like that gets caught automatically instead of by trial and error in a terminal.

Small refactor, real lesson

The actual code that broke in the past week wasn't complicated. What made debugging slow was structure — a server file that couldn't be tested in isolation, a file name that silently worked in one environment and failed in another. Fixing the shape of the code turned out to matter more than adding more code.

What's left

One small frontend polish item — the API base URL is currently hardcoded to localhost, which needs to be configurable before deployment — then Phase 5: getting this live.

Repo's public if you want to see the test file or the before/after of the refactor.

Building SemaKazi Part 2: Starting the Frontend, No Framework Required

Ian Ochieng — Sat, 01 Aug 2026 11:19:45 +0000

Phase 1 of SemaKazi (a verified reputation platform for Kenya's informal-sector workers — electricians, carpenters, mechanics, tailors) shipped a working backend: auth, profiles, proof-of-work, reviews, badges, all tested end-to-end. Today I started Phase 2 — the frontend.

Keeping it deliberately simple

No React, no build step, no bundler. Just HTML, CSS, and vanilla JavaScript talking to the API with fetch. For a project this size, reaching for a framework would've added ceremony without adding value — the goal is working software, not a tech showcase.

What went in today

The skeleton first. Before any actual pages, I built the shared pieces every page would need:

api.js — one object (api.register, api.login, api.searchProfiles, etc.) wrapping every backend call, so no page has to write raw fetch logic or handle auth headers manually
nav.js — a nav bar that swaps its links depending on whether you're logged in
style.css — shared design tokens (cards, buttons, forms) so every page that comes later looks consistent without repeating CSS

Building this first meant every page after it could focus purely on its own logic instead of re-solving "how do I call the API" five separate times.

Then the actual auth pages — registration (with a role picker that shows trade/location fields only if you're signing up as a fundi) and login. Both store the JWT and redirect to a dashboard that... doesn't exist yet. That's fine — it's the next branch, and I'd rather see an honest 404 now than pretend the flow is finished.

The part that actually tripped me up

Folder structure. register.html and login.html needed to sit in a pages/ subfolder, which meant every relative path inside them (../css/style.css, ../js/api.js) had to account for being one level deeper than index.html. Small thing, easy to get backwards, and a good reminder that "confusing" doesn't mean "hard" — sometimes it's just unfamiliar, and the fix is five minutes of careful checking, not a rabbit hole.

Workflow, still

Same discipline as Phase 1: one feature branch per unit of work, each file its own commit, PR descriptions with a summary/why/testing/notes section, merged into main only after local testing against the live backend.

What's next

Search page, then the fundi profile view, then the dashboard those auth pages are currently redirecting to.

Repo's public if you want to follow the commit history as it grows.

Building SemaKazi Part 1: Shipping a Backend the Way Real Teams Do It

Ian Ochieng — Fri, 31 Jul 2026 13:15:12 +0000

Kenya has one of the youngest populations in the world, and most of that workforce works in the informal sector — electricians, carpenters, mechanics, tailors, the people we call "fundis." The problem is simple: there's no digital way for a skilled fundi to prove they're actually skilled. Clients hire based on word-of-mouth alone, which caps good workers to their existing network and lets anyone claim expertise they don't have.

That's the problem SemaKazi is solving — a platform where fundis build a verifiable reputation through proof-of-work uploads, client ratings, and peer-endorsed skill badges.

Today was Phase 1: the backend foundation. Here's what actually went into it.

The stack

Node.js + Express, SQLite (via better-sqlite3) for the database, JWT + bcrypt for auth. Nothing exotic — the goal was a clean, working API, not a tech showcase.

What got built

Data models: users (fundis and clients), proof-of-work entries, reviews, and skill badges — with foreign keys and indexes where the queries actually need them
Auth: register/login with hashed passwords, JWT middleware to protect routes, and an ownership check so users can only edit their own data
Core endpoints: profile search/view, proof-of-work CRUD, review submission, and badge endorsements

Doing it like a real project, not a script

The part I actually wanted to practice wasn't the code — it was the workflow around it:

A proper README and PRD before any code, with an explicit out-of-scope section (no payments, no in-app chat, no admin dashboard in this version — deliberately)
One feature branch per unit of work, merged via pull requests with real descriptions (summary, why, testing notes, known gaps)
GitHub Issues tied to a project board, closed out as each feature merged
A tagged release (v0.1.0-phase1) marking the milestone on main

The bug that actually taught me something

Everything worked in my Codespace. Then I pulled the same repo onto my local machine and got:

Error: Cannot find module './routes/profiles'

Turned out one route file was named profile.js (singular) while the code that required it expected profiles.js (plural). It had worked by accident in one environment and failed correctly in another — a good reminder that "it runs on my machine" isn't the same as "it's actually correct." Renamed the file, committed the fix, moved on.

What's next

Phase 2 is the frontend — wiring up the UI to these endpoints and adding real media upload for proof-of-work. Phase 1 is tagged, merged, and done.

Following along? The repo's public — feel free to poke through the commit history to see how the branches came together.

How I Tamed Legacy Docker (v1.29) for Multi-Stage Microservice Builds

Ian Ochieng — Thu, 30 Jul 2026 13:55:32 +0000

Working with modern multi-stage Dockerfiles on legacy server environments can feel like fitting a square peg into a round hole. While updating the container infrastructure for flexiride-backend—a monorepo running 15 microservices—I ran into a wall with a legacy Docker Engine environment (v1.29.2).

Here is how I adapted our multi-stage build pipeline across 9 active microservices without requiring BuildKit, root privileges, or breaking our build architecture.

The Challenge: Modern Multi-Stage vs. Legacy Daemon

Our goal was straightforward: standardize Dockerfile.base across our active microservices and gateways (auth, user, driver, booking, matching, payment, notification, web-bff, and mobile-bff) to produce consistent :jvm runtime images.

However, legacy Docker v1.29.2 presented three hard constraints:

No BuildKit Support: Modern caching mechanisms like --mount=type=cache failed instantly.
Sequential Target Evaluation: Without BuildKit's smart DAG evaluation, legacy Docker couldn't skip late-stage GraalVM native image compilation steps, even when we only requested the intermediate JVM runtime target.
Restricted Environment: No root privileges were available to upgrade the underlying local engine or daemon.

The Workarounds

1. Reordering `Dockerfile.base` Targets

Because legacy Docker processes build stages sequentially, putting heavy or optional downstream stages first forces the builder to run them regardless of target flags.

By reordering Dockerfile.base to prioritize JVM runtime stages before GraalVM steps, the build pipeline completes the JVM image cleanly before hitting unsupported toolchains.

2. Explicit Stage Targets in Docker Compose

To force legacy Docker to stop cleanly at the JVM stage, I declared explicit build targets across docker-compose.yml:

services:
  auth:
    build:
      context: .
      dockerfile: Dockerfile.base
      target: "false" # Explicitly targets JVM runtime stage on legacy engines
    image: flexirides/auth:jvm

This stopped legacy Docker from executing past the JVM stage and kept image naming completely standardized across services (flexirides/<service-name>:jvm).

Verification & Results

After updating the build definitions, all 9 microservices compiled, tagged, and ran successfully.

1. Tagged Image Consistency

We verified that all 9 images compiled completely without errors and followed standardized naming conventions (flexirides/<service-name>:jvm):

2. Service Bootstrapping

Spun up the auth microservice using docker-compose up -d auth and monitored its transition to an Up (healthy) state:

3. Spring Boot Actuator Health Check

Finally, we queried the service's health endpoint (GET http://localhost:8086/actuator/health) to confirm database connectivity and application readiness:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "UP"
}

Key Takeaways

Stage ordering matters on older Docker daemons that lack BuildKit's dynamic target skipping.
Explicit target declarations in docker-compose.yml prevent legacy engines from running unnecessary build stages.
Always validate microservice readiness with runtime health checks (like Spring Actuator) rather than assuming a successful docker build means a working container.

Have you had to support legacy Docker engines in your production environments? How did you handle multi-stage builds? Let's discuss below!

DEV Community: Ian Ochieng

# Building SemaKazi Part 3: Adding Tests (and Why I Had to Refactor First)

The problem with testing an Express app that just... runs

What got tested

Why this specific set

Small refactor, real lesson

What's left

Building SemaKazi Part 2: Starting the Frontend, No Framework Required

Keeping it deliberately simple

What went in today

The part that actually tripped me up

Workflow, still

What's next

Building SemaKazi Part 1: Shipping a Backend the Way Real Teams Do It

The stack

What got built

Doing it like a real project, not a script

The bug that actually taught me something

What's next

How I Tamed Legacy Docker (v1.29) for Multi-Stage Microservice Builds

The Challenge: Modern Multi-Stage vs. Legacy Daemon

The Workarounds

1. Reordering Dockerfile.base Targets

2. Explicit Stage Targets in Docker Compose

Verification & Results

1. Tagged Image Consistency

2. Service Bootstrapping

3. Spring Boot Actuator Health Check

Key Takeaways

1. Reordering `Dockerfile.base` Targets