Forem: Teguh Coding

Stop Using useEffect for Everything: A Better Approach in Modern React

Teguh Coding — Tue, 10 Mar 2026 06:07:13 +0000

Stop Using useEffect for Everything: A Better Approach in Modern React

The Problem with useEffect Overuse

If you have been writing React for a while, you have likely experienced this: you need to fetch data when a component mounts, so you reach for useEffect. Then you need to update some state based on props changing, so you add another useEffect. Next thing you know, your component has five different useEffect hooks scattered throughout, and you have lost track of when each one runs.

I have been there. The useEffect hook feels like a superpower - it can handle side effects, data fetching, subscriptions, and more. But with great power comes great responsibility, and it is easy to abuse this hook.

When useEffect Actually Makes Sense

Let me be clear: useEffect is not bad. It is an essential tool. The problem is using it as the default solution for every problem.

Legitimate use cases for useEffect:

Subscribing to external data sources (WebSocket, EventSource)
Manually interacting with the DOM (when refs are not enough)
Logging analytics events
Cleanup operations that can not be handled otherwise

The Better Alternatives

1. Fetch Data Directly in Components (Server Components)

In Next.js App Router, you can fetch data directly in your component:

// app/users/page.jsx
async function UsersPage() {
  const users = await fetch("https://api.example.com/users", {
    cache: "no-store" // for dynamic data
  }).then(res => res.json());

  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}

No useEffect, no loading states to manage manually, no race conditions. Just pure, simple code.

2. Use use() for Promise Resolution

React 19 introduced the use() hook, which makes handling promises elegant:

import { use } from "react";

function UserProfile({ userPromise }) {
  const user = use(userPromise);

  return <h1>{user.name}</h1>;
}

This is so much cleaner than the old:

const [user, setUser] = useState(null);
const [loading, setLoading] = useState(true);

useEffect(() => {
  userPromise.then(data => {
    setUser(data);
    setLoading(false);
  });
}, [userPromise]);

if (loading) return <Spinner />;

3. Derive State from Props

Instead of syncing state with props via useEffect:

// Do not do this
function Counter({ initialCount }) {
  const [count, setCount] = useState(initialCount);

  useEffect(() => {
    setCount(initialCount);
  }, [initialCount]);

  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
}

// Do this instead
function Counter({ initialCount }) {
  // Just use the prop directly if it is the source of truth
  const [count, setCount] = useState(initialCount);

  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
}

// Or derive when you need to transform
function UserGreeting({ firstName, lastName }) {
  const fullName = `${firstName} ${lastName}`; // Derived, no state needed
  return <h1>Hello, {fullName}!</h1>;
}

4. Handle Events Directly

Instead of using useEffect to respond to state changes:

// Do not do this
function SearchInput({ onSearch }) {
  const [query, setQuery] = useState("");

  useEffect(() => {
    onSearch(query);
  }, [query, onSearch]);

  return <input value={query} onChange={e => setQuery(e.target.value)} />;
}

// Do this
function SearchInput({ onSearch }) {
  const [query, setQuery] = useState("");

  const handleChange = (e) => {
    const value = e.target.value;
    setQuery(value);
    onSearch(value);
  };

  return <input value={query} onChange={handleChange} />;
}

A Mental Model Shift

The key insight is this: think in data flow, not in lifecycle events.

Ask yourself:

Where does this data come from? (Props, server, context)
Who owns this state? (Parent, local, server)
When should this update? (On event, on render, on mount)

Modern React (with Server Components, use(), and better patterns) encourages you to write code that describes what you want, not when to do it.

Conclusion

useEffect is not going anywhere, but it is not the first tool you should reach for anymore. With Next.js App Router, React Server Components, and hooks like use(), you can write simpler, more maintainable code.

Next time you are tempted to add a useEffect, pause and ask: "Is there a simpler way?"

Your future self will thank you when debugging at 2 AM.

What is your take? Have you moved away from useEffect in your projects? Let me know in the comments!

5 Node.js Patterns That Saved Me Hours of Debugging

Teguh Coding — Mon, 09 Mar 2026 18:06:24 +0000

5 Node.js Patterns That Saved Me Hours of Debugging

After years of writing Node.js applications, I have learned that the difference between maintainable code and spaghetti code often comes down to a few key patterns. Today, I want to share five patterns that have completely transformed how I write and debug Node.js applications.

1. The Repository Pattern: Decoupling Data Access

One of the biggest mistakes I see in Node.js applications is directly using database queries throughout controllers and services. This creates tight coupling and makes testing a nightmare.

Instead, I use the Repository pattern to abstract data access:

// repositories/UserRepository.js
class UserRepository {
  constructor(database) {
    this.db = database;
  }

  async findById(id) {
    return this.db.users.findOne({ id });
  }

  async findByEmail(email) {
    return this.db.users.findOne({ email });
  }

  async create(userData) {
    return this.db.users.create(userData);
  }
}

module.exports = UserRepository;

Now your controller does not care if you are using MongoDB, PostgreSQL, or a mock database. This single change made our tests run 10x faster because we could easily swap in an in-memory database.

2. Error Handling Middleware: One Place for All Errors

Forget try-catch blocks scattered throughout your code. Express has a powerful middleware system that handles errors beautifully:

// Middleware error handler (must be LAST middleware)
const errorHandler = (err, req, res, next) => {
  console.error("Error:", err);

  if (err.name === "ValidationError") {
    return res.status(400).json({
      error: "Validation Failed",
      details: err.message
    });
  }

  if (err.name === "UnauthorizedError") {
    return res.status(401).json({
      error: "Authentication Required"
    });
  }

  // Do not leak error details in production
  res.status(500).json({
    error: process.env.NODE_ENV === "production"
      ? "Internal Server Error"
      : err.message
  });
};

app.use(errorHandler);

The key insight: always put your error handler LAST in the middleware stack. This ensures it catches all errors from all routes.

3. The Builder Pattern for Complex Queries

When building APIs, we often need to construct complex database queries based on optional filters. The Builder pattern makes this clean and readable:

class UserQueryBuilder {
  constructor() {
    this.filters = {};
    this.sort = {};
    this.limit = 50;
    this.offset = 0;
  }

  withRole(role) {
    this.filters.role = role;
    return this;
  }

  withStatus(status) {
    this.filters.status = status;
    return this;
  }

  createdAfter(date) {
    this.filters.createdAt = { $gte: date };
    return this;
  }

  sortedBy(field, order = "desc") {
    this.sort[field] = order;
    return this;
  }

  paginated(page, perPage) {
    this.limit = perPage;
    this.offset = (page - 1) * perPage;
    return this;
  }

  build() {
    return {
      query: this.filters,
      sort: this.sort,
      limit: this.limit,
      offset: this.offset
    };
  }
}

// Usage becomes beautifully readable
const query = new UserQueryBuilder()
  .withRole("admin")
  .withStatus("active")
  .createdAfter(new Date("2025-01-01"))
  .sortedBy("createdAt")
  .paginated(1, 20)
  .build();

No more messy conditional logic scattered throughout your route handlers.

4. Dependency Injection: Making Code Testable

This is the pattern that had the biggest impact on my Node.js applications. Instead of importing modules directly, we inject dependencies:

// Before: Tightly coupled, hard to test
class UserService {
  async getUser(id) {
    const user = await db.users.findOne({ id });
    const emailService = new EmailService();
    await emailService.sendWelcome(user.email);
    return user;
  }
}

// After: Dependency Injection
class UserService {
  constructor(userRepository, emailService) {
    this.userRepository = userRepository;
    this.emailService = emailService;
  }

  async getUser(id) {
    const user = await this.userRepository.findById(id);
    if (user) {
      await this.emailService.sendWelcome(user.email);
    }
    return user;
  }
}

// Easy testing with mocks
const mockRepo = {
  findById: async () => ({ id: 1, email: "test@example.com" })
};

const mockEmail = {
  sendWelcome: async () => {}
};

const service = new UserService(mockRepo, mockEmail);

Now you can test UserService without touching the database or sending real emails. Game changer.

5. Event-Driven Architecture for Loose Coupling

Instead of directly calling services within your business logic, emit events and let listeners handle side effects:

const EventEmitter = require("events");

// Create a dedicated event bus
const eventBus = new EventEmitter();

// In your service, emit events instead of calling other services
class OrderService {
  async createOrder(orderData) {
    const order = await this.orderRepository.create(orderData);

    // Emit event - do not call other services directly
    eventBus.emit("order.created", {
      orderId: order.id,
      customerEmail: order.customerEmail,
      total: order.total
    });

    return order;
  }
}

// Listeners handle the rest (in a separate file or module)
eventBus.on("order.created", async (data) => {
  await sendConfirmationEmail(data.customerEmail, data.orderId);
  await updateInventory(data.orderId);
  await analytics.track("order_created", data);
});

eventBus.on("order.created", async (data) => {
  if (data.total > 1000) {
    await sendHighValueAlert(data);
  }
});

This pattern makes your code remarkably flexible. Want to add a new side effect? Just add another listener. Want to disable something? Comment out or remove the listener. No code changes to your core business logic.

