<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Ian Ochieng</title>
    <description>The latest articles on DEV Community by Ian Ochieng (@iochieng1).</description>
    <link>https://dev.to/iochieng1</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F3953641%2Fd17366eb-7766-4bcf-b157-602c3d0e5d44.jpeg</url>
      <title>DEV Community: Ian Ochieng</title>
      <link>https://dev.to/iochieng1</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/iochieng1"/>
    <language>en</language>
    <item>
      <title>Building an M-Pesa gateway that can't double-charge: idempotency, state machines and signed webhooks</title>
      <dc:creator>Ian Ochieng</dc:creator>
      <pubDate>Mon, 16 Nov 2026 12:43:08 +0000</pubDate>
      <link>https://dev.to/iochieng1/building-an-m-pesa-gateway-that-cant-double-charge-idempotency-state-machines-and-signed-webhooks-3c3i</link>
      <guid>https://dev.to/iochieng1/building-an-m-pesa-gateway-that-cant-double-charge-idempotency-state-machines-and-signed-webhooks-3c3i</guid>
      <description>&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fclalu1bsixa7dfz6wdw7.gif" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fclalu1bsixa7dfz6wdw7.gif" alt="Demo: a merchant creates a payment, the customer approves the M-Pesa prompt, and a signed payment.succeeded webhook arrives" width="560" height="532"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;Accepting M-Pesa in an app looks easy. You call Safaricom's Daraja API, the customer gets a PIN prompt (an "STK push"), and Daraja calls you back with the result.&lt;/p&gt;

&lt;p&gt;The trouble starts after that call. Callbacks arrive twice, arrive late or never arrive. They aren't signed. Your HTTP client times out, retries, and the customer gets two prompts. Each of these can mean taking someone's money twice, or marking an order unpaid when it was paid.&lt;/p&gt;

&lt;p&gt;I built &lt;a href="https://github.com/iochieng1/paybridge" rel="noopener noreferrer"&gt;PayBridge&lt;/a&gt;, a small payments gateway that sits between apps and Daraja, to handle these cases properly. Here are the four ideas that do most of the work.&lt;/p&gt;

&lt;h2&gt;
  
  
  1. Let Postgres decide who goes first
&lt;/h2&gt;

&lt;p&gt;A merchant's server sends &lt;code&gt;POST /v1/payments&lt;/code&gt; with an &lt;code&gt;Idempotency-Key&lt;/code&gt; header. If the request times out, it retries with the same key. The retry must not send a second STK push.&lt;/p&gt;

&lt;p&gt;The usual check-then-insert is a race:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// ❌ Two concurrent retries can both see "no key" and both charge.&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;existing&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;findKey&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;merchantId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;key&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;existing&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;insertKey&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;merchantId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;key&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;sendStkPush&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Instead, the claim is a single statement:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;INSERT&lt;/span&gt; &lt;span class="k"&gt;INTO&lt;/span&gt; &lt;span class="n"&gt;idempotency_keys&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;merchant_id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;key&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;request_hash&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;VALUES&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;$1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nv"&gt;$3&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="k"&gt;CONFLICT&lt;/span&gt; &lt;span class="k"&gt;DO&lt;/span&gt; &lt;span class="k"&gt;NOTHING&lt;/span&gt;
&lt;span class="k"&gt;RETURNING&lt;/span&gt; &lt;span class="k"&gt;key&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The primary key is &lt;code&gt;(merchant_id, key)&lt;/code&gt;. However many requests arrive at once, Postgres lets exactly one insert through. That request sends the push. The others get &lt;code&gt;409 Retry-After: 1&lt;/code&gt; while it runs, and a replay of its stored response once it's done. The row also stores a hash of the request body, so reusing a key for a &lt;em&gt;different&lt;/em&gt; payment gets &lt;code&gt;422&lt;/code&gt; instead of silently returning the wrong payment.&lt;/p&gt;

&lt;p&gt;One subtle rule: if anything fails &lt;strong&gt;after&lt;/strong&gt; Daraja was called, the key is never released. A retry that gets &lt;code&gt;409&lt;/code&gt; until the key expires is annoying. Releasing the key could charge the customer twice.&lt;/p&gt;

&lt;h2&gt;
  
  
  2. A state machine that only moves forward
&lt;/h2&gt;

&lt;p&gt;A payment goes &lt;code&gt;CREATED → PENDING → SUCCEEDED | FAILED | CANCELLED | TIMED_OUT&lt;/code&gt;. Every change is one conditional update:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;UPDATE&lt;/span&gt; &lt;span class="n"&gt;payments&lt;/span&gt;
&lt;span class="k"&gt;SET&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nv"&gt;$new_status&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;
&lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nv"&gt;$id&lt;/span&gt; &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="k"&gt;IN&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s1"&gt;'CREATED'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'PENDING'&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;RETURNING&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If no row comes back, the payment was already final, so nothing happens. A duplicate callback, a replay, or a late "failed" arriving after a success all update no row and record no event. Daraja still gets &lt;code&gt;200&lt;/code&gt; so it stops resending. The audit event is inserted in the same transaction, so the history can't disagree with the status.&lt;/p&gt;

