The "Localhost" Trap: Networking Microservices in Docker Compose

Omar Lashin — Tue, 12 May 2026 08:23:44 +0000

The "It Works On My Machine" Illusion
You've built a beautiful, decoupled microservices architecture. Your Node/Express API runs smoothly on port 3000, and your React frontend fetches data perfectly from http://localhost:3000/api. You containerize both services, spin them up with Docker Compose, and suddenly the frontend crashes with a Connection Refused error.

What happened? You fell into the localhost trap.

Understanding Docker's Internal Network
When running services locally without Docker, localhost refers to your host machine. Both your frontend and backend share this environment. However, when you containerize these services, Docker creates an isolated virtual network. Inside a container, localhost no longer refers to your laptop; it refers to the container itself.

When your React container tries to fetch from localhost:3000, it is looking inside its own isolated environment, where the Node API does not exist.

*The Solution: DNS Resolution via Compose
Docker Compose automatically sets up a custom bridge network and provides internal DNS resolution using the service names defined in your docker-compose.yml.

Let's look at a standard compose file:

version: '3.8'
services:
  api-service:
    build: ./backend
    ports:
      - "3000:3000"

  web-client:
    build: ./frontend
    ports:
      - "8080:80"
    depends_on:
      - api-service

To fix the connection refused error, you must stop hardcoding localhost. If your backend needs to communicate with another containerized service from the server-side, it must use the exact service name defined in the YAML file as the hostname.

// BAD: Fails inside a Docker container
const response = await fetch('http://localhost:3000/api/users');

// GOOD: Utilizes Docker's internal DNS resolver
const response = await fetch('http://api-service:3000/api/users');

By respecting Docker's internal network topography, we ensure our microservices can communicate seamlessly, regardless of the host machine they are deployed on.

Taming Unpredictable User Input: Building a RAG Triage Agent in Node.js

Omar Lashin — Tue, 12 May 2026 08:18:12 +0000

The Problem with Raw User Data
When building the backend for an urban infrastructure platform, the biggest bottleneck isn't the database, it's the users. A citizen reporting a problem rarely uses structured terminology. They don't say, "Electrical failure, Priority 1, Jurisdiction: City Council." They say, "The streetlamp on 5th avenue is sparking and my dog is terrified."

Passing this raw text directly into a database requires a human administrator to manually read and route every single ticket. To automate this, we need to extract structured JSON from unstructured panic.

The RAG Solution
Instead of relying on a raw LLM (which might hallucinate categories that our database doesn't accept), we implemented a lightweight Retrieval-Augmented Generation (RAG) pipeline in Node.js. By feeding the LLM our strict database schemas and city department rules alongside the user prompt, we force it to act as a deterministic triage agent.

Here is a simplified version of the extraction logic using the OpenAI API:

async function categorizeIssue(userReport, cityRulesContext) {
  const systemPrompt = `
    You are a strict city infrastructure triage agent. 
    Analyze the user report against the provided City Rules context.
    You must return ONLY a JSON object with the following keys:
    - category (string: must be one of the approved categories in context)
    - severity (integer: 1-5)
    - department (string: target routing department)
  `;

  const response = await openai.chat.completions.create({
    model: "gpt-4-turbo",
    response_format: { type: "json_object" },
    messages: [
      { role: "system", content: systemPrompt },
      { role: "user", content: `Context: ${cityRulesContext}\n\nReport: ${userReport}` }
    ]
  });

  return JSON.parse(response.choices[0].message.content);
}

By utilizing the response_format: { type: "json_object" } flag, we ensure the output is ready for our Express.js backend to ingest. The Node server doesn't know it's talking to an AI; it just receives a perfectly formatted JSON payload, completely bridging the gap between natural language and strict database requirements.

DEV Community: Omar Lashin

The "Localhost" Trap: Networking Microservices in Docker Compose

Taming Unpredictable User Input: Building a RAG Triage Agent in Node.js