The Bigger Picture

These patterns share a common theme: they reduce complexity by creating clear boundaries between different parts of your application. When something breaks, you know exactly where to look. When you need to add features, you know exactly where to add them.

Start implementing one pattern at a time. Your future self will thank you when debugging takes minutes instead of hours.

What patterns have saved your Node.js development? I would love to hear about your experiences in the comments.

Next.js App Router: The Patterns That Actually Matter in 2026

Teguh Coding — Mon, 09 Mar 2026 06:08:05 +0000

Next.js App Router: The Patterns That Actually Matter in 2026

How to stop fighting the framework and start building real features

The Moment Everything Clicked

I remember the day Next.js 13 dropped with the App Router. I was three months into a project, deeply invested in the Pages Router, and suddenly felt like I had to relearn everything. Client components, server components, streaming, suspense - it was overwhelming.

Six months later, I rewrote that entire project. And you know what? It was faster. Not just the app - my development speed too.

Here is what I wish someone had told me back then.

Stop Thinking in Pages

The biggest mental shift is not technical. It is architectural.

With the Pages Router, you thought in pages. Each route was a standalone island. getServerSideProps fetched data, and that was that.

App Router changes the question. Instead of "What page am I building?" you start asking "What should the user see immediately, and what can wait?"

This is the essence of partial prerendering and streaming - and once you internalize it, everything else falls into place.

The Three Component Types (Simplified)

Let me cut through the confusion. You really only need to understand three scenarios:

1. Server Components (Default)

// This is a Server Component by default
async function BlogPost({ slug }: { slug: string }) {
  // Direct database access - no API routes needed
  const post = await db.posts.findUnique({ where: { slug } });

  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
    </article>
  );
}

Use these for: data fetching, accessing backend resources, keeping sensitive logic server-side.

2. Client Components (When You Need Interactivity)

'use client';

import { useState, useEffect } from 'react';

function SearchInput() {
  const [query, setQuery] = useState('');

  // Real-time search with debouncing
  useEffect(() => {
    const timer = setTimeout(() => {
      if (query) searchAPI(query);
    }, 300);
    return () => clearTimeout(timer);
  }, [query]);

  return (
    <input 
      value={query}
      onChange={(e) => setQuery(e.target.value)}
      placeholder="Search posts..."
    />
  );
}

Use these for: state, event handlers, browser APIs, third-party hooks.

3. The Composition Pattern

This is where magic happens - mixing server and client in the same component tree:

// app/posts/page.tsx (Server Component)
import { Suspense } from 'react';
import SearchInput from './search-input';
import PostList from './post-list';

export default async function PostsPage() {
  const posts = await getPosts(); // Server-side fetch

  return (
    <main>
      <h1>Blog Posts</h1>

      {/* Client component for interactivity */}
      <SearchInput />

      {/* Pass server data to client component */}
      <Suspense fallback={<PostSkeleton />}>
        <PostList initialPosts={posts} />
      </Suspense>
    </main>
  );
}

The key insight: Server Components can import Client Components, but not vice versa. Pass data down as props.

The Data Fetching Revolution

Forget useEffect for data fetching in most cases. Server Components changed the game:

// Old way (still works, but unnecessary now)
function Post() {
  const [post, setPost] = useState(null);

  useEffect(() => {
    fetch('/api/post').then(res => res.json())
      .then(setPost);
  }, []);

  if (!post) return <Skeleton />;
  return <div>{post.title}</div>;
}

// New way (Server Component)
async function Post({ id }: { id: string }) {
  const post = await fetch(`https://api.example.com/posts/${id}`, {
    cache: 'no-store' // or 'force-cache' for static
  }).then(res => res.json());

  return <div>{post.title}</div>;
}

No loading states to manage manually. No race conditions. No "fetch in useEffect" debates.

Caching: Your New Best Friend

Next.js now caches aggressively. Here is how to work with it:

// Static data - cached by default
async function getStaticContent() {
  const res = await fetch('https://api.example.com/about');
  return res.json();
}

// Dynamic data - revalidated on each request
async function getUserData() {
  const res = await fetch('https://api.example.com/user', {
    cache: 'no-store'
  });
  return res.json();
}

// Revalidate every hour
async function getBlogPosts() {
  const res = await fetch('https://api.example.com/posts', {
    next: { revalidate: 3600 }
  });
  return res.json();
}

Pro tip: Use export const dynamic = 'force-dynamic' at the top of a page to make the entire page dynamic.

The Routing Patterns That Scale

Organize your routes intentionally:

app/
├── (marketing)/          # Route group - no URL impact
│   ├── page.tsx         # /
│   └── pricing/
│       └── page.tsx     # /pricing
├── (app)/               # Authenticated routes
│   ├── dashboard/
│   │   ├── page.tsx    # /dashboard
│   │   └── layout.tsx  # Dashboard-specific layout
│   └── settings/
│       └── page.tsx    # /settings
└── api/                  # API routes (still work!)
    └── posts/
        └── route.ts    # /api/posts

Route groups let you share layouts without affecting URLs - perfect for separating marketing pages from authenticated app sections.

What Still Trip People Up

After helping dozens of teams migrate, here are the common mistakes:

1. Making everything use client

If it does not need browser APIs or state, keep it on the server. Your bundle will thank you.

2. Ignoring Suspense boundaries

Use Suspense to wrap slow components. Do not let one slow fetch block your entire page:

<Suspense fallback={<ProductSkeleton />}>
  <ProductReviews productId={id} />
</Suspense>

<Suspense fallback={<RelatedSkeleton />}>
  <RelatedProducts category={category} />
</Suspense>

Both components load in parallel.

3. Forgetting about route handlers

API routes still exist and work great. Use them for:

Webhooks
Custom form submissions
External API proxies
Anything that needs POST/PUT/DELETE

The Bottom Line

App Router is not just a new syntax. It is a different mental model. Once you stop thinking about "pages" and start thinking about "what the user needs first," everything clicks.

Start with Server Components by default. Add use client only when you need interactivity. Pass data down as props. Let Suspense handle the rest.

The framework does the hard work. Your job is to give it the right components to work with.

Building something with Next.js 14? I would love to hear about it. Drop a comment below.

React #NextJS #JavaScript #WebDevelopment #Programming

Use the New use() Hook in React 19 for Cleaner Async Components

Teguh Coding — Sun, 08 Mar 2026 18:07:19 +0000

Use the New use() Hook in React 19 for Cleaner Async Components

If you have been working with React for a while, you have probably dealt with the headache of handling async data in components. Between useEffect, useState, and various data-fetching libraries, the code often becomes cluttered. React 19 introduces a game-changing solution: the use() hook.

Let me show you how this new hook simplifies async data handling and makes your code much cleaner.

The Old Way: Verbose and Error-Prone

Before React 19, fetching data inside a component looked something like this:

function UserProfile({ userId }) {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    setLoading(true);
    fetch(`/api/users/${userId}`)
      .then(res => res.json())
      .then(data => {
        setUser(data);
        setLoading(false);
      })
      .catch(err => {
        setError(err);
        setLoading(false);
      });
  }, [userId]);

  if (loading) return <Spinner />;
  if (error) return <Error message={error.message} />;

  return <div>{user.name}</div>;
}

That is a lot of boilerplate for a simple data fetch. You have to manage three different states, handle the effect dependency correctly, and hope you did not miss any edge cases.

The New Way: Clean and Declarative

React 19s use() hook changes everything. It suspends the component while the promise resolves, handling loading and error states at a higher level in your component tree.

import { use } from 'react';

function UserProfile({ userId }) {
  const user = use(fetchUser(userId));

  return <div>{user.name}</div>;
}

That is it. No state management, no effects, no boilerplate. The component simply waits for the promise to resolve.

How It Actually Works

The use() hook accepts a promise and:

Suspends the component if the promise is pending
Resumes with the resolved value when ready
Throws the error if rejected (which you can catch with an Error Boundary)

Here is a complete example with a realistic data-fetching scenario:

import { use, Suspense, ErrorBoundary } from 'react';

// Async function that returns a promise
async function fetchUser(userId) {
  const res = await fetch(`/api/users/${userId}`);
  if (!res.ok) throw new Error('Failed to fetch user');
  return res.json();
}

function UserProfile({ userId }) {
  const user = use(fetchUser(userId));

  return (
    <div className="user-profile">
      <h2>{user.name}</h2>
      <p>{user.email}</p>
      <span>{user.role}</span>
    </div>
  );
}

// Wrap it with Suspense and ErrorBoundary
function App() {
  return (
    <ErrorBoundary fallback={<ErrorDisplay />}>
      <Suspense fallback={<LoadingSkeleton />}>
        <UserProfile userId="123" />
      </Suspense>
    </ErrorBoundary>
  );
}

Handling Multiple Async Values

One of the best features is how use() handles multiple promises elegantly:

function Dashboard({ userId }) {
  const [user, posts] = use(Promise.all([
    fetchUser(userId),
    fetchPosts(userId)
  ]));

  return (
    <div>
      <h1>Welcome, {user.name}</h1>
      <PostList posts={posts} />
    </div>
  );
}