&lt;p&gt;The test I like most sends 10 copies of the same callback &lt;strong&gt;concurrently&lt;/strong&gt; and asserts that exactly one &lt;code&gt;callback_applied&lt;/code&gt; event exists. It runs against real Postgres via Testcontainers, because a mock can't test a row lock.&lt;/p&gt;

&lt;h2&gt;
  
  
  3. Callbacks aren't signed, so use three checks
&lt;/h2&gt;

&lt;p&gt;Anyone who finds a callback URL can post &lt;code&gt;"ResultCode": 0&lt;/code&gt;. PayBridge layers three checks:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;A secret URL per payment.&lt;/strong&gt; Each callback URL carries 256 random bits, and only its SHA-256 hash is stored.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;An optional IP allowlist&lt;/strong&gt; for Safaricom's ranges, so a leaked URL is useless from elsewhere.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Verification for anything odd.&lt;/strong&gt; If the amount doesn't match, the receipt is missing or the checkout ID is wrong, PayBridge asks Daraja directly with STK Push Query and applies &lt;em&gt;that&lt;/em&gt; answer, never the callback's claim.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  4. Assume the callback never comes
&lt;/h2&gt;

&lt;p&gt;Sometimes Daraja just doesn't call back. A job runs every minute (a BullMQ repeatable job), finds payments stuck in &lt;code&gt;PENDING&lt;/code&gt; for over 2 minutes, and asks Daraja for their status. It applies the result with the &lt;strong&gt;same&lt;/strong&gt; conditional update, so a reconciliation that races a late callback still settles the payment exactly once.&lt;/p&gt;

&lt;h2&gt;
  
  
  Telling the merchant: signed webhooks
&lt;/h2&gt;

&lt;p&gt;When a payment is final, PayBridge POSTs it to the merchant:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;X-PayBridge-Signature: t=1794000000,v1=&amp;lt;hex HMAC-SHA256(secret, "t.body")&amp;gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ul&gt;
&lt;li&gt;The &lt;strong&gt;timestamp is part of what's signed&lt;/strong&gt;, so a captured request can't be replayed later with a new timestamp. Receivers reject anything older than 5 minutes.&lt;/li&gt;
&lt;li&gt;Retries happen after 1m, 5m, 30m, 2h and 12h, and every attempt is logged and visible through the API.&lt;/li&gt;
&lt;li&gt;Delivery is &lt;strong&gt;at least once&lt;/strong&gt;: if the merchant's &lt;code&gt;200&lt;/code&gt; gets lost, PayBridge can't know. Each payment has one stable event ID, so merchants can safely drop duplicates.&lt;/li&gt;
&lt;li&gt;The merchant's URL is checked against private address ranges &lt;strong&gt;inside the socket's DNS lookup&lt;/strong&gt;, so a URL can't point PayBridge at &lt;code&gt;169.254.169.254&lt;/code&gt; or an internal service, even through DNS rebinding.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  What I'd tell myself at the start
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Make the database enforce your invariants.&lt;/strong&gt; Unique constraints, conditional updates and advisory locks are much harder to get wrong than application-level checks.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Test against real infrastructure.&lt;/strong&gt; Every important guarantee here comes from Postgres or a Redis Lua script.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;"Unknown" is a real state.&lt;/strong&gt; A timeout doesn't mean failure. Leaving the payment &lt;code&gt;PENDING&lt;/code&gt; and letting the callback or reconciliation decide is what keeps money correct.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The code, a full trade-offs section and the OpenAPI docs are on &lt;a href="https://github.com/iochieng1/paybridge" rel="noopener noreferrer"&gt;GitHub&lt;/a&gt;. It runs against the Daraja sandbox, so you can &lt;a href="https://paybridge-api-1s9j.onrender.com/docs" rel="noopener noreferrer"&gt;try it live&lt;/a&gt; without moving real money.&lt;/p&gt;

</description>
      <category>typescript</category>
      <category>node</category>
      <category>postgres</category>
      <category>fintech</category>
    </item>
    <item>
      <title>"It works on my machine": 6 ways to share your localhost (and pick the right one in 30 seconds)</title>
      <dc:creator>Ian Ochieng</dc:creator>
      <pubDate>Fri, 30 Oct 2026 10:34:35 +0000</pubDate>
      <link>https://dev.to/iochieng1/it-works-on-my-machine-6-ways-to-share-your-localhost-and-pick-the-right-one-in-30-seconds-46cd</link>
      <guid>https://dev.to/iochieng1/it-works-on-my-machine-6-ways-to-share-your-localhost-and-pick-the-right-one-in-30-seconds-46cd</guid>
      <description>&lt;p&gt;You've just finished a feature. It runs perfectly on &lt;code&gt;localhost:3000&lt;/code&gt;. You send the link to a teammate and they reply:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;"This site can't be reached."&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Of course. &lt;code&gt;localhost&lt;/code&gt; means &lt;em&gt;this&lt;/em&gt; machine. Nobody else's.&lt;/p&gt;

&lt;p&gt;This post walks through &lt;strong&gt;six ways to share your localhost&lt;/strong&gt;, from "same Wi-Fi, zero install" to "public HTTPS URL in one command". Before you scroll, take the quiz below. It'll tell you which section to jump to.&lt;/p&gt;




&lt;h2&gt;
  
  
  🧭 Quick quiz: which one do you need?