No more promise.all + useState + useEffect combinations. Just write async code directly in your component.

Integrating with Existing Patterns

You can still use use() with your existing data-fetching libraries. For example, with TanStack Query:

import { useQuery } from '@tanstack/react-query';
import { use } from 'react';

function UserAvatar({ userId }) {
  const query = useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetchUser(userId)
  });

  // Convert to promise for use()
  const user = use(query.isSuccess ? Promise.resolve(query.data) : new Promise(() => {}));

  return <img src={user.avatar} alt={user.name} />;
}

Or create a simple wrapper:

function useAsync(asyncFn) {
  return use(Promise.resolve().then(() => asyncFn()));
}

function UserCard({ userId }) {
  const user = useAsync(() => fetchUser(userId));
  return <div>{user.name}</div>;
}

Error Handling Done Right

The use() hook integrates beautifully with Reacts Error Boundary pattern:

function PostWithComments({ postId }) {
  const post = use(fetchPost(postId));
  const comments = use(fetchComments(postId));

  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.content}</p>
      <CommentsList comments={comments} />
    </article>
  );
}

// Any error in the component tree bubbles up to the Error Boundary
function ErrorFallback({ error }) {
  return <div className="error">Something went wrong: {error.message}</div>;
}

<ErrorBoundary fallback={<ErrorFallback />}>
  <Suspense fallback={<Loading />}>
    <PostWithComments postId="123" />
  </Suspense>
</ErrorBoundary>

When to Use use() vs useEffect

Use use() when:

You need to fetch data that renders in the component
You want simpler, more readable async code
You are building with Suspense in mind

Stick with useEffect when:

You are handling side effects (logging, analytics)
The data does not directly render in the component
You need fine-grained control over when fetching happens

The Bigger Picture

The use() hook is not just syntactic sugar—it is part of Reacts vision for "React 19: The Era of Async." Combined with Server Components and Actions, it represents a fundamental shift in how we build React applications.

Instead of managing loading states in every component, you define them once at the top level and let React handle the rest. It is a cleaner mental model and results in less code.

Give It a Try

If you are on React 19 (or using the beta), start experimenting with use() in your components. You will be surprised how quickly the boilerplate disappears and how much more readable your async code becomes.

The future of React is async-native. Embrace it.

What do you think about the new use() hook? Have you tried it yet? Drop your thoughts in the comments below.

Building REST APIs That Don't Suck: Patterns I Wish I Knew Sooner

Teguh Coding — Sun, 08 Mar 2026 06:07:16 +0000

Building REST APIs That Don't Suck: Patterns I Wish I Knew Sooner

After building dozens of APIs in production, I've learned that the difference between an API that developers love and one they secretly hate often comes down to a few key patterns. Today, I'm sharing five approaches that have saved me countless debugging sessions and made my codebases actually maintainable.

1. The Repository Pattern: Abstraction That Actually Helps

Here's something I see too often: business logic tangled directly with database calls scattered across route handlers. It's a mess to test and even worse to debug at 2 AM.

The repository pattern changed this for me completely. Instead of mixing concerns, I abstract all data access:

// repositories/UserRepository.js
class UserRepository {
  constructor(database) {
    this.db = database;
  }

  async findById(id) {
    return this.db.users.findUnique({ where: { id } });
  }

  async findByEmail(email) {
    return this.db.users.findUnique({ where: { email } });
  }

  async create(data) {
    return this.db.users.create({ data });
  }

  async update(id, data) {
    return this.db.users.update({ where: { id }, data });
  }
}

module.exports = UserRepository;

Now my route handlers stay clean, and swapping databases later doesn't require rewriting half my application. The key insight? Your routes should never know whether you're using PostgreSQL, MongoDB, or an in-memory array for testing.

2. Consistent Error Responses: Save Your Future Self

I used to return different error formats across endpoints. Sometimes it was { error: "Message" }, other times { message: "Message" }, and occasionally just a raw string. My frontend colleagues rightfully complained.

Now everything follows a consistent structure:

// utils/apiResponse.js
class ApiResponse {
  static success(data, meta = {}) {
    return {
      success: true,
      data,
      meta,
      timestamp: new Date().toISOString()
    };
  }

  static error(message, code = 'INTERNAL_ERROR', statusCode = 500) {
    return {
      success: false,
      error: {
        code,
        message,
        timestamp: new Date().toISOString()
      }
    };
  }

  static validationError(errors) {
    return {
      success: false,
      error: {
        code: 'VALIDATION_ERROR',
        message: 'Invalid input data',
        details: errors,
        timestamp: new Date().toISOString()
      }
    };
  }
}

// Usage in Express
app.get('/users/:id', async (req, res) => {
  try {
    const user = await userService.findById(req.params.id);
    if (!user) {
      return res.status(404).json(
        ApiResponse.error('User not found', 'NOT_FOUND', 404)
      );
    }
    res.json(ApiResponse.success(user));
  } catch (error) {
    res.status(500).json(ApiResponse.error('Something went wrong'));
  }
});

This consistency means my error handling middleware can be centralized, and my frontend team can build predictable error UI.

3. The Service Layer: Where Business Logic Lives

Routes should be thin. I mean really thin. Your route files should only handle HTTP concerns: parsing requests, calling services, and formatting responses. Everything else goes into services:

// services/UserService.js
class UserService {
  constructor(userRepository, emailService) {
    this.userRepository = userRepository;
    this.emailService = emailService;
  }

  async registerUser(userData) {
    // Business validation
    const existing = await this.userRepository.findByEmail(userData.email);
    if (existing) {
      throw new ConflictError('Email already registered');
    }

    // Hash password (never in routes!)
    const hashedPassword = await bcrypt.hash(userData.password, 12);

    // Create user
    const user = await this.userRepository.create({
      ...userData,
      password: hashedPassword
    });

    // Send welcome email
    await this.emailService.sendWelcome(user.email);

    // Return without sensitive data
    const { password, ...safeUser } = user;
    return safeUser;
  }
}

The magic here is testability. I can test my business logic without spinning up an HTTP server. I can mock dependencies easily. My tests read like documentation.

4. Request Validation: Fail Fast, Fail Clear

Validation at the database level is too late. You want to reject invalid requests before they touch your business logic. I use Zod for schema validation:

// validators/userValidator.js
const createUserSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8).regex(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)/, 
    'Password must contain uppercase, lowercase, and number'),
  name: z.string().min(2).max(100),
  role: z.enum(['user', 'admin', 'moderator']).default('user')
});

const updateUserSchema = createUserSchema.partial();

function validate(schema) {
  return (req, res, next) => {
    const result = schema.safeParse(req.body);
    if (!result.success) {
      return res.status(400).json(
        ApiResponse.validationError(result.error.issues)
      );
    }
    req.validatedData = result.data;
    next();
  };
}

// Usage
app.post('/users', validate(createUserSchema), userController.create);
app.patch('/users/:id', validate(updateUserSchema), userController.update);

The schema documents your API contract. New developers can read it and immediately understand what the endpoint expects. Plus, Zod's error messages are actually readable.

5. Pagination: Don't Return Everything

This one seems obvious, but I've seen production APIs returning thousands of records because "the client can handle it." They can't, and they shouldn't have to.

// utils/pagination.js
async function paginate(query, { page = 1, limit = 20 }) {
  const skip = (page - 1) * limit;

  const [data, total] = await Promise.all([
    query.skip(skip).limit(limit),
    query.clone().count()
  ]);

  return {
    data,
    pagination: {
      page,
      limit,
      total,
      totalPages: Math.ceil(total / limit),
      hasMore: page * limit < total
    }
  };
}

// Usage in route
app.get('/posts', async (req, res) => {
  const { page, limit } = req.query;
  const result = await paginate(
    db.posts.findMany({ where: { published: true } }),
    { page: parseInt(page) || 1, limit: parseInt(limit) || 20 }
  );
  res.json(ApiResponse.success(result.data, result.pagination));
});

Always include pagination metadata: total records, total pages, and whether more data exists. Your frontend will thank you.

The Bigger Picture

These patterns aren't about being overly architectural or adding unnecessary complexity. They're about creating predictable, maintainable systems that developers actually enjoy working with.

Start with what hurts most in your current project. Is it inconsistent errors? Start there. Is it hard-to-test routes? Introduce the service layer. Is it validation chaos? Add Zod schemas.

You don't need to refactor everything at once. Small, consistent improvements compound into systems you're proud of.

What patterns have made your API development easier? I'd love to hear what's working for you.

Docker Networking Explained: From Zero to Hero with Real Examples

Teguh Coding — Sat, 07 Mar 2026 18:05:21 +0000

The Moment Everything Clicked

I still remember the confusion on my face when my container couldn't reach another container. "They're on the same machine! They're both Docker! Why can't they talk?"

That was three years ago. Since then, I've helped dozens of teams debug networking issues that should have taken minutes but instead took hours. The problem? Most tutorials jump straight into bridge networks without explaining the mental model.

Let me save you the headache.

Understanding Docker's Network Model

Docker creates isolated network namespaces for containers. This means each container has its own network stack, IP address, and ports. By default, Docker provides several network drivers.

The Four Network Types You Need to Know

bridge - The default network. Containers can communicate with each other and the host.
host - Removes network isolation between container and host.
overlay - Connects containers across multiple Docker hosts.
none - Completely disables networking.

For most local development, you'll live in the bridge world. Let's explore that.

The Default Bridge: What You Need to Understand

When you run a container without specifying a network, Docker places it on the default bridge network. Here's the catch: containers on the default bridge can only communicate via IP addresses, not container names.

# This will FAIL - DNS resolution doesn't work on default bridge
docker run --name database postgres:15
docker run --name api myapi:latest
# From api container: ping database won't work!

This is why named networks exist.

Creating Your Own Bridge Network

Here's the fix - create a custom bridge network and DNS resolution just works:

# Create a custom bridge network
docker network create my-network

# Run containers on this network
docker run -d --name database --network my-network postgres:15
docker run -d --name redis --network my-network redis:alpine
docker run -d --name api --network my-network -p 3000:3000 myapi:latest

Now from the api container, you can reach services by name:

# These work!
docker exec api ping database
docker exec api ping redis

The docker-compose.yml Approach

In production-like setups, you'll use Docker Compose. Here's how networking works there:

version: '3.8'

services:
  api:
    build: .
    ports:
      - "3000:3000"
    depends_on:
      - database
      - redis
    networks:
      - app-network

  database:
    image: postgres:15
    volumes:
      - pgdata:/var/lib/postgresql/data
    networks:
      - app-network

  redis:
    image: redis:alpine
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

Key insight: Docker Compose automatically creates a network and connects all services to it. Services can reach each other by their service names.

Connecting Containers Across Compose Files

Sometimes you have multiple compose files that need to communicate. Here's how:

# In docker-compose.yml for frontend
services:
  frontend:
    build: ./frontend
    networks:
      - frontend-network
      - backend-network

networks:
  frontend-network:
    external: true
  backend-network:
    driver: bridge

Create the external network first:

docker network create frontend-network
docker-compose up -d

Port Mapping: The Host vs Container Confusion

One common point of confusion: -p 3000:3000. What does that mean?

-p HOST_PORT:CONTAINER_PORT

Container port (right side): The port inside the container listening for connections
Host port (left side): The port on your host machine that forwards to the container

# Container listens on 5432 (PostgreSQL default)
# Host machine exposes it on 5433
ports:
  - "5433:5432"

Debugging Container Networking

When things break, here are your debugging tools:

Check which networks a container is on

docker inspect container_name --format='{{json .NetworkSettings.Networks}}'

List all networks

docker network ls

Inspect a network

docker network inspect bridge

Test connectivity between containers

docker exec -it container_a ping container_b

Check DNS resolution

docker exec -it container_a nslookup container_b

A Real-World Scenario

Let's put it all together. Imagine you have a Node.js API that connects to PostgreSQL and Redis, with a frontend that talks to the API.

version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: user
      POSTGRES_PASSWORD: secret
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d myapp"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]

  api:
    build: .
    environment:
      DATABASE_URL: postgresql://user:secret@postgres:5432/myapp
      REDIS_URL: redis://redis:6379
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    ports:
      - "3000:3000"

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - api

volumes:
  postgres_data:

Notice how:

Services communicate using their names (postgres, redis, api)
depends_on with condition: service_healthy ensures proper startup order
Nginx reverse-proxies to the API

Quick Reference Cheat Sheet

# Create a network
docker network create my-network

# Run container on specific network
docker run --network my-network nginx

# Connect running container to network
docker network connect my-network container-name

# Disconnect from network
docker network disconnect my-network container-name

# Remove unused networks
docker network prune

The Bottom Line

Docker networking doesn't have to be mysterious. Here's the mental model:

Custom bridge networks - Use these for most local development. They provide DNS resolution between containers.
Service names as hostnames - In Docker Compose, the service name IS the hostname.
Port mapping - Only needed when you want to expose services to the host.
Debug with inspect - When in doubt, docker network inspect reveals everything.

Next time your containers can't talk to each other, you'll know exactly where to look.

What Docker networking challenges are you facing? Drop a comment below!

Stop Writing Bad Dockerfiles: Production-Ready Best Practices That Actually Work

Teguh Coding — Sat, 07 Mar 2026 06:07:33 +0000

Most Dockerfiles are a disaster waiting to happen.

I inherited a project last year with a Dockerfile that took 12 minutes to build. Twelve. Minutes. For a simple Node.js API. The final image was 1.8GB. There were five different :latest tags scattered throughout. And it ran as root.

That project taught me everything about what NOT to do. Here are the Dockerfile best practices that will save you from those mistakes.

The Problem with Typical Dockerfiles

Most developers write Dockerfiles like this:

FROM node:latest
COPY . .
RUN npm install
CMD ["node", "index.js"]

This looks fine until you realize it:

Rebuilds everything on every code change
Includes your node_modules in the image
Uses an unpredictable Node version
Has no error handling
Runs as root

Let's fix this.

1. Always Pin Specific Versions

Never use :latest. When you build next month, you might get a completely different base image with breaking changes.

# Bad
FROM node:latest

# Good - specific version
FROM node:20.11.0-alpine3.19

The alpine variant is smaller (about 5MB vs 900MB+). For production, that's a big deal.

2. Use .dockerignore (Seriously)

You'd be amazed what's in your image that shouldn't be.

# .dockerignore
node_modules
npm-debug.log
.git
.gitignore
README.md
.env
.env.*
*.md
dist
coverage
.vscode
.idea
docker-compose*.yml
Dockerfile

That .env file with your production secrets? If you COPY . . without .dockerignore, it's in your image. I've seen this cause real security breaches.

3. Order Matters for Layer Caching

Docker builds layers. Each instruction creates a new layer. Docker caches unchanged layers, which makes rebuilds fast. Structure your Dockerfile so frequently changing steps come last:

# Better ordering - dependencies change less often
FROM node:20.11.0-alpine3.19

WORKDIR /app

# Copy package files FIRST
COPY package*.json ./

# Install dependencies (cached unless package.json changes)
RUN npm ci --only=production

# Copy source code LAST (changes every build)
COPY . .

# Expose and run
EXPOSE 3000
CMD ["node", "index.js"]

This way, changing index.js doesn't trigger a new npm install.

4. Use Multi-Stage Builds for Smaller Images

Your dev dependencies don't belong in production.

# Build stage
FROM node:20.11.0-alpine3.19 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Production stage
FROM node:20.11.0-alpine3.19 AS production
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package*.json ./

USER node
EXPOSE 3000
CMD ["node", "dist/index.js"]

This produces a lean production image without TypeScript, test frameworks, or build tools.

5. Never Run as Root

This is a security must. Running as root means if an attacker compromises your container, they have root on the host.

# Create a non-root user
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001

# Change ownership of files
CHOWN nodejs:nodejs /app

# Switch to non-root user
USER nodejs

Then in your Compose file:

services:
  app:
    user: "1001:1001"

6. Use HEALTHCHECK

Your orchestrator needs to know if your container is actually healthy.

FROM node:20.11.0-alpine3.19

WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .

EXPOSE 3000

# Health check - curl is lightweight enough for alpine
RUN apk add --no-cache curl
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD curl -f http://localhost:3000/health || exit 1

CMD ["node", "index.js"]

Now Kubernetes or Docker Compose knows when your app is actually ready to serve traffic.

7. Understand the Difference Between RUN, CMD, and ENTRYPOINT

This confuses everyone:

RUN: Executes during build (creates layer)
CMD: Default command when container starts (can be overridden)
ENTRYPOINT: Defines the actual executable (arguments are appended)

# CMD - can be overridden at runtime
CMD ["node", "index.js"]
# docker run myapp custom.js runs custom.js

# ENTRYPOINT - treats arguments as parameters
ENTRYPOINT ["node"]
CMD ["index.js"]
# docker run myapp debug.js runs node debug.js

For most Node.js apps, CMD is what you want.

8. Handle Signals Properly

Docker sends SIGTERM first, then SIGKILL after 10 seconds. Your app needs to handle graceful shutdown.

// In your Node.js app
const server = http.createServer(app);

const shutdown = () => {
  console.log('Received shutdown signal, closing server...');
  server.close(() => {
    console.log('Server closed');
    process.exit(0);
  });

  // Force exit after timeout
  setTimeout(() => {
    console.error('Forced shutdown');
    process.exit(1);
  }, 10000);
};

process.on('SIGTERM', shutdown);
process.on('SIGINT', shutdown);

Putting It All Together

Here's a production-ready Dockerfile:

# Build stage
FROM node:20.11.0-alpine3.19 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

# Production stage
FROM node:20.11.0-alpine3.19 AS production
WORKDIR /app

# Security: create non-root user
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nodejs -u 1001

# Copy built artifacts
COPY --from=builder --chown=nodejs:nodejs /app/dist ./dist
COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --from=builder --chown=nodejs:nodejs /app/package.json ./