&lt;/h2&gt;

&lt;p&gt;Answer these three questions and keep score in your head.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;1. Who needs to see it?&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;(a) My phone or a laptop on the same Wi-Fi&lt;/li&gt;
&lt;li&gt;(b) Someone outside my network: a client, a teammate at home, a webhook&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;2. Can you install something?&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;(a) Nope, locked-down machine&lt;/li&gt;
&lt;li&gt;(b) Sure&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;3. How long does the link need to live?&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;(a) Ten minutes, for a quick demo&lt;/li&gt;
&lt;li&gt;(b) Days or weeks, with the same URL every time&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;/p&gt;
  👉 Click for your answer
  &lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;1a:&lt;/strong&gt; go to Method 1, LAN sharing. No tools needed.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;1b + 2a:&lt;/strong&gt; go to Method 2, SSH tunnel. You already have &lt;code&gt;ssh&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;1b + 2b + 3a:&lt;/strong&gt; go to Method 3, Cloudflare quick tunnel or Method 4, ngrok.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;1b + 3b:&lt;/strong&gt; go to Method 5, Tailscale Funnel or a named Cloudflare tunnel.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;You live in VS Code:&lt;/strong&gt; go to Method 6, VS Code port forwarding.&lt;/li&gt;
&lt;/ul&gt;



&lt;p&gt;&lt;/p&gt;




&lt;h2&gt;
  
  
  1. Same Wi-Fi? Just bind to &lt;code&gt;0.0.0.0&lt;/code&gt;
&lt;/h2&gt;

&lt;p&gt;Most dev servers listen on &lt;code&gt;127.0.0.1&lt;/code&gt; by default. That's the loopback interface: only your own machine can connect to it. Tell the server to listen on &lt;strong&gt;all&lt;/strong&gt; interfaces instead:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# Vite&lt;/span&gt;
npm run dev &lt;span class="nt"&gt;--&lt;/span&gt; &lt;span class="nt"&gt;--host&lt;/span&gt;

&lt;span class="c"&gt;# Next.js&lt;/span&gt;
npx next dev &lt;span class="nt"&gt;-H&lt;/span&gt; 0.0.0.0

&lt;span class="c"&gt;# Python static server&lt;/span&gt;
python3 &lt;span class="nt"&gt;-m&lt;/span&gt; http.server 8000 &lt;span class="nt"&gt;--bind&lt;/span&gt; 0.0.0.0

&lt;span class="c"&gt;# Go&lt;/span&gt;
http.ListenAndServe&lt;span class="o"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"0.0.0.0:8080"&lt;/span&gt;, nil&lt;span class="o"&gt;)&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then find your machine's local IP:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;hostname&lt;/span&gt; &lt;span class="nt"&gt;-I&lt;/span&gt;              &lt;span class="c"&gt;# Linux&lt;/span&gt;
ipconfig getifaddr en0   &lt;span class="c"&gt;# macOS&lt;/span&gt;
ipconfig                 &lt;span class="c"&gt;# Windows (look for "IPv4 Address")&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Open &lt;code&gt;http://192.168.x.x:3000&lt;/code&gt; on your phone. Done.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Good for:&lt;/strong&gt; testing on real mobile devices.&lt;br&gt;
&lt;strong&gt;Watch out for:&lt;/strong&gt; public/café Wi-Fi often blocks device-to-device traffic, and your firewall (&lt;code&gt;ufw&lt;/code&gt;, Windows Defender) may need to allow the port.&lt;/p&gt;


&lt;h2&gt;
  
  
  2. SSH tunnel: nothing to install
&lt;/h2&gt;

&lt;p&gt;If you have &lt;code&gt;ssh&lt;/code&gt; (and you do), you have a tunnel:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;ssh &lt;span class="nt"&gt;-R&lt;/span&gt; 80:localhost:3000 nokey@localhost.run
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It prints a public HTTPS URL. Anyone on the internet can open it until you close the terminal.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Good for:&lt;/strong&gt; locked-down machines and one-off demos.&lt;br&gt;
&lt;strong&gt;Watch out for:&lt;/strong&gt; the free URL changes every session.&lt;/p&gt;


&lt;h2&gt;
  
  
  3. Cloudflare quick tunnel
&lt;/h2&gt;

&lt;p&gt;Install &lt;code&gt;cloudflared&lt;/code&gt;, then:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;cloudflared tunnel &lt;span class="nt"&gt;--url&lt;/span&gt; http://localhost:3000
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;You get a random &lt;code&gt;https://something.trycloudflare.com&lt;/code&gt; URL. No account needed for quick tunnels.&lt;/p&gt;

&lt;p&gt;Want a stable URL on your own domain? Log in and create a &lt;strong&gt;named tunnel&lt;/strong&gt;. Same tool, permanent hostname.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Good for:&lt;/strong&gt; fast, free, HTTPS by default.&lt;/p&gt;




&lt;h2&gt;
  
  
  4. ngrok
&lt;/h2&gt;

&lt;p&gt;The classic. Sign up once, add your auth token, then:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;ngrok http 3000
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The killer feature is the &lt;strong&gt;local inspector&lt;/strong&gt; at &lt;code&gt;http://127.0.0.1:4040&lt;/code&gt;. You can see every request that hit your tunnel and &lt;strong&gt;replay&lt;/strong&gt; it. If you're debugging Stripe, GitHub or M-Pesa webhooks, this saves hours.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Good for:&lt;/strong&gt; webhook development.&lt;/p&gt;




&lt;h2&gt;
  
  
  5. Tailscale Funnel
&lt;/h2&gt;

&lt;p&gt;If you already use Tailscale to reach your own devices, Funnel exposes a port to the public internet on a stable &lt;code&gt;*.ts.net&lt;/code&gt; HTTPS address:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;tailscale funnel 3000
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If you only need &lt;em&gt;your team&lt;/em&gt; to see it (not the whole internet), skip Funnel and share over the tailnet privately. That's the more secure option.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Good for:&lt;/strong&gt; long-lived links with the same URL every time.&lt;/p&gt;




&lt;h2&gt;
  
  
  6. VS Code port forwarding
&lt;/h2&gt;

&lt;p&gt;Open the &lt;strong&gt;Ports&lt;/strong&gt; panel (next to Terminal), click &lt;strong&gt;Forward a Port&lt;/strong&gt;, enter &lt;code&gt;3000&lt;/code&gt;, sign in with GitHub. Right-click the port and set visibility to &lt;strong&gt;Public&lt;/strong&gt; if someone without a GitHub login needs it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Good for:&lt;/strong&gt; zero context-switching if you're already in the editor.&lt;/p&gt;




&lt;h2&gt;
  
  
  🐛 "The tunnel works but my app is broken"
&lt;/h2&gt;

&lt;p&gt;You'll probably hit at least one of these:&lt;/p&gt;

&lt;p&gt;&lt;/p&gt;
  "Blocked request. This host is not allowed." (Vite)
  &lt;br&gt;
Newer Vite versions reject unknown hostnames. Add the tunnel host to your config:&lt;br&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight javascript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// vite.config.js&lt;/span&gt;
&lt;span class="k"&gt;export&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="na"&gt;server&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="na"&gt;allowedHosts&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;.trycloudflare.com&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="s1"&gt;.ngrok-free.app&lt;/span&gt;&lt;span class="dl"&gt;'&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;


&lt;p&gt;For webpack-dev-server, the equivalent is &lt;code&gt;allowedHosts: 'all'&lt;/code&gt;.&lt;br&gt;
&lt;/p&gt;

&lt;br&gt;
&lt;p&gt;&lt;/p&gt;

&lt;p&gt;&lt;/p&gt;
  The page loads but API calls fail
  &lt;br&gt;
Your frontend is probably still calling &lt;code&gt;http://localhost:8080/api&lt;/code&gt;. On &lt;em&gt;their&lt;/em&gt; machine, that's &lt;em&gt;their&lt;/em&gt; localhost. Use a relative path (&lt;code&gt;/api&lt;/code&gt;) behind a dev proxy, or tunnel the backend too.&lt;br&gt;


&lt;p&gt;&lt;/p&gt;

&lt;p&gt;&lt;/p&gt;
  Login works locally but not through the tunnel
  &lt;br&gt;
Cookies set with &lt;code&gt;Secure&lt;/code&gt; or &lt;code&gt;SameSite&lt;/code&gt; rules, plus OAuth redirect URIs, are tied to the hostname. Add the tunnel URL to your OAuth app's allowed redirects and check your cookie domain.&lt;br&gt;


&lt;p&gt;&lt;/p&gt;

&lt;p&gt;&lt;/p&gt;
  Hot reload is dead
  &lt;br&gt;
HMR runs over a WebSocket. Most tunnels support WebSockets, but your dev server may try to connect to &lt;code&gt;localhost&lt;/code&gt;. In Vite, set &lt;code&gt;server.hmr.clientPort: 443&lt;/code&gt; when you're behind an HTTPS tunnel.&lt;br&gt;


&lt;p&gt;&lt;/p&gt;




&lt;h2&gt;
  
  
  🔒 Before you share: a 4-point safety check
&lt;/h2&gt;

&lt;p&gt;A public tunnel is a &lt;strong&gt;public server&lt;/strong&gt;. Bots find new URLs within minutes.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;[ ] No real secrets or production data in the app you're exposing&lt;/li&gt;
&lt;li&gt;[ ] Debug panels and admin routes are off (or behind auth)&lt;/li&gt;
&lt;li&gt;[ ] You'll &lt;strong&gt;close the tunnel&lt;/strong&gt; when the demo ends&lt;/li&gt;
&lt;li&gt;[ ] For anything longer than a demo, add auth (most tunnel tools support basic auth or SSO)&lt;/li&gt;
&lt;/ul&gt;




&lt;h2&gt;
  
  
  Cheat sheet
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Need&lt;/th&gt;
&lt;th&gt;Command&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Phone on the same Wi-Fi&lt;/td&gt;
&lt;td&gt;&lt;code&gt;npm run dev -- --host&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Public URL, no install&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ssh -R 80:localhost:3000 nokey@localhost.run&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Public URL, no account&lt;/td&gt;
&lt;td&gt;&lt;code&gt;cloudflared tunnel --url http://localhost:3000&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Webhook debugging&lt;/td&gt;
&lt;td&gt;&lt;code&gt;ngrok http 3000&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Stable URL&lt;/td&gt;
&lt;td&gt;&lt;code&gt;tailscale funnel 3000&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Already in VS Code&lt;/td&gt;
&lt;td&gt;Ports panel → Forward a Port&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;