# Switch to non-root user
USER nodejs

EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))"

CMD ["node", "dist/index.js"]

The Bottom Line

A good Dockerfile isn't about using all the tricks. It's about:

Security: Non-root user, no secrets in image
Speed: Proper layer caching, multi-stage builds
Reliability: Health checks, graceful shutdown
Maintainability: Specific versions, clear structure

Start with these practices. Your builds will be faster, your images smaller, and your production incidents fewer.

What Dockerfile nightmares have you encountered? Drop them in the comments.

Docker Compose for Local Development: The Setup That Makes Your Team Actually Enjoy Onboarding

Teguh Coding — Thu, 05 Mar 2026 06:05:33 +0000

There is a ritual every developer knows too well.

A new engineer joins the team. They clone the repo. They follow the README — a document last updated eighteen months ago. Two hours later, they are still fighting with port conflicts, missing environment variables, and a PostgreSQL version that refuses to cooperate with their machine.

Docker Compose exists to kill that ritual. Not just for running containers, but for building a local development environment so smooth that onboarding becomes a non-event.

This article is about doing it right.

Why Most Docker Compose Setups Fall Short

Most teams adopt Docker Compose and immediately replicate their production docker run commands inside a YAML file. That works, technically. But it misses everything that makes local development actually pleasant:

Hot reloading when you change code
Shared environment variables without copying .env files everywhere
Services that start in the right order
Logs that don't require a PhD to read
A database with seed data already loaded

Let's build a setup that handles all of this.

The Project Structure

We'll use a Node.js API + PostgreSQL + Redis stack as the example. The same patterns apply to Python, Go, or any backend language.

my-app/
  docker-compose.yml
  docker-compose.override.yml
  .env
  .env.example
  apps/
    api/
      Dockerfile
      Dockerfile.dev
      src/
  db/
    init/
      01_schema.sql
      02_seed.sql

The key insight here: two Compose files. One for the baseline config, one for local overrides. This is Docker Compose's built-in feature that most teams never use.

The Base Compose File

# docker-compose.yml
version: '3.9'

services:
  api:
    build:
      context: ./apps/api
      dockerfile: Dockerfile
    environment:
      NODE_ENV: production
      DATABASE_URL: postgresql://app:secret@db:5432/appdb
      REDIS_URL: redis://cache:6379
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_started
    ports:
      - "3000:3000"

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: appdb
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./db/init:/docker-entrypoint-initdb.d
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d appdb"]
      interval: 5s
      timeout: 5s
      retries: 5

  cache:
    image: redis:7-alpine
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

A few things worth noting:

The healthcheck on postgres is not optional. Without it, your API container starts, tries to connect to the database, and fails because Postgres is still initializing. depends_on with condition: service_healthy solves this elegantly.

The ./db/init volume mount auto-runs SQL files in alphabetical order when the database is first created. Your new engineer gets a database with real schema and seed data on their first docker compose up.

The Override File for Local Dev

This is where the magic happens.

# docker-compose.override.yml
version: '3.9'

services:
  api:
    build:
      dockerfile: Dockerfile.dev
    environment:
      NODE_ENV: development
    volumes:
      - ./apps/api/src:/app/src
    command: npm run dev
    ports:
      - "9229:9229"  # Node.js debugger port

  db:
    ports:
      - "5432:5432"  # Expose locally for DB clients like TablePlus

  cache:
    ports:
      - "6379:6379"  # Expose locally for Redis clients

Docker Compose automatically merges docker-compose.override.yml with docker-compose.yml when you run docker compose up. No flags needed.

What this override does:

Uses a dev-specific Dockerfile (with nodemon or tsx watch installed)
Mounts your source code directly into the container so changes reflect instantly
Exposes database and cache ports locally so developers can connect with their GUI tools
Opens the Node.js debug port for stepping through code in VS Code

The Dev Dockerfile

# Dockerfile.dev
FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install  # Full install, including devDependencies

# Source is mounted via volume, not copied
CMD ["npm", "run", "dev"]

Notice: no COPY src . here. The source code comes in through the volume mount. This means every file save on your host machine immediately reflects inside the container, triggering your dev server's hot reload.

Environment Variable Strategy

Commit an .env.example file with all required variables but no real values:

# .env.example
DATABASE_URL=
REDIS_URL=
JWT_SECRET=
API_PORT=3000

Commit a .env file with safe local defaults (not secrets):

# .env  (safe to commit for local dev defaults)
DATABASE_URL=postgresql://app:secret@db:5432/appdb
REDIS_URL=redis://cache:6379
JWT_SECRET=local-dev-secret-not-for-production
API_PORT=3000

In your Compose file, reference it:

services:
  api:
    env_file:
      - .env

For production, you never commit real secrets. But for local development, having working defaults means a new engineer types docker compose up and everything just works.

The Makefile: Hiding the Complexity

Docker commands get verbose. A simple Makefile keeps things friendly:

.PHONY: up down logs shell db-reset

up:
    docker compose up --build -d

ddown:
    docker compose down

logs:
    docker compose logs -f api

shell:
    docker compose exec api sh

db-reset:
    docker compose down -v
    docker compose up -d db
    docker compose exec db psql -U app -d appdb -f /docker-entrypoint-initdb.d/01_schema.sql

test:
    docker compose exec api npm test

Now onboarding looks like:

git clone https://github.com/your-org/my-app
cd my-app
make up

Three commands. Done.

Handling the Logs Problem

Running docker compose logs -f across five services is a wall of noise. Two approaches:

Option 1: Filter by service

docker compose logs -f api

Option 2: Use structured logging in your app and pipe to jq

docker compose logs -f api | jq '.'

If you are running many services, consider adding Dozzle to your Compose stack — a lightweight log viewer that runs as a container and gives you a browser UI for all service logs:

  dozzle:
    image: amir20/dozzle:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - "8888:8080"

Visit http://localhost:8888 and you get a clean, searchable log UI for every container.

One More Thing: Profiles

Docker Compose supports profiles — a way to define services that only start when explicitly requested.

  mailhog:
    image: mailhog/mailhog
    ports:
      - "1025:1025"  # SMTP
      - "8025:8025"  # Web UI
    profiles:
      - mail

  pgadmin:
    image: dpage/pgadmin4
    environment:
      PGADMIN_DEFAULT_EMAIL: admin@local.dev
      PGADMIN_DEFAULT_PASSWORD: admin
    ports:
      - "5050:80"
    profiles:
      - admin

Now developers only start these when they need them:

docker compose --profile mail up -d    # Start with MailHog
docker compose --profile admin up -d   # Start with pgAdmin

The core stack stays lean. Heavy optional services are available but out of the way.

What Good Onboarding Feels Like

When this setup is in place, your README shrinks to:

Install Docker Desktop
Clone the repo
Run make up
Visit http://localhost:3000

No version conflicts. No "works on my machine." No two-hour debugging sessions before writing a single line of code.

That's the real value of Docker Compose done right. It's not about containerization. It's about respect for your teammates' time.

Quick Reference

Command	What it does
`docker compose up -d`	Start all services in background
`docker compose up --build -d`	Rebuild images then start
`docker compose down`	Stop and remove containers
`docker compose down -v`	Also remove volumes (fresh database)
`docker compose logs -f api`	Follow logs for one service
`docker compose exec api sh`	Shell into running container
`docker compose ps`	Check container status

If your team is still doing manual setup, this is the weekend project that pays back within the first week. Build it once, and every future engineer thanks you without knowing your name.

That's a pretty good legacy to leave in a YAML file.

Docker Compose for Local Development: The Setup That Makes Your Team Hate Excuses

Teguh Coding — Wed, 04 Mar 2026 18:06:36 +0000

You have been there. A new developer joins the team, and within the first hour they are already stuck. "It works on my machine" is being typed in Slack. Node version mismatch. PostgreSQL not running. Redis connection refused. The classic onboarding nightmare that wastes hours every single week.

Docker Compose is the cure. Not just for deployment — for local development. When set up right, it collapses that chaos into a single command: docker compose up. This article walks through building a local development environment with Docker Compose that actually feels good to work in, not like you are fighting the tool.

Why Most Docker Compose Setups Fall Short

The typical beginner Compose file does the basics: spins up a database, maybe a Redis instance, and the app. But then frustration sets in:

Code changes require rebuilding the image
Logs from multiple services are a mess
Environment variables are hardcoded everywhere
There is no separation between dev and production config

Let us fix all of that.

The Project Structure

For a Node.js backend with PostgreSQL and Redis, here is a clean starting layout:

my-project/
  app/
    src/
    package.json
    Dockerfile
  docker-compose.yml
  docker-compose.override.yml
  .env
  .env.example

The key insight: docker-compose.yml is your base config. docker-compose.override.yml is the dev-only layer that Docker Compose automatically merges when you run docker compose up. You never have to pass -f flags manually.

The Base Compose File

# docker-compose.yml
version: "3.9"

services:
  app:
    build:
      context: ./app
      target: base
    env_file: .env
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - backend

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_NAME}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]
      interval: 5s
      timeout: 5s
      retries: 5
    networks:
      - backend

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5
    networks:
      - backend

volumes:
  postgres_data:

networks:
  backend:
    driver: bridge

A few things worth noting here. The depends_on with condition: service_healthy is a game changer. Your app will not start until the database is actually ready to accept connections — not just started. No more race conditions on first docker compose up.

The Dev Override

# docker-compose.override.yml
version: "3.9"

services:
  app:
    build:
      target: development
    volumes:
      - ./app:/usr/src/app
      - /usr/src/app/node_modules
    ports:
      - "3000:3000"
      - "9229:9229"
    command: npm run dev
    environment:
      NODE_ENV: development

  db:
    ports:
      - "5432:5432"

  redis:
    ports:
      - "6379:6379"

This override does several important things:

Volume mounting for hot reload: ./app:/usr/src/app mounts your local source into the container. Changes you make in your editor instantly appear inside the container without rebuilding.

The node_modules trick: The line /usr/src/app/node_modules creates an anonymous volume that prevents your local node_modules from overwriting the container's installed packages. This avoids the native binary nightmare when your machine is Mac and the container is Linux.

Exposed ports for local tools: Exposing 5432 and 6379 means you can connect your local database GUI or Redis client directly. Useful for debugging without docker exec.

Debug port: Port 9229 is the Node.js inspector port. With this exposed, you can attach VS Code debugger directly to the running container.

The Dockerfile That Supports Both Worlds

# app/Dockerfile
FROM node:20-alpine AS base
WORKDIR /usr/src/app
COPY package*.json ./
RUN npm ci --only=production
COPY . .

FROM base AS development
RUN npm ci
CMD ["npm", "run", "dev"]

FROM base AS production
CMD ["node", "src/index.js"]

The multi-stage Dockerfile lets Compose target different stages. In the override, target: development pulls the stage with dev dependencies. In production, you target production and get a lean image without nodemon or other dev-only tools.

Environment Variables Done Right

Never hardcode secrets. Never commit them. Here is a minimal .env.example to commit:

# .env.example
DB_USER=appuser
DB_PASSWORD=changeme
DB_NAME=myapp
DB_HOST=db
DB_PORT=5432
REDIS_URL=redis://redis:6379
PORT=3000
NODE_ENV=development

Each developer copies this to .env and fills in their values. The .env file is gitignored. Simple, explicit, no magic.

One critical detail: inside Compose, services talk to each other by service name, not localhost. So DB_HOST=db and REDIS_URL=redis://redis:6379 use the service names defined in the Compose file. This trips up almost everyone the first time.

Useful Compose Commands for Daily Work

Once your setup is in place, here is the workflow that becomes muscle memory:

# Start everything (with rebuild if Dockerfile changed)
docker compose up --build

# Start in background, follow specific service logs
docker compose up -d
docker compose logs -f app

# Restart just one service (after code change when not using hot reload)
docker compose restart app

# Run a one-off command inside a service
docker compose exec app sh
docker compose exec db psql -U appuser -d myapp

# Run database migrations
docker compose exec app npm run migrate

# Nuke everything and start fresh
docker compose down -v
docker compose up --build

The exec command is your best friend for debugging. Need to check what is in Redis? docker compose exec redis redis-cli. Need a Postgres shell? One line and you are in.

Making It Fast: Layer Caching That Actually Works

The biggest pain with Docker in development is slow rebuilds. Here is what makes caching actually hold:

# Copy package files FIRST, install, THEN copy source
COPY package*.json ./
RUN npm ci
COPY . .

If your source changes but package.json did not, Docker reuses the cached layer with all your installed packages. This makes rebuilds go from 2 minutes to 10 seconds.

With volume mounts in dev mode, you rarely need to rebuild at all. The only times you do: changing the Dockerfile, adding new npm packages, or modifying environment variables.

Adding a Seed Script

Getting a fresh database with test data should be zero-friction:

# Add to docker-compose.override.yml
services:
  db-seed:
    build:
      context: ./app
      target: development
    command: npm run db:seed
    env_file: .env
    depends_on:
      db:
        condition: service_healthy
    networks:
      - backend
    profiles:
      - tools

The profiles: [tools] key means this service does not start by default. To seed the database:

docker compose --profile tools run --rm db-seed

Clean, on-demand, no side effects on the normal up flow.

The Payoff

When a new developer joins your team, the onboarding is:

Clone the repo
Copy .env.example to .env
Run docker compose up

That is it. No "install PostgreSQL 15 specifically, not 16". No "make sure your Redis is version 7". No mystery errors because someone has Node 18 and the project needs Node 20.

Everybody runs the same stack. Bugs are reproducible. Onboarding takes minutes, not days. "It works on my machine" disappears from your Slack permanently.

Docker Compose for local development is not about being fancy — it is about respecting your team's time. Build it once, document it well, and stop solving the same environment problems forever.

Docker Security Hardening: 10 Practices That Will Protect Your Containers in Production

Teguh Coding — Wed, 04 Mar 2026 06:06:50 +0000

It started with a Slack message from our CTO at 2 AM.

"We have a breach. Someone got into our container host."

That was two years ago. Our team had been running Docker in production for over a year, and like many teams, we had focused entirely on getting things working — not on keeping things secure. We assumed Docker was "safe by default." We were wrong.

After spending weeks doing a post-mortem and rebuilding our infrastructure with security as a first-class concern, I learned more about container security in one month than I had in the previous year. This article is the guide I wish I had before that 2 AM message.

Why Container Security Is Different

Containers share the host kernel. That single fact changes everything. A misconfigured container is not an isolated problem — it is a potential foothold into your entire host system. Understanding this is the mental shift that makes everything else click.

Let us walk through 10 concrete practices, from the easiest wins to the more advanced configurations.

1. Never Run Containers as Root

This is the number one mistake I see in production Docker setups. By default, processes inside a container run as root (UID 0). If an attacker exploits your application, they get root inside the container — and depending on your configuration, that can mean root on the host.

Fix it in your Dockerfile:

FROM node:20-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .

# Create a non-root user and switch to it
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser

EXPOSE 3000
CMD ["node", "server.js"]

Or enforce it at runtime:

docker run --user 1000:1000 my-app

2. Use Read-Only Filesystems

If your application does not need to write to the filesystem (most web services do not), make the container filesystem read-only. This stops a whole class of attacks where the attacker tries to write malicious scripts or modify configuration files.

docker run --read-only \
  --tmpfs /tmp \
  --tmpfs /var/run \
  my-app

Or in Docker Compose:

services:
  api:
    image: my-app
    read_only: true
    tmpfs:
      - /tmp
      - /var/run

The --tmpfs flag gives the container writable in-memory space for things like temp files and PID files, without touching the real filesystem.

3. Drop Unnecessary Linux Capabilities

Docker gives containers a default set of Linux capabilities — powers like NET_RAW (can craft raw packets), SYS_CHROOT (can change root directory), and others that most applications simply do not need.

Drop all capabilities and add back only what you need:

docker run \
  --cap-drop ALL \
  --cap-add NET_BIND_SERVICE \
  my-app

In Docker Compose:

services:
  api:
    image: my-app
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE

For most web APIs, you need zero extra capabilities beyond the defaults — and you should drop the defaults too.

4. Scan Your Images for Vulnerabilities

Your application code is only part of the equation. The base image you build on top of could contain hundreds of known vulnerabilities. Scanning tools make this visible.

# Using Docker Scout (built into Docker Desktop and CLI)
docker scout cves my-app:latest

# Using Trivy (open source, excellent CI integration)
trivy image my-app:latest

# Using Grype
grype my-app:latest

Integrate this into your CI pipeline so vulnerabilities are caught before images reach production:

# .github/workflows/security.yml
- name: Scan image for vulnerabilities
  run: |
    trivy image \
      --exit-code 1 \
      --severity HIGH,CRITICAL \
      my-app:${{ github.sha }}

5. Use Minimal Base Images

Fewer packages means a smaller attack surface. Alpine Linux images are around 5MB and contain almost nothing. Distroless images from Google contain only your application and its runtime — no shell, no package manager, nothing extra.

# Before: 1.1GB attack surface
FROM node:20

# Better: ~150MB
FROM node:20-alpine

# Best for production: ~120MB, no shell at all
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .

FROM gcr.io/distroless/nodejs20-debian12
WORKDIR /app
COPY --from=builder /app .
EXPOSE 3000
CMD ["server.js"]

An attacker who gets into a distroless container has no bash, no curl, no wget — their options are severely limited.

6. Never Put Secrets in Images

This one should be obvious, but I still find secrets baked into Docker images in the wild. Environment variables, build args, and COPY instructions can all end up in image layers — and image layers are permanent.

Bad:

# This secret is now in your image forever
ARG DATABASE_URL=postgres://user:password@host/db
ENV DATABASE_URL=$DATABASE_URL

Better — inject secrets at runtime:

docker run -e DATABASE_URL="$DATABASE_URL" my-app

Best — use Docker secrets for Swarm, or mount secret files:

# Docker secret (Swarm)
docker secret create db_password ./password.txt