&lt;h2&gt;
  
  
  💬 Your turn
&lt;/h2&gt;

&lt;p&gt;I'm curious what everyone actually uses:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Which method is your go-to?&lt;/strong&gt; Drop the number (1–6) in the comments.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;What's the weirdest bug you've hit through a tunnel?&lt;/strong&gt; I'll add the best ones to the troubleshooting section above.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Challenge:&lt;/strong&gt; run one of these commands right now and share your app with someone. Then tell me how long it took, from typing the command to them opening the link. ⏱️&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;If this saved you a "can't be reached" message, a ❤️ or 🦄 helps other devs find it.&lt;/p&gt;

</description>
      <category>webdev</category>
      <category>beginners</category>
      <category>devops</category>
      <category>tutorial</category>
    </item>
    <item>
      <title>Debugging Expo: Fixing Node v18 Incompatibilities and Network ETIMEDOUT Errors on Linux</title>
      <dc:creator>Ian Ochieng</dc:creator>
      <pubDate>Tue, 22 Sep 2026 11:41:47 +0000</pubDate>
      <link>https://dev.to/iochieng1/debugging-expo-fixing-node-v18-incompatibilities-and-network-etimedout-errors-on-linux-1j57</link>
      <guid>https://dev.to/iochieng1/debugging-expo-fixing-node-v18-incompatibilities-and-network-etimedout-errors-on-linux-1j57</guid>
      <description>&lt;p&gt;Setting up a fresh mobile workspace can sometimes feel like running an obstacle course. If you’ve ever run &lt;code&gt;npx create-expo-app&lt;/code&gt; only to be met with a wall of engine warnings, random &lt;code&gt;ReferenceError: File is not defined&lt;/code&gt; breaks, and persistent &lt;code&gt;ETIMEDOUT&lt;/code&gt; network failures, you are not alone.&lt;/p&gt;

&lt;p&gt;Here is exactly why these errors happen on a Linux environment and a bulletproof roadmap to fixing them.&lt;/p&gt;




&lt;h2&gt;
  
  
  The Culprit 1: Node.js Version Mismatch
&lt;/h2&gt;

&lt;p&gt;Modern scaffolding tools move fast. The latest editions of &lt;code&gt;create-expo-app&lt;/code&gt; heavily leverage modern Web APIs natively inside the runtime environment (specifically the global &lt;code&gt;File&lt;/code&gt; interface). &lt;/p&gt;

&lt;p&gt;If you are running an older LTS release like &lt;strong&gt;Node v18.19.1&lt;/strong&gt;, you will trigger an internal crash:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;npm WARN EBADENGINE package: &lt;span class="s1"&gt;'create-expo-app@5.0.0'&lt;/span&gt;, required: &lt;span class="o"&gt;{&lt;/span&gt; node: &lt;span class="s1"&gt;'&amp;gt;=20.0.0'&lt;/span&gt; &lt;span class="o"&gt;}&lt;/span&gt;
ReferenceError: File is not defined
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  The Solution: Node Version Manager (NVM)
&lt;/h3&gt;

&lt;p&gt;Don't rely on system package managers like &lt;code&gt;apt&lt;/code&gt; which often trail behind. Pull down the repository manually, configure your profile, and upgrade to the recommended target (Node 22):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# Clone the repository&lt;/span&gt;
git clone https://github.com ~/.nvm
&lt;span class="nb"&gt;cd&lt;/span&gt; ~/.nvm &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; git checkout v0.40.1 &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;cd&lt;/span&gt; ~

&lt;span class="c"&gt;# Register NVM to your shell profile&lt;/span&gt;
&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s1"&gt;'export NVM_DIR="$HOME/.nvm"'&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&amp;gt;&lt;/span&gt; ~/.bashrc
&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s1"&gt;'[ -s "$NVM_DIR/nvm.sh" ] &amp;amp;&amp;amp; \. "$NVM_DIR/nvm.sh"'&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&amp;gt;&lt;/span&gt; ~/.bashrc
&lt;span class="nb"&gt;source&lt;/span&gt; ~/.bashrc

&lt;span class="c"&gt;# Switch to the stable runtime&lt;/span&gt;
nvm &lt;span class="nb"&gt;install &lt;/span&gt;22
nvm use 22
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;






&lt;h2&gt;
  
  
  The Culprit 2: The &lt;code&gt;ETIMEDOUT&lt;/code&gt; Registry Wall
&lt;/h2&gt;

&lt;p&gt;If you are working on a company asset or behind restrictive network routing layers, standard interactive initializations can drop packets. Expo CLI's pre-download validation steps check versions remotely; if your gateway delays this handshake, you will get hit with an &lt;code&gt;AggregateError [ETIMEDOUT]&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  The Solution: Bypass CLI Network Checks
&lt;/h3&gt;