# Mount as a file at runtime
docker run \
  --mount type=secret,id=db_password \
  my-app

Always add your .env files to .dockerignore:

.env
.env.local
.env.production
*.pem
*.key
secrets/

7. Limit Container Resources

Without resource limits, a single compromised or runaway container can eat all CPU and memory on the host, taking down every other service. This is both a reliability issue and a security issue (denial of service).

docker run \
  --memory 512m \
  --memory-swap 512m \
  --cpus 0.5 \
  --pids-limit 100 \
  my-app

In Docker Compose:

services:
  api:
    image: my-app
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 512M

--pids-limit is particularly underrated — it prevents fork bombs and process-based denial-of-service attacks.

8. Enable Security Profiles (seccomp and AppArmor)

Docker applies a default seccomp profile that blocks about 44 dangerous syscalls. You can go further with a custom profile.

# Apply default seccomp profile explicitly
docker run --security-opt seccomp=default my-app

# Apply a custom restrictive profile
docker run --security-opt seccomp=./my-seccomp-profile.json my-app

# Enable AppArmor profile
docker run --security-opt apparmor=docker-default my-app

# Prevent privilege escalation inside the container
docker run --security-opt no-new-privileges my-app

The no-new-privileges flag is an easy win — it prevents processes inside the container from gaining more privileges than they started with, even if they call setuid binaries.

9. Isolate Containers with Networks

By default, all containers on a host can talk to each other on the default bridge network. Use custom networks to enforce isolation — only containers that need to communicate should be on the same network.

services:
  api:
    image: my-api
    networks:
      - frontend
      - backend

  postgres:
    image: postgres:16
    networks:
      - backend  # Only accessible from api, not from internet-facing services

  nginx:
    image: nginx
    networks:
      - frontend  # Only talks to api, not to the database
    ports:
      - "80:80"

networks:
  frontend:
    driver: bridge
  backend:
    driver: bridge
    internal: true  # No external access

The internal: true flag on the backend network means containers on that network cannot reach the internet — even if compromised, they cannot exfiltrate data outbound.

10. Audit Your Running Containers Regularly

Security is not a one-time configuration — it is an ongoing practice. Build auditing into your workflow.

# List containers running as root
docker ps -q | xargs docker inspect \
  --format '{{.Name}}: User={{.Config.User}}' | grep 'User=$'

# Check for containers with dangerous capabilities
docker ps -q | xargs docker inspect \
  --format '{{.Name}}: CapAdd={{.HostConfig.CapAdd}}'

# Find images with no vulnerability scan record
docker images --format '{{.Repository}}:{{.Tag}}' | \
  xargs -I{} sh -c 'echo "Scanning {}..."; trivy image --quiet {}'

# Use Docker Bench for Security (automated CIS benchmark)
docker run --rm \
  --net host --pid host --userns host --cap-add audit_control \
  -v /var/lib:/var/lib \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /etc:/etc:ro \
  docker/docker-bench-security

Docker Bench for Security is a script that checks for dozens of common configuration issues against the CIS Docker Benchmark. Run it when you first set up a new host and then periodically thereafter.

Putting It All Together

Here is a production-ready Docker Compose snippet that incorporates all of these practices:

services:
  api:
    image: my-api:${VERSION}
    user: "1000:1000"
    read_only: true
    tmpfs:
      - /tmp
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges
      - seccomp=./seccomp-profile.json
    networks:
      - backend
    environment:
      - NODE_ENV=production
    secrets:
      - db_password
    deploy:
      resources:
        limits:
          cpus: '0.50'
          memory: 256M
          pids: 100

networks:
  backend:
    internal: true

secrets:
  db_password:
    external: true

The Mindset Shift

The 2 AM breach taught me that container security is not about any single setting — it is about defense in depth. Each of these practices limits what an attacker can do if they get past one layer of defense.

None of them are complicated. Most can be added to existing setups in an afternoon. But they compound: a container running as a non-root user with a read-only filesystem, dropped capabilities, resource limits, and no-new-privileges is an incredibly hostile environment for an attacker.

Do not wait for your own 2 AM message. Start with the first three practices this week — non-root user, read-only filesystem, and drop capabilities — and work your way down the list.

Your future self will thank you.

Have questions or want to share your own container security setup? Drop a comment below. I read every one.

Docker Volumes Explained: Stop Losing Data Every Time You Restart a Container

Teguh Coding — Tue, 03 Mar 2026 18:05:46 +0000

You spent two hours setting up your PostgreSQL container, seeded it with test data, ran your app against it — everything works perfectly. Then you restart the container. Gone. All of it. The database is empty again.

If you have been there, you already know the pain. If you have not, consider this your warning. Docker containers are ephemeral by design, and that is a feature — until you forget about it and lose your data.

This article is a practical guide to Docker volumes: what they are, how they work, when to use each type, and the patterns that will save you from the "where did my data go" panic at 2 AM.

Why Containers Lose Data

Every Docker container gets its own writable layer on top of its image. When you write files inside a running container, they go into this layer. The problem: when the container is removed (not just stopped, but removed), that writable layer is deleted with it.

This is intentional. Containers are supposed to be disposable. You should be able to spin up ten copies of your app container and throw them away without ceremony. But your database is not supposed to be disposable.

This is exactly the problem that volumes solve.

The Three Ways to Persist Data

Docker gives you three mechanisms for data persistence:

Volumes — managed by Docker, stored in Docker's own storage area
Bind mounts — map a host directory directly into the container
tmpfs mounts — stored in memory, gone when the container stops (useful for sensitive data)

Let's look at each one.

Docker Volumes: The Recommended Approach

Volumes are managed entirely by Docker. You create them, Docker handles where they live on the host (usually /var/lib/docker/volumes/ on Linux). You do not need to worry about host paths.

Creating and using a volume

# Create a named volume
docker volume create myapp-data

# Run a container with that volume
docker run -d \
  --name postgres \
  -e POSTGRES_PASSWORD=secret \
  -v myapp-data:/var/lib/postgresql/data \
  postgres:16

Now your PostgreSQL data survives container restarts and even container removal. The volume persists until you explicitly delete it.

Inspect and manage volumes

# List all volumes
docker volume ls

# Inspect a volume (shows the actual host path)
docker volume inspect myapp-data

# Remove a volume (careful -- this deletes the data)
docker volume rm myapp-data

# Remove all unused volumes
docker volume prune

Why volumes beat bind mounts for production

Volumes work the same on any OS — no path differences between Linux, macOS, and Windows
Docker can manage backups and migrations of volumes
Volumes can be shared between containers more safely
Named volumes are easy to identify and reason about

Bind Mounts: Direct Host Access

Bind mounts map a specific directory from your host machine into the container. They are perfect for development.

docker run -d \
  --name myapp \
  -v /home/teguh/myapp:/app \
  node:20 node /app/server.js

Anything you change in /home/teguh/myapp on your host is instantly reflected inside the container at /app. This is why bind mounts are the go-to for local development — you edit code in your editor, and the running container sees the changes immediately.

The development workflow

# docker-compose.yml for local development
services:
  app:
    build: .
    ports:
      - "3000:3000"
    volumes:
      # Bind mount for live code changes
      - ./src:/app/src
      # Named volume for node_modules (prevents host/container conflicts)
      - node_modules:/app/node_modules
    command: npm run dev

  postgres:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: myapp
    volumes:
      # Named volume for database persistence
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:
  node_modules:

Notice the node_modules trick. If you bind-mount your entire project directory, the container's node_modules (compiled for Linux) gets overwritten by your host's node_modules (compiled for macOS or Windows). Using a named volume for node_modules keeps them separate and avoids the infamous "wrong platform" binary errors.

Sharing Volumes Between Containers

Multiple containers can read from and write to the same volume. This is useful for sidecar patterns — like a log aggregator that reads files written by your application container.

# Container 1: writes logs
docker run -d \
  --name app \
  -v shared-logs:/var/log/app \
  myapp:latest

# Container 2: reads and ships those logs
docker run -d \
  --name log-shipper \
  -v shared-logs:/var/log/app:ro \
  fluent-bit:latest

The :ro flag makes the mount read-only in the second container — a good security practice when a container only needs to read, not write.

Volume Backup and Restore

This is the part people forget until disaster strikes. Always have a backup strategy.

Backup a volume

# Create a backup of the postgres_data volume
docker run --rm \
  -v postgres_data:/source:ro \
  -v $(pwd)/backups:/backup \
  alpine \
  tar czf /backup/postgres_$(date +%Y%m%d_%H%M%S).tar.gz -C /source .

This spins up a minimal Alpine container, mounts your volume as read-only, and tars up the contents into a backups/ folder on your host.

Restore from backup

# Create a fresh volume
docker volume create postgres_data_restored

# Extract your backup into it
docker run --rm \
  -v postgres_data_restored:/target \
  -v $(pwd)/backups:/backup \
  alpine \
  tar xzf /backup/postgres_20260303_180000.tar.gz -C /target

Common Mistakes and How to Avoid Them

Mistake 1: Anonymous volumes

# Bad: Docker generates a random ID as the volume name
docker run -v /var/lib/postgresql/data postgres:16

# Good: Always use named volumes
docker run -v postgres_data:/var/lib/postgresql/data postgres:16

Anonymous volumes accumulate silently. You will end up with dozens of docker volume ls entries that look like a3f2b8c1d4e... and have no idea what they contain.

Mistake 2: Forgetting volumes exist when rebuilding

When you run docker-compose down, volumes are preserved by default. This is usually what you want. But when you want a completely clean slate:

# Remove containers AND volumes
docker-compose down -v

# Or remove specific volumes
docker volume rm myproject_postgres_data

Mistake 3: Wrong permissions

If your container runs as a non-root user (it should), the volume mount might have permission issues.

FROM node:20-alpine

# Create a non-root user
RUN addgroup -S appgroup && adduser -S appuser -G appgroup

# Create and own the data directory
RUN mkdir -p /app/data && chown appuser:appgroup /app/data

USER appuser

Putting It All Together

Here is a production-ready Docker Compose setup combining everything:

services:
  app:
    build:
      context: .
      target: production
    ports:
      - "3000:3000"
    volumes:
      - uploads:/app/uploads
    depends_on:
      - postgres
      - redis
    environment:
      DATABASE_URL: postgresql://user:secret@postgres:5432/myapp
      REDIS_URL: redis://redis:6379

  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: myapp
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./scripts/init.sql:/docker-entrypoint-initdb.d/init.sql:ro

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    volumes:
      - redis_data:/data
    command: redis-server --appendonly yes

volumes:
  postgres_data:
  redis_data:
  uploads:

Notice: every stateful service (postgres, redis, file uploads) has a named volume. The init SQL script uses a bind mount with :ro because it is static config, not data.

The Mental Model

Think of it this way:

Named volumes for any data that needs to survive: databases, user uploads, application state
Bind mounts for development: source code, config files you want to edit live
Read-only mounts for config: seed data, init scripts, certificates
No mounts for anything truly ephemeral: temp files, build artifacts, logs you do not care about

Once this becomes habit, you stop losing data and start treating your containers with appropriate disposability — stateless app containers come and go freely, while your precious data sits safely in volumes.

Wrapping Up

Docker volumes are one of those things that seem complicated until they click, and then they seem obvious. The key insight is simple: separate your stateless compute (containers) from your stateful data (volumes).

Named volumes for production, bind mounts for development, always back up your volumes before doing anything destructive, and never use anonymous volumes if you can help it.

Now go check your running containers — you might have some orphaned anonymous volumes sitting around, taking up space and holding data you have already forgotten about.

docker volume ls
docker volume prune

You have been warned.

Docker Networking Demystified: How Containers Actually Talk to Each Other

Teguh Coding — Tue, 03 Mar 2026 12:05:30 +0000

Most developers treat Docker networking like a black box. You type docker run, the container starts, things work (or they don't), and you spend 45 minutes Googling why your app can't reach the database.

I've been there. After debugging one too many "connection refused" errors in containers that should be talking to each other, I decided to actually understand how Docker networking works under the hood. This post is what I wish I had read back then.

The Mental Model: Containers Are Not VMs

Before diving in, one shift in thinking matters: containers share the host kernel. They're not isolated machines — they're isolated processes. Docker networking is about creating logical boundaries and channels between those processes.

When Docker installs, it creates a virtual network bridge called docker0 on your host. Think of it like a virtual switch that containers plug into. Each container gets a virtual ethernet interface (veth pair), one end inside the container, one end connected to docker0.

You can see this right now:

ip addr show docker0
# Look for the 172.17.0.1 range — that's Docker's default subnet

The Four Network Drivers

Docker ships with four built-in network drivers. Understanding when to use each one saves a lot of pain.

1. Bridge (Default)

This is what you get if you don't specify anything. Containers on the same bridge network can talk to each other. Containers on different bridge networks cannot — unless you explicitly connect them.

# Create a custom bridge network
docker network create my-app-network

# Run containers on that network
docker run -d --name api --network my-app-network my-api-image
docker run -d --name db --network my-app-network postgres:15

Now api can reach db by hostname — just postgres://db:5432/mydb. Docker's embedded DNS handles the name resolution automatically on custom bridge networks.

Important: The default docker0 bridge does NOT support DNS-based hostname resolution between containers. That's the #1 footgun for beginners. Always create a custom bridge network.

2. Host

The container shares the host's network stack entirely. No isolation, no port mapping needed — the container's port 3000 IS the host's port 3000.

docker run --network host nginx
# nginx is now accessible on the host's port 80 directly

Use this when performance is critical and you're on Linux. Avoid on Mac/Windows where Docker runs inside a VM anyway — the semantics get weird.

3. None

Completely disables networking. The container gets a loopback interface only.

docker run --network none my-batch-job

Perfect for security-sensitive batch processing that should never touch the network.

4. Overlay

For multi-host networking in Docker Swarm. Containers on different physical machines can communicate as if they're on the same network. Uses VXLAN encapsulation under the hood.

We'll skip the deep dive here — overlay is a Swarm-specific topic worth its own post.

Docker Compose: Networking Done Right

Here's where 90% of day-to-day Docker networking happens. Docker Compose automatically creates a custom bridge network for your stack and wires up all services. This is the happy path.

# docker-compose.yml
version: '3.9'

services:
  api:
    build: ./api
    ports:
      - "3000:3000"
    environment:
      DB_HOST: db
      REDIS_HOST: cache
    depends_on:
      - db
      - cache

  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: secret
    volumes:
      - pgdata:/var/lib/postgresql/data

  cache:
    image: redis:7-alpine

volumes:
  pgdata:

In this stack, api can reach db at db:5432 and cache at cache:6379. No magic — it's Docker's DNS using service names.

Multiple Networks in Compose

What if you want isolation within your stack? Maybe your frontend should reach the API but NOT the database directly.

version: '3.9'

services:
  frontend:
    image: nginx
    networks:
      - frontend-net

  api:
    build: ./api
    networks:
      - frontend-net
      - backend-net

  db:
    image: postgres:15
    networks:
      - backend-net

networks:
  frontend-net:
  backend-net:

Now frontend and api share a network. api and db share a separate network. frontend has zero path to db. Clean security segmentation, zero extra config.

Port Mapping: What Actually Happens

When you do -p 8080:3000, you're telling Docker:

Listen on host port 8080
Forward traffic to container port 3000

Docker uses iptables rules under the hood (on Linux) to route that traffic through NAT. You can inspect this:

sudo iptables -t nat -L DOCKER --line-numbers

You'll see DNAT rules for each port mapping.

A few patterns worth knowing:

# Bind only to localhost (more secure — not exposed externally)
docker run -p 127.0.0.1:5432:5432 postgres

# Let Docker pick a random host port
docker run -p 3000 my-app

# Map all exposed ports automatically
docker run -P my-app

For internal services (databases, caches), consider NOT publishing ports at all. If they're on the same Docker network, other containers can reach them without exposing them to the host.

Debugging Network Issues

When something's not connecting, here's the toolkit:

# Inspect a network
docker network inspect my-app-network

# See which containers are connected
docker network inspect my-app-network --format '{{json .Containers}}' | python3 -m json.tool

# Test connectivity from inside a container
docker exec -it api ping db
docker exec -it api curl http://db:8080/health

# Drop into a container with networking tools
docker run --rm --network my-app-network nicolaka/netshoot nslookup db
docker run --rm --network my-app-network nicolaka/netshoot traceroute db

The nicolaka/netshoot image is a lifesaver — it's a container packed with every networking diagnostic tool you'd ever want: curl, nslookup, dig, netstat, ss, tcpdump, iperf3, and more.

A Real-World Example: API + Database + Reverse Proxy

Putting it all together with a realistic three-tier setup:

version: '3.9'

services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    networks:
      - public-net

  api:
    build: ./api
    environment:
      NODE_ENV: production
      DB_URL: postgresql://app_user:secret@db:5432/appdb
    networks:
      - public-net
      - private-net
    # No ports exposed — only reachable via nginx

  db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: app_user
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: appdb
    volumes:
      - pgdata:/var/lib/postgresql/data
    networks:
      - private-net
    # No ports exposed — only reachable by api

networks:
  public-net:
  private-net:
    internal: true  # This network has NO external internet access

volumes:
  pgdata:

Note the internal: true on the private network — containers on that network cannot reach the internet at all, only each other. That's a solid security posture for a database tier.

Key Takeaways

Always create custom bridge networks — never rely on the default docker0 bridge for inter-container communication
Docker Compose handles 90% of networking automatically — service names become hostnames
Use multiple networks within a Compose stack to enforce security boundaries
Don't publish ports for services that only need to talk to other containers
nicolaka/netshoot is your debugging best friend
internal: true networks block outbound internet access entirely

Docker networking clicked for me the moment I stopped thinking of containers as mini-VMs and started thinking of them as processes with shared networking abstractions. Once that mental model locks in, debugging becomes a lot less mysterious.

What networking issue has tripped you up the most? Drop it in the comments — I'm curious how many people have hit the default bridge DNS problem.