&lt;p&gt;When &lt;code&gt;npx expo install&lt;/code&gt; times out checking SDK compatibility tables, you can skip the middleman. Explicitly declare your target packages and pass a massive timeout flag (&lt;code&gt;npm_config_timeout=600000&lt;/code&gt;) directly to standard &lt;code&gt;npm&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nv"&gt;npm_config_timeout&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;600000 npm &lt;span class="nb"&gt;install&lt;/span&gt; @react-native-async-storage/async-storage@1.24.0 @react-native-community/netinfo@11.4.1
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;em&gt;This circumvents the CLI wrapper check and pulls the packages down directly via the direct registry stream.&lt;/em&gt;&lt;/p&gt;




&lt;h2&gt;
  
  
  The Culprit 3: Jest Transpilation Failures (&lt;code&gt;Unexpected token&lt;/code&gt;)
&lt;/h2&gt;

&lt;p&gt;Once your dependencies are in, writing tests with modern features like TypeScript type assertions (&lt;code&gt;as const&lt;/code&gt;) can make Jest choke out of the box:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;SyntaxError: Unexpected token, expected ","
  &amp;gt; 16 |       category: 'flooding' as const,
       |                            ^
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This happens because Jest runs inside basic Node and needs an explicit instruction set to clean up TypeScript syntax before executing assertions.&lt;/p&gt;

&lt;h3&gt;
  
  
  The Solution: Add the Expo Babel Engine
&lt;/h3&gt;

&lt;p&gt;You need to explicitly feed the &lt;code&gt;babel-preset-expo&lt;/code&gt; compilation module to your project development dependencies and configure Jest to use it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# Install the missing preset engine&lt;/span&gt;
npm &lt;span class="nb"&gt;install&lt;/span&gt; &lt;span class="nt"&gt;--save-dev&lt;/span&gt; babel-preset-expo

&lt;span class="c"&gt;# Create your babel.config.js&lt;/span&gt;
&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"module.exports = function(api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
  };
};"&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; babel.config.js
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Finally, assign the global preset config layer inside your &lt;code&gt;package.json&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="nl"&gt;"jest"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"preset"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"jest-expo"&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Now, typing &lt;code&gt;npm test&lt;/code&gt; will yield clean green checkmarks across your test suites! &lt;/p&gt;




&lt;h2&gt;
  
  
  Wrapped Up and Ready
&lt;/h2&gt;

&lt;p&gt;Debugging infrastructure issues can be draining, but understanding the underlying breaks—Node runtime constraints, network wrappers, and transpiler rules—turns a frustrating block into a minor bump. &lt;/p&gt;

&lt;p&gt;Have you hit similar walls with Expo or WSL networking? Drop your workarounds below!&lt;/p&gt;

</description>
      <category>reactnative</category>
      <category>expo</category>
      <category>typescript</category>
      <category>debugging</category>
    </item>
    <item>
      <title># Building SemaKazi Part 3: Adding Tests (and Why I Had to Refactor First)</title>
      <dc:creator>Ian Ochieng</dc:creator>
      <pubDate>Mon, 03 Aug 2026 08:02:15 +0000</pubDate>
      <link>https://dev.to/iochieng1/-building-semakazi-part-3-adding-tests-and-why-i-had-to-refactor-first-2pne</link>
      <guid>https://dev.to/iochieng1/-building-semakazi-part-3-adding-tests-and-why-i-had-to-refactor-first-2pne</guid>
      <description>&lt;p&gt;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.&lt;/p&gt;

&lt;h2&gt;
  
  
  The problem with testing an Express app that just... runs
&lt;/h2&gt;

&lt;p&gt;My &lt;code&gt;server.js&lt;/code&gt; did two jobs at once: configure the Express app &lt;em&gt;and&lt;/em&gt; call &lt;code&gt;app.listen()&lt;/code&gt; 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.&lt;/p&gt;

&lt;p&gt;The fix is a pattern I'd read about but never actually needed until today: split it in two.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;app.js&lt;/code&gt; — builds and returns a configured Express app. No &lt;code&gt;listen()&lt;/code&gt; call.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;server.js&lt;/code&gt; — imports that app, calls &lt;code&gt;.listen()&lt;/code&gt;, and that's it.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Now tests can import &lt;code&gt;app.js&lt;/code&gt;, spin up an instance on &lt;code&gt;port: 0&lt;/code&gt; (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.&lt;/p&gt;

&lt;h2&gt;
  
  
  What got tested
&lt;/h2&gt;

&lt;p&gt;Seven tests, using Node's built-in test runner and native &lt;code&gt;fetch&lt;/code&gt; — no new dependencies:&lt;/p&gt;

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

&lt;p&gt;Each test run gets its own throwaway SQLite file, cleaned up after — so tests never touch the real dev database.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why this specific set
&lt;/h2&gt;

&lt;p&gt;Not exhaustive coverage — just the kinds of things that already broke once. The &lt;code&gt;.env&lt;/code&gt;/JWT issue from Phase 1 and the &lt;code&gt;profile.js&lt;/code&gt;/&lt;code&gt;profiles.js&lt;/code&gt; naming mismatch were both only caught by manual &lt;code&gt;curl&lt;/code&gt; 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.&lt;/p&gt;

&lt;h2&gt;
  
  
  Small refactor, real lesson
&lt;/h2&gt;

&lt;p&gt;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 &lt;em&gt;shape&lt;/em&gt; of the code turned out to matter more than adding more code.&lt;/p&gt;

&lt;h2&gt;
  
  
  What's left
&lt;/h2&gt;

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




&lt;p&gt;&lt;em&gt;Repo's public if you want to see the test file or the before/after of the refactor.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>javascript</category>
      <category>node</category>
      <category>refactoring</category>
      <category>testing</category>
    </item>
    <item>
      <title>Building SemaKazi Part 2: Starting the Frontend, No Framework Required</title>
      <dc:creator>Ian Ochieng</dc:creator>
      <pubDate>Sat, 01 Aug 2026 11:19:45 +0000</pubDate>
      <link>https://dev.to/iochieng1/-building-semakazi-part-2-starting-the-frontend-no-framework-required-2j02</link>
      <guid>https://dev.to/iochieng1/-building-semakazi-part-2-starting-the-frontend-no-framework-required-2j02</guid>
      <description>&lt;p&gt;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.&lt;/p&gt;

&lt;h2&gt;
  
  
  Keeping it deliberately simple
&lt;/h2&gt;

&lt;p&gt;No React, no build step, no bundler. Just HTML, CSS, and vanilla JavaScript talking to the API with &lt;code&gt;fetch&lt;/code&gt;. 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.&lt;/p&gt;

&lt;h2&gt;
  
  
  What went in today
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;The skeleton first.&lt;/strong&gt; Before any actual pages, I built the shared pieces every page would need:&lt;/p&gt;

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

&lt;p&gt;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.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Then the actual auth pages&lt;/strong&gt; — 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.&lt;/p&gt;

&lt;h2&gt;
  
  
  The part that actually tripped me up
&lt;/h2&gt;

&lt;p&gt;Folder structure. &lt;code&gt;register.html&lt;/code&gt; and &lt;code&gt;login.html&lt;/code&gt; needed to sit in a &lt;code&gt;pages/&lt;/code&gt; subfolder, which meant every relative path inside them (&lt;code&gt;../css/style.css&lt;/code&gt;, &lt;code&gt;../js/api.js&lt;/code&gt;) had to account for being one level deeper than &lt;code&gt;index.html&lt;/code&gt;. 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.&lt;/p&gt;

&lt;h2&gt;
  
  
  Workflow, still
&lt;/h2&gt;

&lt;p&gt;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 &lt;code&gt;main&lt;/code&gt; only after local testing against the live backend.&lt;/p&gt;

&lt;h2&gt;
  
  
  What's next
&lt;/h2&gt;

&lt;p&gt;Search page, then the fundi profile view, then the dashboard those auth pages are currently redirecting to.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Repo's public if you want to follow the commit history as it grows.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>webdev</category>
      <category>node</category>
      <category>github</category>
      <category>opensource</category>
    </item>
    <item>
      <title>Building SemaKazi Part 1: Shipping a Backend the Way Real Teams Do It</title>
      <dc:creator>Ian Ochieng</dc:creator>
      <pubDate>Fri, 31 Jul 2026 13:15:12 +0000</pubDate>
      <link>https://dev.to/iochieng1/building-semakazi-part-1-shipping-a-backend-the-way-real-teams-do-it-32da</link>
      <guid>https://dev.to/iochieng1/building-semakazi-part-1-shipping-a-backend-the-way-real-teams-do-it-32da</guid>
      <description>&lt;p&gt;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.&lt;/p&gt;

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

&lt;p&gt;Today was Phase 1: the backend foundation. Here's what actually went into it.&lt;/p&gt;

&lt;h2&gt;
  
  
  The stack
&lt;/h2&gt;

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

&lt;h2&gt;
  
  
  What got built
&lt;/h2&gt;

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

&lt;h2&gt;
  
  
  Doing it like a real project, not a script
&lt;/h2&gt;

&lt;p&gt;The part I actually wanted to practice wasn't the code — it was the workflow around it:&lt;/p&gt;

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

&lt;h2&gt;
  
  
  The bug that actually taught me something
&lt;/h2&gt;

&lt;p&gt;Everything worked in my Codespace. Then I pulled the same repo onto my local machine and got:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Error: Cannot find module './routes/profiles'
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Turned out one route file was named &lt;code&gt;profile.js&lt;/code&gt; (singular) while the code that required it expected &lt;code&gt;profiles.js&lt;/code&gt; (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.&lt;/p&gt;

&lt;h2&gt;
  
  
  What's next
&lt;/h2&gt;

&lt;p&gt;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.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Following along? The repo's public — feel free to poke through the commit history to see how the branches came together.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>webdev</category>
      <category>github</category>
      <category>opensource</category>
      <category>node</category>
    </item>
    <item>
      <title>How I Tamed Legacy Docker (v1.29) for Multi-Stage Microservice Builds</title>
      <dc:creator>Ian Ochieng</dc:creator>
      <pubDate>Thu, 30 Jul 2026 13:55:32 +0000</pubDate>
      <link>https://dev.to/iochieng1/how-i-tamed-legacy-docker-v129-for-multi-stage-microservice-builds-596c</link>
      <guid>https://dev.to/iochieng1/how-i-tamed-legacy-docker-v129-for-multi-stage-microservice-builds-596c</guid>
      <description>&lt;p&gt;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 &lt;strong&gt;flexiride-backend&lt;/strong&gt;—a monorepo running 15 microservices—I ran into a wall with a legacy Docker Engine environment (&lt;code&gt;v1.29.2&lt;/code&gt;). &lt;/p&gt;

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




&lt;h2&gt;
  
  
  The Challenge: Modern Multi-Stage vs. Legacy Daemon
&lt;/h2&gt;

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

&lt;p&gt;However, legacy Docker &lt;code&gt;v1.29.2&lt;/code&gt; presented three hard constraints:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;No BuildKit Support:&lt;/strong&gt; Modern caching mechanisms like &lt;code&gt;--mount=type=cache&lt;/code&gt; failed instantly.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Sequential Target Evaluation:&lt;/strong&gt; 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.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Restricted Environment:&lt;/strong&gt; No root privileges were available to upgrade the underlying local engine or daemon.&lt;/li&gt;
&lt;/ol&gt;




&lt;h2&gt;
  
  
  The Workarounds
&lt;/h2&gt;

&lt;h3&gt;
  
  
  1. Reordering &lt;code&gt;Dockerfile.base&lt;/code&gt; Targets
&lt;/h3&gt;

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

&lt;p&gt;By &lt;strong&gt;reordering &lt;code&gt;Dockerfile.base&lt;/code&gt; to prioritize JVM runtime stages before GraalVM steps&lt;/strong&gt;, the build pipeline completes the JVM image cleanly before hitting unsupported toolchains.&lt;/p&gt;

&lt;h3&gt;
  
  
  2. Explicit Stage Targets in Docker Compose
&lt;/h3&gt;

&lt;p&gt;To force legacy Docker to stop cleanly at the JVM stage, I declared explicit build targets across &lt;code&gt;docker-compose.yml&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="na"&gt;services&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
  &lt;span class="na"&gt;auth&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
    &lt;span class="na"&gt;build&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt;
      &lt;span class="na"&gt;context&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;.&lt;/span&gt;
      &lt;span class="na"&gt;dockerfile&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Dockerfile.base&lt;/span&gt;
      &lt;span class="na"&gt;target&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;false"&lt;/span&gt; &lt;span class="c1"&gt;# Explicitly targets JVM runtime stage on legacy engines&lt;/span&gt;
    &lt;span class="na"&gt;image&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;flexirides/auth:jvm&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This stopped legacy Docker from executing past the JVM stage and kept image naming completely standardized across services (&lt;code&gt;flexirides/&amp;lt;service-name&amp;gt;:jvm&lt;/code&gt;).&lt;/p&gt;




&lt;h2&gt;
  
  
  Verification &amp;amp; Results
&lt;/h2&gt;

&lt;p&gt;After updating the build definitions, all 9 microservices compiled, tagged, and ran successfully.&lt;/p&gt;

&lt;h3&gt;
  
  
  1. Tagged Image Consistency
&lt;/h3&gt;

&lt;p&gt;We verified that all 9 images compiled completely without errors and followed standardized naming conventions (&lt;code&gt;flexirides/&amp;lt;service-name&amp;gt;:jvm&lt;/code&gt;):&lt;br&gt;
&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F1tbqlndpyxcbuf6770g7.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F1tbqlndpyxcbuf6770g7.png" alt="Compiled Docker Images List" width="800" height="452"&gt;&lt;/a&gt;&lt;/p&gt;
&lt;h3&gt;
  
  
  2. Service Bootstrapping
&lt;/h3&gt;

&lt;p&gt;Spun up the &lt;code&gt;auth&lt;/code&gt; microservice using &lt;code&gt;docker-compose up -d auth&lt;/code&gt; and monitored its transition to an &lt;code&gt;Up (healthy)&lt;/code&gt; state:&lt;br&gt;
&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fu73y1ee0v0tt8baz61q3.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fu73y1ee0v0tt8baz61q3.png" alt="Docker Container Status" width="800" height="452"&gt;&lt;/a&gt;&lt;/p&gt;
&lt;h3&gt;
  
  
  3. Spring Boot Actuator Health Check
&lt;/h3&gt;

&lt;p&gt;Finally, we queried the service's health endpoint (&lt;code&gt;GET http://localhost:8086/actuator/health&lt;/code&gt;) to confirm database connectivity and application readiness:&lt;br&gt;
&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fbb8cmv6w9x96am8ias91.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fbb8cmv6w9x96am8ias91.png" alt="Spring Actuator Health Check" width="800" height="321"&gt;&lt;/a&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight http"&gt;&lt;code&gt;&lt;span class="k"&gt;HTTP&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="m"&gt;1.1&lt;/span&gt; &lt;span class="m"&gt;200&lt;/span&gt; &lt;span class="ne"&gt;OK&lt;/span&gt;
&lt;span class="na"&gt;Content-Type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;application/json&lt;/span&gt;

&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"UP"&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;






&lt;h2&gt;
  
  
  Key Takeaways
&lt;/h2&gt;

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




&lt;p&gt;&lt;em&gt;Have you had to support legacy Docker engines in your production environments? How did you handle multi-stage builds? Let's discuss below!&lt;/em&gt;&lt;/p&gt;

</description>
      <category>docker</category>
      <category>devops</category>
      <category>java</category>
      <category>microservices</category>
    </item>
  </channel>
</rss>
