DEV Community: Niraj Maharjan

A Practical Guide to Structuring a Go Backend

Niraj Maharjan — Mon, 31 Aug 2026 15:04:49 +0000

Folders aren't the framework. Responsibilities are.

If you've watched a Go backend tutorial, you've probably seen a project structured like this:

project/
├── cmd/api/main.go
├── internal/
│   ├── handlers/
│   ├── services/
│   ├── repository/
│   ├── database/
│   └── config/
├── migrations/
├── go.mod
├── go.sum
└── Makefile

It looks like a rulebook. It isn't. This is one convention among several, and the value isn't in the folder names — it's in the idea that different kinds of code shouldn't get tangled together. This post walks through why that separation exists, where the real decision points are (interfaces, validation, testing), and where people — including tutorials — tend to overstate things as "rules" when they're really trade-offs.

1. Follow One Request Through the System

The fastest way to understand the layout is to trace POST /users through it:

Client → Handler → Service → Repository → Database

cmd/api/main.go — wires everything together (dependency injection). It doesn't do business work; it assembles the app: config → database → repository → service → handler → router → server.
internal/handlers/ — the HTTP layer. Parses requests, does shape-level checks, calls the service, writes the response.
internal/services/ — business logic. Doesn't know or care whether the caller was HTTP, gRPC, or a CLI.
internal/repository/ — data access. Knows how to talk to the database; the service doesn't need to know the SQL.
internal/database/ — connection setup, pooling, health checks. Distinct from repository, which is about queries, not connections.
internal/config/ — environment-driven values (DATABASE_URL, PORT, JWT_SECRET) instead of hardcoded strings.
migrations/ — versioned, reproducible schema history (001_create_users.up.sql, etc.) via tools like golang-migrate or goose.
go.mod / go.sum — module definition and dependency checksums, both committed to source control.
Makefile — shortcuts (make run, make test) so nobody has to memorize go build -o bin/api ./cmd/api.

internal/ isn't decorative, either — Go enforces it at compile time. A package inside internal/ can only be imported by code within the parent module, which is exactly what you want for application-specific code that isn't a public library.

2. The Full File & Folder Catalog

Beyond the core layers, a realistic Go backend accumulates a handful of other files and folders. Here's what each one is actually for — and which ones are load-bearing vs. optional.

Root-level files

go.mod — declares the module (module github.com/you/project), the Go version, and lists dependencies. Updated automatically when you run go get.
go.sum — cryptographic checksums for every dependency, so builds are verifiable and reproducible. Think of go.mod as "what I need" and go.sum as "and here's proof it's the expected content." Both get committed; you basically never hand-edit go.sum.
Makefile — not Go-specific, just a shortcut layer (make run, make test, make build, make fmt) so nobody has to remember the full go build -o bin/api ./cmd/api incantation.
.env / .env.example — .env holds real environment values (DATABASE_URL=..., JWT_SECRET=...) and should be gitignored, never committed. .env.example is the checked-in template with blank or fake values, so anyone cloning the repo knows what variables exist without seeing real secrets.
.gitignore — keeps .env, build output (/bin), temp files, and logs out of version control.

`cmd/` — your executables

cmd/
├── api/main.go      → HTTP server
├── worker/main.go   → background job processor
└── migrate/main.go  → migration runner

cmd/ answers "what programs does this repo produce?" — one subfolder per binary. A project can have just api/, or grow to include a worker process, a migration CLI, etc., all sharing the same internal/ packages.

`internal/main.go` — what it's actually doing

func main() {
    cfg := config.Load()
    db := database.Connect(cfg.DatabaseURL)

    repo := repository.NewUserRepository(db)
    service := services.NewUserService(repo)
    handler := handlers.NewUserHandler(service)

    router := setupRouter(handler)
    http.ListenAndServe(":8080", router)
}

This is dependency injection / wiring, not business logic. Its only job is assembling the chain: config → database → repository → service → handler → router → server.

Other common `internal/` folders

middleware/ — code that runs around handlers, not inside them: logging, authentication, rate limiting, panic recovery. Order matters — a request typically passes through logging → auth → rate limiting → handler.
models/ — plain data structs (type User struct {...}). Not mandatory: many Go projects skip a dedicated models/ folder and instead colocate a model.go inside a feature package (e.g. internal/user/model.go).
routes/ — maps URLs to handlers (router.POST("/users", userHandler.Create)). Some projects keep this directly in main.go instead, or call it server/, router/, or http/. There's no universal convention here.
dto/ — Data Transfer Objects, used when your database model shouldn't be exposed as-is over the API (e.g. a User struct has PasswordHash, but UserResponse strips it out before serializing to JSON). Useful once an API's public shape diverges from its storage shape; unnecessary for small projects where they're identical.

Outside `internal/`

migrations/ — versioned schema changes (001_create_users.up.sql / .down.sql), run through a tool like golang-migrate or goose so any empty database can be brought up to the current expected schema.
api/ — API contract files, typically OpenAPI/Swagger specs (openapi.yaml). Can be used to generate docs, client SDKs, or server interfaces.
docs/ — project documentation (architecture.md, deployment.md) — plain and self-explanatory.
scripts/ — one-off operational scripts that aren't application code: seed.sh, setup.sh, deploy.sh.
tests/ — usually not needed. Go's idiom is to keep tests beside the code they test (user.go next to user_test.go), not in a separate top-level folder. go test ./... finds them regardless of nesting.

`pkg/` — the controversial one

pkg/
├── logger/
├── auth/
└── validator/

The intent behind pkg/ is "code here is meant to be imported by external projects." It's popular in some repos, but it's not required, and it's one of the most commonly cargo-culted folders — people arrive assuming internal = private and pkg = public as a hard Go rule and sort everything into one or the other without asking whether they're actually building a reusable library. If you are genuinely building something importable, it can just live at the repo root as its own package; if it's application-specific, it belongs in internal/ regardless of whether pkg/ exists.

Core vs. optional, at a glance

Tier	Folders/files
Core, almost always present	`cmd/`, `internal/`, `go.mod`, `go.sum`
Very common in backend APIs	`handlers/`, `services/`, `repository/`, `database/`, `config/`, `migrations/`
Common, depending on project size	`middleware/`, `models/`, `routes/`, `api/`, `docs/`, `scripts/`
Add deliberately, not by default	`pkg/`, `utils/`, `helpers/`, `common/`, `dto/`

3. Why Bother With a Repository Interface at All?

This is the first place people either over-engineer or under-engineer. The point of an interface isn't the interface — it's what it decouples.

type UserRepository interface {
    GetByID(ctx context.Context, id string) (*User, error)
    Save(ctx context.Context, u *User) error
}

type UserService struct {
    repo UserRepository // depends on the interface, not the struct
}

Two real benefits:

Testability. In a service-layer unit test, you can hand the service a fake repository that returns canned data — no real database required.
Swappability. Move from Postgres to something else, or add a caching layer in front of it, and the service code doesn't change. It only knows about method signatures.

The Go-specific twist: define the interface in the consuming package (next to UserService), not next to the implementation (postgresUserRepo). This is the opposite of the Java/C# habit of pairing an interface with its implementation. Go uses structural typing — no implements keyword — so the consumer just declares "here's what I need," and any type with matching methods satisfies it automatically.

When to actually add one — ask:

Will there be more than one implementation? (Real DB + test mock counts as two.)
Am I crossing a layer boundary where I want to decouple the consumer from the implementation?
Will this need to be swapped or faked in a test?

If a function has no external dependency (no DB, network, or filesystem), it usually doesn't need an interface — test it directly. For a small CLI tool or a single-implementation package nobody's mocking, skip it. Adding one later, when a second implementation shows up, is a five-minute refactor in Go — not the architectural commitment it is in some other languages.

4. Validation Isn't One Thing — It's (At Least) Two

A common misconception is "validation happens in the service layer." In practice it splits cleanly by what kind of question is being asked:

Layer	Validates	Example
Handler	Is the request well-formed?	JSON parses, required fields exist, types are right, string fields match an expected shape (email, UUID, date)
Service	Is this operation semantically allowed?	Is this email already registered? Does the user have permission? Is the order in a cancellable state?

Type checking mostly happens for free during JSON decoding — send a string where an int is expected and it fails at bind time. Struct tags plus a library like go-playground/validator handle shape-level checks declaratively:

type CreateUserRequest struct {
    Email string `json:"email" validate:"required,email"`
    Age   int    `json:"age"   validate:"required,gte=18"`
}

Normalization (trimming whitespace, lowercasing an email) also tends to live at the boundary — it's not quite validation, it's cleanup before validation runs.

The service layer then checks things that require business context or a database lookup — things the handler structurally cannot know:

func (s *UserService) CreateUser(ctx context.Context, req CreateUserRequest) error {
    existing, _ := s.repo.GetByEmail(ctx, req.Email)
    if existing != nil {
        return ErrEmailAlreadyExists // business rule, not a shape check
    }
    // ...
}

Why not just put everything in the handler? Because the moment you add a second entry point — a CLI tool, a background import job, a gRPC service — business rules enforced only in the HTTP handler get silently skipped or duplicated. Centralizing them in the service means every entry point shares the same rules.

One thing worth flagging explicitly: this isn't double validation of the same fact. The handler checks shape; the service checks meaning. They're answering different questions, not repeating the same one.

5. What Actually Needs a `_test.go` File?

Not everything, despite what "one test file per source file" suggests as an ideal. The convention (foo.go + foo_test.go, same package, same directory) is real and idiomatic — Go's tooling assumes it — but applying it everywhere isn't a rule people actually follow.

Write tests for: anything with branching logic, business rules, edge cases, parsing/validation, error paths. This is most of what lives in services/.
Usually skip: trivial getters, main.go, pure wiring/DI code, thin pass-through structs with no logic.

A decent gut check: if you can't imagine a bug living in that file, you probably don't need a test for it.

Test types map onto the layers differently:

Service tests are usually the highest-value unit tests — swap in a fake repository, and you're testing business rules without touching a database.
Handler tests use net/http/httptest with a fake service, checking status codes and response shape for well-formed vs. malformed input.
Repository tests are more often integration tests — you're really verifying the SQL and scanning logic work against a real (often ephemeral/test) database, not something a fake can substitute for.
Config tests are worth having when there's real logic (defaults, required-field checks) — not just for the sake of coverage.

A rough test pyramid: many unit tests (services, pure logic), some integration tests (repositories, key HTTP flows), few end-to-end tests (critical user journeys only).

6. Misconceptions and Pitfalls Worth Naming Explicitly

These are the places where tutorials (and the source material this post is based on) tend to state something as more universal than it actually is, or where beginners commonly overreach:

"This is the standard Go structure." It isn't. There's no official Go backend layout. The layered structure (handlers/services/repository/) and the feature-oriented structure (internal/user/, internal/order/, each bundling its own handler+service+repo+model) are both legitimate, with different scaling trade-offs. Layered structure keeps related types of logic together; feature-oriented keeps related domains together. Neither is "correct" — they're different answers to "what will I need to find quickly six months from now?"
"internal/ is private, pkg/ is public" as a default. This is a carried-over assumption from other ecosystems. Go doesn't require it. If something is application-specific, internal/ is usually right regardless of whether you also have a pkg/. Don't create pkg/ just because a template has one.
Interfaces "because clean architecture says so." Defining a UserRepository interface with every CRUD method the concrete type has — without ever swapping the implementation or mocking it in a test — is abstraction for its own sake. The interface should describe what the consumer needs, not mirror the implementation's full surface area.
Repositories as an assumed requirement. For a small application, handler → database directly is a legitimate choice. Repositories earn their keep as the codebase and test surface grow, not by default.
utils/ as a junk drawer. A package should have one clear responsibility. A utils/ folder that accumulates string.go, date.go, auth.go, email.go is a sign that logic wasn't given a real home — and it tends to grow, unlike everything else, without anyone questioning it.
Sanitization vs. validation vs. escaping, treated as one thing. They're not interchangeable: strings.TrimSpace is normalization, checking an email format is validation, escaping output for HTML display is contextual encoding, and preventing SQL injection is about parameterized queries — never manual string sanitization. Conflating these leads to either redundant checks or, worse, gaps (e.g., assuming "I validated the input" also means "I'm safe from SQL injection," which it doesn't — parameterization is a separate, non-optional step).
Assuming internal → repository → database is the only safe direction, without saying why. The dependency direction matters because it keeps lower layers ignorant of higher ones: a repository shouldn't import anything HTTP-related, and a database package shouldn't know a handler exists. If you find a lower layer importing from a higher one, that's usually a sign a responsibility landed in the wrong place — not just a style nit.
Treating 100% test-file coverage as a proxy for correctness. A main.go_test.go or a test for a one-line getter doesn't reduce risk much; it mostly pads a coverage number. Test where a bug is plausible, not where a file exists.

The One Thing to Actually Remember

Don't memorize folder names — memorize the three questions:

Is this about HTTP? → Handler.
Is this a business rule? → Service.
Is this about storing or retrieving data? → Repository.

And a fourth question, orthogonal to the first three: does this layer need to know the concrete implementation it's talking to, or just the capability? That's what an interface is for — nothing more mystical than that.

Start simple. A 500-line service might genuinely only need main.go, a couple of packages, and go.mod. Add structure when the pain of not having it shows up — not because a tutorial's folder tree looked complete.

Understanding Go Concurrency Through Pipelines: Channels, Goroutines, and the Questions Everyone Asks

Niraj Maharjan — Mon, 20 Jul 2026 12:57:22 +0000

If you've written a Go pipeline like the one below and felt like something "shouldn't work" but somehow does, you're not alone. This pattern — three stages connected by channels — trips up almost everyone the first time, because it forces you to unlearn the instinct that functions "finish their work" before returning.

func sliceToChannel(nums []int) <-chan int {
    out := make(chan int)
    go func() {
        for _, n := range nums {
            out <- n
        }
        close(out)
    }()
    return out
}

func sq(in <-chan int) <-chan int {
    out := make(chan int)
    go func() {
        for n := range in {
            out <- n * n
        }
        close(out)
    }()
    return out
}

func main() {
    nums := []int{1, 2, 3, 4, 5}
    // Stage 1
    dataChannel := sliceToChannel(nums)
    // Stage 2
    finalChannel := sq(dataChannel)
    // Stage 3
    for nums := range finalChannel {
        fmt.Println(nums)
    }
}

The big picture

This is the pipeline pattern: independent stages, each running in its own goroutine, connected by channels that act as conveyor belts.

sliceToChannel()  --channel-->  sq()  --channel-->  main() prints
   (Stage 1)                  (Stage 2)              (Stage 3)

Each stage does one job and hands its output downstream. No stage needs to know how the others are implemented — it just needs a channel to read from and a channel to write to. That decoupling is the entire point of the pattern.

Let's unpack every piece of confusion this code tends to cause.

1. Why is there a `return` if two goroutines are supposed to be communicating?

This is the core insight most people miss: a function and the goroutine launched inside it are two different things that finish at completely different times.

func sliceToChannel(nums []int) <-chan int {
    out := make(chan int)   // 1. create the channel
    go func() {              // 2. launch a goroutine — runs concurrently
        for _, n := range nums {
            out <- n
        }
        close(out)
    }()
    return out                // 3. function returns IMMEDIATELY
}

Step by step:

out := make(chan int) creates an empty pipe. Nobody has sent or received anything yet.
go func(){...}() schedules the inner function to run concurrently. Go doesn't wait for it to do anything — it kicks it off in the background and immediately moves to the next line.
return out hands back the channel itself — the pipe, not any data flowing through it. The goroutine may not have even started executing yet.

So the return isn't "returning the result of a communication." It's returning a handle to the pipe, so whoever called sliceToChannel() can start receiving whenever they're ready. The goroutine keeps running independently, feeding values into that pipe over time.

Mental model: you're handing someone a garden hose that's about to have water pushed through it. You don't wait for all the water to come out before handing over the hose — you hand it over immediately, and the water flows through later, concurrently, while you both go about your business.

2. What does `close` actually do?

close(out) does not delete the channel or block anyone from reading it. It's a signal: "no more values are coming."

This matters because of how range and receive operations behave:

for n := range in {
    out <- n * n
}
close(out)

range over a channel keeps pulling values, one at a time, and blocks when the channel is empty. It only exits the loop when the channel is both empty and closed.

If you never call close, range blocks forever after the last value — waiting for a value that will never arrive. That's a deadlock, and we'll trigger one deliberately in a minute so you can see exactly what it looks like.

There's a two-value receive form that shows what's happening under the hood:

n, ok := <-out

ok is false once the channel is closed and drained. range uses this internally to know when to stop.

Two rules worth memorizing:

Only the sender should close a channel — never the receiver.
Close a channel at most once. Closing an already-closed channel panics.

3. The channel is unbuffered — so why does looping over it make sense?

These are two unrelated concepts, and mixing them up is a common source of confusion.

Buffered vs. unbuffered is about how many values can sit in the channel waiting to be picked up before a send blocks.

make(chan int) → unbuffered, capacity 0. A send (out <- n) blocks until another goroutine is simultaneously ready to receive. It's a synchronous handshake.
make(chan int, 5) → buffered, capacity 5. A send only blocks once the buffer is full.

range/looping is about how many values total will pass through the channel over its lifetime — completely independent of buffering.

Even with an unbuffered channel, many values can flow through sequentially, one handshake at a time. range just keeps asking "give me the next value" until the channel closes. Buffering only changes whether the sender has to wait for a receiver right now — it doesn't change whether looping is meaningful.

So in sq:

for n := range in {      // receive one value at a time, block if none ready
    out <- n * n          // send one value, block until sq's downstream receives it
}

Each iteration is one handshake in, one handshake out. Nothing is buffered in bulk anywhere — it's a pure pass-through, value by value.

4. How `main()` actually executes, concurrently

nums := []int{1, 2, 3, 4, 5}
dataChannel := sliceToChannel(nums)   // starts goroutine #1, returns channel immediately
finalChannel := sq(dataChannel)        // starts goroutine #2, returns channel immediately
for nums := range finalChannel {       // main blocks here, pulling values
    fmt.Println(nums)
}

At this point there are three concurrently running things: the sliceToChannel goroutine, the sq goroutine, and main itself. None of them wait for each other to fully finish — they run interleaved, synchronizing only at the moments they send or receive on a shared channel.

A caveat before the trace below: the Go scheduler doesn't guarantee this exact sequence of who-blocks-first. What's guaranteed is that values arrive at main in order (1, 4, 9, 16, 25) because each unbuffered handshake is a strict rendezvous. The blow-by-blow below is one valid way this plays out — useful for building intuition, not a literal scheduler log.

In prose form:

Goroutine 1 tries out <- 1. It blocks — nobody's receiving yet.
Goroutine 2's range in attempts <-in. This matches goroutine 1's send. Handshake: 1 moves across. Goroutine 1 continues and tries out <- 2 (blocks again). Goroutine 2 now has n = 1, computes 1*1 = 1, tries out <- 1 on its own channel — blocks, since main isn't receiving yet.
main's range finalChannel attempts <-finalChannel. Matches goroutine 2's send. 1 arrives in main and gets printed.
This repeats: 2 → 4, 3 → 9, 4 → 16, 5 → 25, printed one at a time.
After the last value, goroutine 1's loop ends and it calls close(out). Goroutine 2's range in sees the channel closed, exits its loop, and calls close(out) on its own channel. main's range finalChannel sees that close too, and its loop ends naturally.
main() finishes normally.

No deadlock, no explicit sync.WaitGroup needed — the close signal cascades down the pipeline and unwinds everything cleanly.

5. Read-only channels and why functions return them

func sliceToChannel(nums []int) <-chan int

<-chan int is a directional channel type — specifically receive-only. The arrow points away from chan, meaning "you can only receive from this, not send into it."

There's also chan<- int (send-only — arrow points into chan) and plain chan int (bidirectional).

Why bother? It's a compile-time safety contract. Inside sliceToChannel, out is an ordinary bidirectional chan int, because the goroutine needs to send on it. But the function's return type is declared <-chan int. Go allows this implicit conversion automatically because it's narrowing (bidirectional → directional), not widening.

The caller then only ever has a receive-only view:

dataChannel := sliceToChannel(nums)   // dataChannel is <-chan int

If you accidentally wrote dataChannel <- 10 somewhere in main, the compiler rejects it — because as far as main is concerned, that channel is receive-only. This prevents a whole class of bugs: a downstream consumer accidentally becoming a producer, or closing a channel it doesn't own.

This is the discipline the whole pipeline pattern relies on:

The function that creates and owns a channel is the only one allowed to send on it or close it.
Everyone downstream gets a <-chan view — read-only, can't send, can't close, can't mess it up.

6. What happens if you forget to `close`? (Deliberately breaking it)

Let's trigger the failure mode on purpose. Drop the close(out) call from sliceToChannel:

func sliceToChannelBroken(nums []int) <-chan int {
    out := make(chan int)
    go func() {
        for _, n := range nums {
            out <- n
        }
        // close(out) — deliberately omitted
    }()
    return out
}

Run this through the same pipeline, and here's what happens:

Values 1 through 5 flow through and get printed exactly as before — the missing close doesn't affect delivery of values that do exist.
After 5 is sent, goroutine 1's for loop ends. It falls off the end of the function without calling close.
Goroutine 2's range in has delivered its last value and now calls <-in again, waiting for the next one. But no more values are coming, and the channel was never closed — so this receive blocks forever.
Because goroutine 2 never finishes, it never closes its own out channel either.
main's range finalChannel is waiting on a channel that will now never close and never receive another value. It blocks forever too.

Since every goroutine is now permanently blocked and none of them can be woken up by anything, the Go runtime detects this and panics:

fatal error: all goroutines are asleep - deadlock!

This is Go's built-in deadlock detector — it notices when the entire program has nothing left to schedule, not just one goroutine. It's one of the few runtime safety nets you get for free with channels: forgetting a close doesn't silently hang forever with no explanation, it (usually) surfaces loudly.

Takeaway: close isn't just tidiness — in a range-based pipeline, it's the only thing that tells downstream consumers "stop waiting, there's nothing left."

7. What changes if you add buffering?

Now let's swap the unbuffered channels for buffered ones and see how the blocking pattern — not the final output — changes.

func sliceToChannelBuffered(nums []int) <-chan int {
    out := make(chan int, 3) // buffer of 3
    go func() {
        for _, n := range nums {
            out <- n
            fmt.Println("sent", n)
        }
        close(out)
    }()
    return out
}

With make(chan int, 3):

The first three sends (1, 2, 3) succeed immediately, without waiting for anyone to receive — they just land in the buffer.
The fourth send (4) blocks, because the buffer is full and nothing has drained it yet.
Once a receiver takes a value out (freeing a slot), the next blocked send can proceed.

Compare the console output pattern between unbuffered and buffered versions:

Unbuffered (capacity 0): sends and receives are tightly interleaved — you'd see sent 1 immediately followed by a receive of 1, then sent 2, and so on, because each send is a synchronous handshake.

Buffered (capacity 3): you'd see sent 1, sent 2, sent 3 fire off in a rapid burst (no receiver needed yet), and only then would sends and receives start pacing each other, once the buffer fills up.

The final printed sequence in main (1, 4, 9, 16, 25) is identical either way — buffering doesn't change what gets delivered or in what order (channels are always FIFO), only how eagerly the sender can get ahead of the receiver before it's forced to wait.

When does this matter in practice?

A small buffer can smooth out short bursts of speed mismatch between producer and consumer, reducing context-switch overhead.
It does not fix a slow consumer — if the consumer is permanently slower than the producer, the buffer just delays the inevitable blocking, it doesn't eliminate it.
An oversized buffer can hide bugs: a pipeline that "deadlocks" with an unbuffered channel might silently limp along with a giant buffer, only to blow up later at a different, less obvious point (or exhaust memory if the producer runs far ahead of a consumer that never shows up).

Unbuffered channels are usually the right default for pipeline stages, precisely because they surface synchronization bugs immediately (like the deadlock above) instead of masking them behind buffer capacity.

Putting it all together — a mental model

Think of each pipeline stage function as a small factory:

Builds a conveyor belt (make(chan int)).
Hires a worker (go func(){...}()) who starts putting items on the belt whenever ready — running independently, forever, until told to stop.
Immediately hands you the belt (return out) so you can start taking things off it, even though the worker might not have placed anything on it yet.
The worker eventually finishes and flips a "no more items" sign (close), which tells anyone looping over the belt to stop waiting and exit.

Every confusing part of this pattern — the early return, the apparent contradiction of "unbuffered but looped," the deadlock when close is missing, the way buffering changes pacing but not order — falls out of that one factory model once it clicks.

Quick reference

Concept	Rule of thumb
`go func(){...}()`	Starts running concurrently; caller doesn't wait
`return channel`	Hands back a pipe, not data — synchronization happens later
`close(ch)`	Only the sender closes; signals "no more values"; closing twice panics
Unbuffered channel	Send blocks until a matching receive happens — synchronous handshake
Buffered channel	Send blocks only once the buffer is full — some slack before syncing
`range` over a channel	Blocks until a value arrives or the channel closes and drains
`<-chan T` / `chan<- T`	Compiler-enforced read-only / write-only views, prevents misuse
Missing `close` in a `range` pipeline	Deadlock: `fatal error: all goroutines are asleep`

How to Get a Free .np Domain and Host Your Developer Portfolio

Niraj Maharjan — Sun, 12 Apr 2026 15:49:26 +0000

So I finally did it. My portfolio is live, not on some generic .github.io subdomain, but on my own .np domain. Sounds cool, right? It was. But getting there? That was a whole journey. Let me walk you through exactly what I did, where I got stuck, and how you can do it without repeating my mistakes.

Why I Wanted This in the First Place

Every developer eventually wants their own corner of the internet. A portfolio that screams you. I wanted mine to have a personal domain .np because I'm from Nepal and its free of cost. But I also wanted it interactive, modern, with 3D elements. So the stack I chose was Vite + Spline for the frontend.

Simple goal. Not-so-simple execution.

Step 1: Registering My .np Domain

Before writing a single line of code, I went ahead and locked in my domain.

In Nepal, .np domains are managed by Mercantile Communications. Here's the quick rundown:

Go to register.com.np
Check if your desired domain is available
Submit the required documents (citizenship, organization letter if needed)
Wait for approval — this isn't instant like .com

⚠️ Heads up: .np registration is free but it involves a manual review process. It took me a couple of days. Plan accordingly.

Once approved, I had my domain. Now came the real work.

Step 2: Building the Portfolio Site

I built my site using Vite (for fast dev experience) and Spline (for 3D interactive objects).

npm create vite@latest portfolio -- --template react
cd portfolio
npm install

For Spline, I used their React runtime:

npm install @splinetool/react-spline @splinetool/runtime

The Spline objects are embedded directly as components. Super clean.

Step 3: Deploying to GitHub Pages

Since Vite doesn't produce a traditional static site out of the box for GitHub Pages, I needed the gh-pages package.

npm install gh-pages --save-dev

Then I added two scripts in my package.json:

"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d dist"
}

predeploy runs the build automatically before deploy kicks in. Clean.

Then I pushed my code to GitHub, went to my repo → Settings → Pages, and set the source to the gh-pages branch.

Ran npm run deploy and... it was live on https://yourusername.github.io/portfolio.

The Problem I Hit (And How I Fixed It)

Here's where things got frustrating.

My site was loading but all the assets — images, JS, CSS — were broken. Blank screen, console full of 404s.

The issue? Vite's base path.

When your site is hosted at yourusername.github.io/portfolio, Vite needs to know the base path is /portfolio/. But when it's on your custom domain (root of the domain), the base needs to be /.

I couldn't just hardcode one or the other. So I wrote a condition in vite.config.js:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

onst isGithubPages = process.env.GITHUB === "true";

export default defineConfig(({ mode }) => ({
  plugins: [react()],
  base: isGithubPages ? "/portfolio/" : "/",
})

Then in my deploy script (or CI), I just set GITHUB=true when building for the github domain. Problem solved. No more broken paths.

💡 This is one of those things nobody tells you upfront. If your GitHub Pages site looks broken, check your base in vite.config.js first.

Step 4: Setting Up DNS with Cloudflare

With the site working on GitHub Pages, it was time to point my .np domain to it.

I chose Cloudflare for DNS management — it's free, fast, and has a clean interface.

Here's what I did:

1. Create a Cloudflare account and add your domain.

2. Add DNS records pointing to GitHub Pages. GitHub requires 4 A records and 1 CNAME:

Type	Name	Value
A	@	185.199.108.153
A	@	185.199.109.153
A	@	185.199.110.153
A	@	185.199.111.153
CNAME	www	yourusername.github.io

3. Cloudflare gives you two nameservers — something like:

aria.ns.cloudflare.com
bob.ns.cloudflare.com

4. Go back to your .np domain registration panel → find the Edit DNS / Nameserver option → replace the existing nameservers with the two Cloudflare ones.

Then… you wait.

In my case it took about 2 hours for the domain to go active. Some people say it can take up to 48 hours — mine was luckily on the faster end.

Step 5: Connecting the Custom Domain to GitHub

Once DNS was propagating, I went back to my GitHub repo:

Settings → Pages → Custom Domain

I entered my .np domain, saved it, and GitHub automatically verified it and enabled HTTPS via Let's Encrypt.

After the DNS fully kicked in — boom. My portfolio was live on my own .np domain.

The Full Flow at a Glance

Register .np domain
      ↓
Build site with Vite + Spline
      ↓
Add gh-pages, write predeploy + deploy scripts
      ↓
Fix vite.config.js base path logic
      ↓
Deploy to GitHub Pages
      ↓
Set up Cloudflare DNS (4 A records + 1 CNAME)
      ↓
Update nameservers on .np registrar
      ↓
Add custom domain in GitHub repo settings
      ↓
Wait ~2 hours → Live

What I'd Tell My Past Self

Register the domain first. .np takes time to approve. Don't build everything and then wait.
The base path issue in Vite will catch you off guard. Handle it early.
Cloudflare is your friend. Free, reliable, and the dashboard is easy to navigate.
DNS propagation is not instant. Grab a coffee. Don't keep refreshing dig every 30 seconds (I definitely didn't do this).

Final Thoughts

Hosting my own portfolio on a .np domain felt unnecessarily complicated at first. But once you understand each piece — domain registration, GitHub Pages, Vite's config, Cloudflare DNS — it actually makes a lot of sense.

If you're a developer from Nepal and you've been putting this off, this is your sign. The .np domain is free, GitHub Pages is free, Cloudflare is free. The only cost is a couple of hours of your time.

Go build something worth linking to.

The Essential Guide to Application Logging: From Basics to Production

Niraj Maharjan — Wed, 08 Apr 2026 02:10:31 +0000

Introduction: The Black Box Problem

Your application crashed in production at 3 AM. Users are complaining. You SSH into the server and... nothing. No clue what happened, when it happened, or why.

This is what happens without proper logging.

Logging is your application's flight recorder. When something goes wrong (and it will), logs are your only way to understand what happened.

In this guide, you'll learn:

What logging is and why it's critical
Log levels and when to use them
How to implement logging in Python and Node.js
Structured logging for production
Best practices and common mistakes
What NOT to log (security)

What is Logging?

Logging is the practice of recording events, errors, and information about your application's behavior.

The Simple Definition

Logging = Writing down what your application is doing, so you can understand it later

Think of It Like This:

Without Logs:
User reports: "The app crashed"
You: "When? What were you doing? What error?"
User: "I don't remember"
You: 🤷 (Can't fix what you can't see)

With Logs:
User: "The app crashed"
You: *checks logs*
[2024-01-14 03:23:45] ERROR: Database connection timeout after 30s
[2024-01-14 03:23:45] ERROR: Failed to process order #12345
You: ✅ "Database issue, I know how to fix this"

Log Levels Explained

Log levels categorize the importance/severity of log messages.

The Standard Hierarchy

DEBUG    →  Detailed diagnostic information
INFO     →  General informational messages
WARNING  →  Something unexpected but handled
ERROR    →  Error occurred but app continues
CRITICAL →  Serious error, app may crash

When to Use Each Level

1. DEBUG - Development Details

Use for: Detailed diagnostic information useful during development

logger.debug(f"User {user_id} attempting login")
logger.debug(f"SQL Query: {query}")
logger.debug(f"Cache hit: {cache_key}")
logger.debug(f"Function arguments: {args}, {kwargs}")

When: Only in development. Turn OFF in production (too verbose).

2. INFO - Normal Operations

Use for: Confirming things are working as expected

logger.info(f"User {user_id} logged in successfully")
logger.info(f"Order {order_id} created")
logger.info(f"Server started on port 8080")
logger.info(f"Cronjob completed: 500 emails sent")

When: Production. Track normal business operations.

3. WARNING - Something's Off

Use for: Unexpected situations that don't prevent operation

logger.warning(f"API response took 5s (expected <1s)")
logger.warning(f"Disk usage at 85%")
logger.warning(f"Deprecated function called: {func_name}")
logger.warning(f"User tried invalid action: {action}")

When: Things that might become problems. Set up alerts.

4. ERROR - Something Failed

Use for: Errors that prevent a specific operation but app continues

logger.error(f"Failed to send email to {email}", exc_info=True)
logger.error(f"Payment processing failed: {error}")
logger.error(f"Database query failed: {query}")
logger.error(f"File not found: {filepath}")

When: An operation failed. Always log the exception.

5. CRITICAL - Everything's on Fire 🔥

Use for: Severe errors that might crash the application

logger.critical("Database connection pool exhausted")
logger.critical("Out of memory")
logger.critical("Cannot connect to primary database")
logger.critical("Security breach detected")

When: System-level failures. Immediate action required.

Quick Decision Tree

Is it useful for debugging? → DEBUG
Is it a normal operation? → INFO
Is it unexpected but handled? → WARNING
Did something fail? → ERROR
Is the system in danger? → CRITICAL

Implementation: Python

Basic Logging

import logging

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

logger = logging.getLogger(__name__)

# Use it
logger.debug("This won't show (level is INFO)")
logger.info("Application started")
logger.warning("Cache miss for key: user_123")
logger.error("Failed to connect to database")
logger.critical("System out of memory")

Output:

2024-01-14 10:30:45,123 - __main__ - INFO - Application started
2024-01-14 10:30:46,456 - __main__ - WARNING - Cache miss for key: user_123
2024-01-14 10:30:47,789 - __main__ - ERROR - Failed to connect to database
2024-01-14 10:30:48,012 - __main__ - CRITICAL - System out of memory

Production-Ready Setup

import logging
import logging.handlers
import sys
from pathlib import Path

def setup_logging(log_level=logging.INFO):
    """Configure logging for production"""

    # Create logs directory
    log_dir = Path("logs")
    log_dir.mkdir(exist_ok=True)

    # Create logger
    logger = logging.getLogger()
    logger.setLevel(log_level)

    # Format
    formatter = logging.Formatter(
        '%(asctime)s - %(name)s - %(levelname)s - %(message)s',
        datefmt='%Y-%m-%d %H:%M:%S'
    )

    # Console handler (stdout)
    console_handler = logging.StreamHandler(sys.stdout)
    console_handler.setLevel(logging.INFO)
    console_handler.setFormatter(formatter)
    logger.addHandler(console_handler)

    # File handler (rotating)
    file_handler = logging.handlers.RotatingFileHandler(
        log_dir / "app.log",
        maxBytes=10 * 1024 * 1024,  # 10MB
        backupCount=5
    )
    file_handler.setLevel(logging.DEBUG)
    file_handler.setFormatter(formatter)
    logger.addHandler(file_handler)

    # Error file handler (errors only)
    error_handler = logging.handlers.RotatingFileHandler(
        log_dir / "error.log",
        maxBytes=10 * 1024 * 1024,
        backupCount=5
    )
    error_handler.setLevel(logging.ERROR)
    error_handler.setFormatter(formatter)
    logger.addHandler(error_handler)

    return logger

# Initialize
logger = setup_logging()

# Use in your application
def process_order(order_id):
    logger.info(f"Processing order {order_id}")
    try:
        # Process order
        result = do_something(order_id)
        logger.info(f"Order {order_id} processed successfully")
        return result
    except Exception as e:
        logger.error(f"Failed to process order {order_id}: {e}", exc_info=True)
        raise

What this does:

✅ Logs to console (for Docker/CloudWatch)
✅ Logs to rotating files (10MB max, keeps 5 backups)
✅ Separate error log file
✅ Includes timestamps and log levels
✅ Automatically includes stack traces for errors

Structured Logging (JSON)

Why JSON? Easy to parse, search, and analyze with tools like ELK, Splunk, DataDog.

import logging
import json
from datetime import datetime

class JSONFormatter(logging.Formatter):
    """Custom formatter that outputs JSON"""

    def format(self, record):
        log_data = {
            'timestamp': datetime.utcnow().isoformat(),
            'level': record.levelname,
            'logger': record.name,
            'message': record.getMessage(),
            'module': record.module,
            'function': record.funcName,
            'line': record.lineno
        }

        # Add exception info if present
        if record.exc_info:
            log_data['exception'] = self.formatException(record.exc_info)

        # Add extra fields (if any)
        if hasattr(record, 'user_id'):
            log_data['user_id'] = record.user_id
        if hasattr(record, 'request_id'):
            log_data['request_id'] = record.request_id

        return json.dumps(log_data)

# Configure
logger = logging.getLogger(__name__)
handler = logging.StreamHandler()
handler.setFormatter(JSONFormatter())
logger.addHandler(handler)
logger.setLevel(logging.INFO)

# Use with extra context
logger.info("User login", extra={'user_id': 123, 'request_id': 'abc-123'})

Output:

{
  "timestamp": "2024-01-14T10:30:45.123456",
  "level": "INFO",
  "logger": "__main__",
  "message": "User login",
  "module": "app",
  "function": "login",
  "line": 42,
  "user_id": 123,
  "request_id": "abc-123"
}

Benefits:

✅ Easy to query: logs where user_id=123
✅ Structured data for analytics
✅ Works with log aggregation tools

Using python-json-logger (Easier)

from pythonjsonlogger import jsonlogger
import logging

logger = logging.getLogger()
handler = logging.StreamHandler()

# JSON formatter
formatter = jsonlogger.JsonFormatter(
    '%(timestamp)s %(level)s %(name)s %(message)s'
)
handler.setFormatter(formatter)
logger.addHandler(handler)
logger.setLevel(logging.INFO)

# Use it
logger.info("User logged in", extra={
    'user_id': 123,
    'ip_address': '192.168.1.1',
    'user_agent': 'Mozilla/5.0'
})

Implementation: Node.js

Basic Logging with Winston (Industry Standard)

const winston = require('winston');

// Create logger
const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.errors({ stack: true }),
    winston.format.json()
  ),
  transports: [
    // Console output
    new winston.transports.Console({
      format: winston.format.combine(
        winston.format.colorize(),
        winston.format.simple()
      )
    }),
    // File output
    new winston.transports.File({ 
      filename: 'logs/error.log', 
      level: 'error' 
    }),
    new winston.transports.File({ 
      filename: 'logs/combined.log' 
    })
  ]
});

// Use it
logger.debug('Debugging info');
logger.info('User logged in', { userId: 123 });
logger.warn('Slow response time', { duration: 5000 });
logger.error('Database error', { error: err.message });

Production Setup with Winston

const winston = require('winston');
const path = require('path');

// Different formats for different environments
const isDevelopment = process.env.NODE_ENV !== 'production';

const logger = winston.createLogger({
  level: process.env.LOG_LEVEL || 'info',

  // Format
  format: winston.format.combine(
    winston.format.timestamp({
      format: 'YYYY-MM-DD HH:mm:ss'
    }),
    winston.format.errors({ stack: true }),
    winston.format.splat(),
    winston.format.json()
  ),

  // Default metadata
  defaultMeta: { 
    service: 'my-app',
    environment: process.env.NODE_ENV 
  },

  transports: [
    // Console (always)
    new winston.transports.Console({
      format: isDevelopment
        ? winston.format.combine(
            winston.format.colorize(),
            winston.format.printf(({ level, message, timestamp, ...meta }) => {
              return `${timestamp} [${level}]: ${message} ${
                Object.keys(meta).length ? JSON.stringify(meta, null, 2) : ''
              }`;
            })
          )
        : winston.format.json()
    }),

    // File - All logs
    new winston.transports.File({
      filename: path.join('logs', 'combined.log'),
      maxsize: 10485760, // 10MB
      maxFiles: 5
    }),

    // File - Errors only
    new winston.transports.File({
      filename: path.join('logs', 'error.log'),
      level: 'error',
      maxsize: 10485760,
      maxFiles: 5
    })
  ],

  // Handle exceptions and rejections
  exceptionHandlers: [
    new winston.transports.File({ 
      filename: path.join('logs', 'exceptions.log') 
    })
  ],
  rejectionHandlers: [
    new winston.transports.File({ 
      filename: path.join('logs', 'rejections.log') 
    })
  ]
});

module.exports = logger;

Usage in Express:

const express = require('express');
const logger = require('./logger');

const app = express();

// Log all requests
app.use((req, res, next) => {
  const start = Date.now();

  res.on('finish', () => {
    const duration = Date.now() - start;
    logger.info('HTTP Request', {
      method: req.method,
      url: req.url,
      status: res.statusCode,
      duration: `${duration}ms`,
      userAgent: req.get('user-agent'),
      ip: req.ip
    });
  });

  next();
});

// Your routes
app.get('/api/users/:id', async (req, res) => {
  try {
    logger.info('Fetching user', { userId: req.params.id });

    const user = await getUserById(req.params.id);

    logger.info('User fetched successfully', { 
      userId: req.params.id,
      username: user.username 
    });

    res.json(user);
  } catch (error) {
    logger.error('Failed to fetch user', {
      userId: req.params.id,
      error: error.message,
      stack: error.stack
    });

    res.status(500).json({ error: 'Internal server error' });
  }
});

// Global error handler
app.use((err, req, res, next) => {
  logger.error('Unhandled error', {
    error: err.message,
    stack: err.stack,
    url: req.url,
    method: req.method
  });

  res.status(500).json({ error: 'Something went wrong' });
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  logger.info('Server started', { port: PORT });
});

Simple Console Logging (Quick Start)

// Don't use console.log in production!
// But if you must keep it simple:

const log = {
  debug: (msg, ...args) => console.log(`[DEBUG] ${msg}`, ...args),
  info: (msg, ...args) => console.log(`[INFO] ${msg}`, ...args),
  warn: (msg, ...args) => console.warn(`[WARN] ${msg}`, ...args),
  error: (msg, ...args) => console.error(`[ERROR] ${msg}`, ...args)
};

log.info('User logged in', { userId: 123 });
log.error('Database error', new Error('Connection failed'));

⚠️ Not recommended for production - use Winston or Pino instead.

What to Log (and What NOT to Log)

✅ DO Log

1. Application Lifecycle

logger.info("Application started")
logger.info("Database connection established")
logger.info("Server listening on port 8080")
logger.info("Graceful shutdown initiated")

2. Business Operations

logger.info(f"Order {order_id} created by user {user_id}")
logger.info(f"Payment processed: ${amount}")
logger.info(f"Email sent to {email}")

3. Errors and Exceptions

try:
    result = risky_operation()
except Exception as e:
    logger.error(f"Operation failed: {e}", exc_info=True)
    # exc_info=True includes the stack trace

4. Performance Metrics

start = time.time()
result = slow_operation()
duration = time.time() - start

if duration > 1.0:
    logger.warning(f"Slow operation: {duration:.2f}s")

5. Security Events

logger.warning(f"Failed login attempt for user {username} from {ip}")
logger.error(f"Invalid API key used: {api_key[:8]}...")
logger.critical("Potential SQL injection detected")

6. External Service Calls

logger.info(f"Calling external API: {api_url}")
logger.error(f"External API failed: {api_url} - {status_code}")

❌ DO NOT Log

1. Passwords (NEVER)

# ❌ NEVER DO THIS
logger.info(f"User login: {username} with password {password}")

# ✅ DO THIS
logger.info(f"User login: {username}")

2. API Keys / Secrets

# ❌ BAD
logger.debug(f"Stripe key: {stripe_key}")

# ✅ GOOD (if you must log it)
logger.debug(f"Stripe key: {stripe_key[:8]}...")  # First 8 chars only

3. Credit Card Numbers

# ❌ BAD
logger.info(f"Processing card {card_number}")

# ✅ GOOD
logger.info(f"Processing card ending in {card_number[-4:]}")

4. Personal Identifiable Information (PII)

# ❌ BAD
logger.info(f"User data: {email}, {ssn}, {address}")

# ✅ GOOD
logger.info(f"User data updated", extra={'user_id': user_id})

5. Full Request/Response Bodies (in production)

# ❌ BAD (may contain sensitive data)
logger.debug(f"Request body: {request.body}")

# ✅ GOOD
logger.debug(f"Request received", extra={
    'endpoint': request.path,
    'method': request.method,
    'content_length': len(request.body)
})

Best Practices

1. Use Structured Logging

// ❌ BAD - Hard to parse
logger.info(`User 123 logged in from 192.168.1.1`);

// ✅ GOOD - Structured, searchable
logger.info('User logged in', {
  userId: 123,
  ipAddress: '192.168.1.1',
  timestamp: new Date().toISOString()
});

Why? You can search: "Show me all logs where userId=123"

2. Include Context

# ❌ BAD - No context
logger.error("Database error")

# ✅ GOOD - Full context
logger.error(
    "Database connection failed",
    extra={
        'database': 'postgresql',
        'host': 'db.example.com',
        'port': 5432,
        'timeout': 30,
        'retry_count': 3
    },
    exc_info=True
)

3. Use Correlation IDs

// Generate unique ID for each request
app.use((req, res, next) => {
  req.requestId = crypto.randomUUID();
  next();
});

// Include in all logs
app.get('/api/users', async (req, res) => {
  logger.info('Fetching users', { requestId: req.requestId });

  try {
    const users = await db.getUsers();
    logger.info('Users fetched', { 
      requestId: req.requestId, 
      count: users.length 
    });
    res.json(users);
  } catch (error) {
    logger.error('Failed to fetch users', { 
      requestId: req.requestId,
      error: error.message 
    });
    res.status(500).json({ error: 'Server error' });
  }
});

Benefit: Track a single request across multiple log entries.

4. Log at the Right Level

# Development
logger.setLevel(logging.DEBUG)  # See everything

# Staging
logger.setLevel(logging.INFO)   # Normal operations + errors

# Production
logger.setLevel(logging.WARNING)  # Only warnings and errors

Set via environment variable:

import os
log_level = os.getenv('LOG_LEVEL', 'INFO')
logger.setLevel(getattr(logging, log_level.upper()))

5. Rotate Log Files

from logging.handlers import RotatingFileHandler

handler = RotatingFileHandler(
    'app.log',
    maxBytes=10 * 1024 * 1024,  # 10MB
    backupCount=5                # Keep 5 old files
)
# Creates: app.log, app.log.1, app.log.2, app.log.3, app.log.4, app.log.5

Why? Prevent logs from filling up disk space.

6. Don't Log in Loops (Unless Necessary)

# ❌ BAD - Creates 1 million log entries
for user in users:  # 1 million users
    logger.info(f"Processing user {user.id}")
    process_user(user)

# ✅ GOOD - Log summary
logger.info(f"Starting batch process for {len(users)} users")
for user in users:
    process_user(user)
logger.info(f"Batch process completed")

# ✅ GOOD - Log errors only
for user in users:
    try:
        process_user(user)
    except Exception as e:
        logger.error(f"Failed to process user {user.id}: {e}")

7. Use Appropriate Formats for Environments

// Development: Human-readable
const devFormat = winston.format.combine(
  winston.format.colorize(),
  winston.format.printf(info => `${info.level}: ${info.message}`)
);

// Production: JSON for parsing
const prodFormat = winston.format.json();

const logger = winston.createLogger({
  format: process.env.NODE_ENV === 'production' ? prodFormat : devFormat,
  transports: [new winston.transports.Console()]
});

Common Mistakes

Mistake #1: Logging Too Much in Production

# ❌ BAD - DEBUG in production
logger.setLevel(logging.DEBUG)

# Result: Gigabytes of logs, costs $$$, slows down app

# ✅ GOOD
logger.setLevel(logging.WARNING)  # Only warnings and errors

Mistake #2: Not Logging Enough Context

# ❌ BAD
logger.error("Error occurred")
# What error? Where? Why?

# ✅ GOOD
logger.error(
    "Failed to process payment",
    extra={
        'user_id': user_id,
        'order_id': order_id,
        'amount': amount,
        'payment_method': payment_method,
        'error_code': error.code
    },
    exc_info=True
)

Mistake #3: Using print() Instead of Logger

# ❌ BAD
print("User logged in")
print("Error:", error)

# Problems:
# - No log levels
# - No timestamps
# - Can't control output
# - Can't send to different destinations

# ✅ GOOD
logger.info("User logged in")
logger.error("Error occurred", exc_info=True)

Mistake #4: Logging Synchronously in High-Traffic Apps

// ❌ Can slow down requests
logger.info('Request processed');  // Blocks until written to file

// ✅ Use async transports
const logger = winston.createLogger({
  transports: [
    new winston.transports.File({
      filename: 'app.log',
      options: { flags: 'a' }  // Append mode
    })
  ]
});

Better: Send logs to a queue (Redis, Kafka) and process asynchronously.

Mistake #5: Not Including Stack Traces for Errors

# ❌ BAD
try:
    risky_operation()
except Exception as e:
    logger.error(f"Error: {e}")
    # Where did it happen? What was the call stack?

# ✅ GOOD
try:
    risky_operation()
except Exception as e:
    logger.error(f"Error: {e}", exc_info=True)
    # Includes full stack trace

Log Aggregation Tools

For production, send logs to centralized systems:

Popular Tools

1. ELK Stack (Elasticsearch, Logstash, Kibana)

from logstash_formatter import LogstashFormatterV1

handler = logging.StreamHandler()
handler.setFormatter(LogstashFormatterV1())
logger.addHandler(handler)

2. CloudWatch (AWS)

import watchtower

logger.addHandler(watchtower.CloudWatchLogHandler(
    log_group='my-app',
    stream_name='production'
))

3. Datadog

const logger = winston.createLogger({
  transports: [
    new winston.transports.Http({
      host: 'http-intake.logs.datadoghq.com',
      path: '/v1/input',
      ssl: true
    })
  ]
});

4. Sentry (for errors)

const Sentry = require('@sentry/node');

Sentry.init({ dsn: 'your-dsn' });

try {
  riskyOperation();
} catch (error) {
  Sentry.captureException(error);
  logger.error('Operation failed', { error });
}

Quick Reference

Python Logging Cheat Sheet

import logging

# Setup
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)

# Usage
logger.debug('Debug message')
logger.info('Info message')
logger.warning('Warning message')
logger.error('Error message', exc_info=True)
logger.critical('Critical message')

# With context
logger.info('User action', extra={'user_id': 123})

# Format
logging.basicConfig(
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    level=logging.INFO
)

Node.js Winston Cheat Sheet

const winston = require('winston');

// Setup
const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.Console(),
    new winston.transports.File({ filename: 'app.log' })
  ]
});

// Usage
logger.debug('Debug message');
logger.info('Info message', { userId: 123 });
logger.warn('Warning message');
logger.error('Error message', { error: err.message });

Conclusion

Key Takeaways

Always log - It's your application's black box recorder
Use log levels correctly - DEBUG for development, INFO for production operations, ERROR for failures
Structure your logs - JSON format for production
Add context - User IDs, request IDs, timestamps
Never log secrets - Passwords, API keys, credit cards
Rotate log files - Prevent disk space issues
Use proper tools - Winston (Node.js), logging module (Python)
Centralize in production - ELK, CloudWatch, Datadog

The Golden Rules

✅ Log enough to debug issues
❌ Don't log so much you can't find anything
✅ Log errors with full context
❌ Never log sensitive data
✅ Use structured logging (JSON)
❌ Don't use print() or console.log() in production

Next Steps

Implement logging in your current project
Add structured logging (JSON format)
Set up log rotation to prevent disk issues
Review your logs - Are you logging the right things?
Set up alerting on ERROR and CRITICAL logs
Consider log aggregation for production (ELK, Datadog)

Questions?

Want to know more about:

Setting up ELK stack?
Distributed tracing with correlation IDs?
Log monitoring and alerting?
Performance impact of logging?

Drop a comment below! 🚀

Remember: Good logging is the difference between fixing a bug in 5 minutes and debugging for 5 hours. Invest time in setting it up properly!

The Complete Guide to Rate Limiting: Protect Your API Like a Pro

Niraj Maharjan — Tue, 07 Apr 2026 03:27:29 +0000

Introduction: The Pizza Delivery Problem

Imagine you own a pizza restaurant. You can make 100 pizzas per hour. One day, someone calls and orders 500 pizzas for delivery in the next 10 minutes.

What do you do?

Option A: Accept the order, fail to deliver, disappoint 500 people, and destroy your reputation.

Option B: Politely say "Sorry, we can only handle 100 pizzas per hour. We can deliver 100 now and the rest over the next 4 hours."

This is exactly what rate limiting does for your API.

In this comprehensive guide, you'll learn:

What rate limiting is and why you need it
Different rate limiting algorithms (Token Bucket, Leaky Bucket, Fixed Window, Sliding Window)
How to implement rate limiting in Node.js, Python, and Go
What happens when limits are exceeded
Best practices and real-world examples
Common pitfalls and how to avoid them

What is Rate Limiting?
Why Rate Limiting Matters
Rate Limiting Algorithms Explained
Implementation Examples
What Happens When Limit is Exceeded
Rate Limiting Strategies
Best Practices
Common Pitfalls
Real-World Examples
Tools and Libraries

What is Rate Limiting?

Rate limiting is a technique to control the number of requests a user or client can make to your API or service within a specific time window.

The Simple Definition

Rate limiting = Setting a maximum number of requests allowed in a given time period

Examples:

Twitter API: 300 requests per 15-minute window
GitHub API: 5,000 requests per hour for authenticated users
Stripe API: 100 requests per second
Google Maps API: 10 requests per second per user

The Mental Model

Think of rate limiting as a speed limit on a highway:

Without Rate Limiting:
User → [API] → Database
User → [API] → Database
User → [API] → Database (repeated 1 million times)
Result: Server crashes 💥

With Rate Limiting:
User → [Rate Limiter] → [API] → Database (100 times)
User → [Rate Limiter] ❌ "Too many requests, try again later"
Result: Server stays healthy ✅

Why Rate Limiting Matters

1. Prevent API Abuse

Scenario: DDoS Attack

Attacker sends 100,000 requests per second
↓
Without Rate Limiting: Your server dies
With Rate Limiting: Only 100 requests/sec allowed, rest blocked

2. Ensure Fair Usage

Scenario: One User Hogging Resources

User A: Makes 1 request
User B: Makes 10,000 requests (bot scraping your data)
User A: Experiences slow response times

With Rate Limiting:
User B: Limited to 100 requests/hour
User A: Gets normal performance

3. Control Costs

Scenario: Cloud Bills

Each API call costs money (database queries, third-party APIs, compute)

Without Limits:
- Malicious bot makes 1 million requests
- Your AWS bill: $10,000 this month

With Limits:
- Bot limited to 1,000 requests/hour
- Your AWS bill: $50 this month

4. Protect Downstream Services

Scenario: Database Overload

Your API → Database (max 1,000 connections)

10,000 concurrent requests arrive
↓
Without Rate Limiting: Database crashes
With Rate Limiting: Only 1,000 requests pass through

5. Maintain Quality of Service

Scenario: Server Capacity

Your server can handle 500 requests/second comfortably
At 1,000 requests/second, it starts timing out

Rate Limiting:
- Set limit to 500 requests/second
- Everyone gets fast responses
- No timeouts or errors

Rate Limiting Algorithms Explained

There are four main algorithms. Let's understand each one with visual examples.

1. Fixed Window Counter (Simplest)

How it works:

Time divided into fixed windows (e.g., every 1 minute)
Count requests in current window
Reset counter at window boundary

Example: Limit = 5 requests per minute

Minute 1 (00:00 - 01:00):
Request 1: ✅ (count: 1)
Request 2: ✅ (count: 2)
Request 3: ✅ (count: 3)
Request 4: ✅ (count: 4)
Request 5: ✅ (count: 5)
Request 6: ❌ "Rate limit exceeded"
Request 7: ❌ "Rate limit exceeded"

Minute 2 (01:00 - 02:00):
Counter resets to 0
Request 8: ✅ (count: 1)

Visual Representation:

Limit: 5 requests/minute

Time:  00:00                    01:00                    02:00
       |------------------------|------------------------|
Window 1                       Window 2
Requests: 1,2,3,4,5 (6,7 blocked)    Resets, allows 5 more

Pros:

✅ Simple to implement
✅ Memory efficient
✅ Easy to understand

Cons:

❌ Boundary problem: Burst of requests at window edges

The Boundary Problem:

Limit: 5 requests/minute

00:59:50 → User makes 5 requests (all allowed)
01:00:00 → Window resets
01:00:01 → User makes 5 more requests (all allowed)

Result: User made 10 requests in 11 seconds!
This is double the intended rate.

Implementation:

class FixedWindowRateLimiter {
  constructor(limit, windowMs) {
    this.limit = limit;           // Max requests
    this.windowMs = windowMs;     // Time window in milliseconds
    this.requests = new Map();    // Store request counts
  }

  async isAllowed(userId) {
    const now = Date.now();
    const windowStart = Math.floor(now / this.windowMs) * this.windowMs;

    const key = `${userId}:${windowStart}`;
    const count = this.requests.get(key) || 0;

    if (count >= this.limit) {
      return false;  // Rate limit exceeded
    }

    this.requests.set(key, count + 1);
    return true;
  }
}

// Usage
const limiter = new FixedWindowRateLimiter(5, 60000); // 5 requests per minute

const allowed = await limiter.isAllowed('user123');
if (allowed) {
  // Process request
} else {
  // Reject with 429 Too Many Requests
}

2. Sliding Window Log (Most Accurate)

How it works:

Keep a log of all request timestamps
For each new request, remove timestamps older than the window
Count remaining timestamps
Allow if count < limit

Visual Representation:

Limit: 3 requests per minute
Current time: 01:00:30

Request Log:
[00:59:45] ← Still within 1-minute window (45 seconds ago)
[01:00:10] ← Within window (20 seconds ago)
[01:00:25] ← Within window (5 seconds ago)

New request at 01:00:30:
- Count requests in last 60 seconds: 3
- Limit: 3
- Result: ❌ Blocked (at limit)

New request at 01:00:46:
- [00:59:45] is now older than 60 seconds, remove it
- Count: 2
- Result: ✅ Allowed

Timeline Visualization:

Time:     00:59:45   01:00:10   01:00:25   01:00:30 (current)
          |----------|----------|----------|----------|
          ✓          ✓          ✓          ?

<----- 60 second window ---->

Requests in window: 3
Limit: 3
New request: ❌ Blocked

Pros:

✅ Most accurate
✅ No boundary problem
✅ True sliding window

Cons:

❌ Memory intensive (stores all timestamps)
❌ Slower (must scan all timestamps)

Implementation:

class SlidingWindowLogRateLimiter {
  constructor(limit, windowMs) {
    this.limit = limit;
    this.windowMs = windowMs;
    this.logs = new Map();  // userId → array of timestamps
  }

  async isAllowed(userId) {
    const now = Date.now();
    const windowStart = now - this.windowMs;

    // Get user's request log
    let userLog = this.logs.get(userId) || [];

    // Remove timestamps older than window
    userLog = userLog.filter(timestamp => timestamp > windowStart);

    // Check if limit exceeded
    if (userLog.length >= this.limit) {
      return false;
    }

    // Add current request timestamp
    userLog.push(now);
    this.logs.set(userId, userLog);

    return true;
  }
}

// Usage
const limiter = new SlidingWindowLogRateLimiter(5, 60000);

const allowed = await limiter.isAllowed('user123');

3. Sliding Window Counter (Balanced Approach)

How it works:

Combines Fixed Window simplicity with Sliding Window accuracy.

Formula:

Allowed requests = (requests in previous window × overlap percentage) 
                   + (requests in current window)

Visual Example:

Limit: 10 requests/minute
Current time: 01:00:40 (40 seconds into current minute)

Previous window (00:00-01:00): 8 requests
Current window (01:00-02:00): 5 requests so far

Calculate overlap:
- We're 40 seconds into current window (40/60 = 66.6%)
- So we use 33.3% of previous window (remaining time)

Weighted count = (8 × 0.333) + 5 = 2.67 + 5 = 7.67 ≈ 8

Is 8 < 10? Yes ✅ Allow request

Timeline Visualization:

         Previous Window          Current Window
         00:00 ─────── 01:00      01:00 ─────── 02:00
              8 requests                5 requests
         |<────────────────>|<───>|<────────────>|
                            ↑ overlap  ↑
                            33.3%      current time (01:00:40)

Pros:

✅ More accurate than Fixed Window
✅ More memory efficient than Sliding Log
✅ Good compromise

Cons:

❌ Slightly more complex
❌ Not perfectly accurate

Implementation:

class SlidingWindowCounterRateLimiter {
  constructor(limit, windowMs) {
    this.limit = limit;
    this.windowMs = windowMs;
    this.windows = new Map();  // userId → {previousCount, currentCount, currentWindowStart}
  }

  async isAllowed(userId) {
    const now = Date.now();
    const currentWindowStart = Math.floor(now / this.windowMs) * this.windowMs;
    const previousWindowStart = currentWindowStart - this.windowMs;

    let userData = this.windows.get(userId) || {
      previousCount: 0,
      currentCount: 0,
      currentWindowStart: currentWindowStart
    };

    // If we're in a new window, rotate the counts
    if (userData.currentWindowStart < currentWindowStart) {
      userData.previousCount = userData.currentCount;
      userData.currentCount = 0;
      userData.currentWindowStart = currentWindowStart;
    }

    // Calculate how far into the current window we are
    const timeIntoWindow = now - currentWindowStart;
    const percentageIntoWindow = timeIntoWindow / this.windowMs;

    // Calculate weighted count
    const weightedCount = 
      (userData.previousCount * (1 - percentageIntoWindow)) + 
      userData.currentCount;

    // Check limit
    if (weightedCount >= this.limit) {
      return false;
    }

    // Increment current window count
    userData.currentCount++;
    this.windows.set(userId, userData);

    return true;
  }
}

// Usage
const limiter = new SlidingWindowCounterRateLimiter(10, 60000);

4. Token Bucket (Industry Standard)

How it works:

Imagine a bucket that holds tokens. Tokens are added at a constant rate. Each request consumes a token.

Bucket Capacity: 10 tokens
Refill Rate: 1 token per second

Initial state: Bucket has 10 tokens
|🪙🪙🪙🪙🪙🪙🪙🪙🪙🪙| ← Full bucket

Request 1: ✅ (9 tokens left)
|🪙🪙🪙🪙🪙🪙🪙🪙🪙  |

Request 2: ✅ (8 tokens left)
|🪙🪙🪙🪙🪙🪙🪙🪙    |

... 10 rapid requests ...

|                  | ← Empty bucket

Request 11: ❌ "No tokens available"

Wait 1 second...
Bucket refills: +1 token
|🪙                |

Request 12: ✅ (0 tokens left)

Key Properties:

Bucket capacity = Maximum burst size
Refill rate = Sustained rate limit
Allows bursts = Can use all tokens at once, then wait for refill

Example:

Capacity: 100 tokens
Refill: 10 tokens/second

Scenario 1: Steady traffic
- User makes 10 requests/second
- Tokens refill at 10/second
- Result: Smooth operation ✅

Scenario 2: Burst traffic
- User makes 100 requests instantly (uses all tokens)
- Then waits 10 seconds for refill
- Makes 100 more requests
- Result: Allowed, but forced to wait ✅

Scenario 3: Excessive traffic
- User makes 100 requests (bucket empty)
- Immediately tries 100 more
- Result: 100 blocked until tokens refill ❌

Pros:

✅ Allows bursts (flexible)
✅ Memory efficient
✅ Industry standard
✅ Smooth long-term rate

Cons:

❌ Can allow sudden bursts
❌ Slightly complex to understand

Implementation:

class TokenBucketRateLimiter {
  constructor(capacity, refillRate) {
    this.capacity = capacity;        // Max tokens in bucket
    this.refillRate = refillRate;    // Tokens added per second
    this.buckets = new Map();         // userId → {tokens, lastRefill}
  }

  async isAllowed(userId, tokensRequired = 1) {
    const now = Date.now();

    let bucket = this.buckets.get(userId) || {
      tokens: this.capacity,
      lastRefill: now
    };

    // Calculate tokens to add since last refill
    const timePassed = (now - bucket.lastRefill) / 1000; // Convert to seconds
    const tokensToAdd = timePassed * this.refillRate;

    // Refill bucket (cap at capacity)
    bucket.tokens = Math.min(this.capacity, bucket.tokens + tokensToAdd);
    bucket.lastRefill = now;

    // Check if enough tokens
    if (bucket.tokens >= tokensRequired) {
      bucket.tokens -= tokensRequired;
      this.buckets.set(userId, bucket);
      return true;
    }

    // Not enough tokens
    this.buckets.set(userId, bucket);
    return false;
  }

  // Helper: Get time until next token
  getTimeUntilNextToken(userId) {
    const bucket = this.buckets.get(userId);
    if (!bucket || bucket.tokens >= 1) return 0;

    const tokensNeeded = 1 - bucket.tokens;
    const timeMs = (tokensNeeded / this.refillRate) * 1000;
    return Math.ceil(timeMs / 1000); // Return seconds
  }
}

// Usage
const limiter = new TokenBucketRateLimiter(100, 10); // 100 tokens, refill 10/sec

const allowed = await limiter.isAllowed('user123', 1);
if (!allowed) {
  const retryAfter = limiter.getTimeUntilNextToken('user123');
  console.log(`Try again in ${retryAfter} seconds`);
}

5. Leaky Bucket (Constant Output Rate)

How it works:

Requests enter a queue (bucket). They "leak" out at a constant rate.

Think of it like water dripping from a bucket with a hole:

Requests flow in (variable rate)
        ↓
    [========]  ← Bucket (queue)
        ↓↓↓
    Leak out (constant rate)
        ↓
    Processed

Visual Example:

Capacity: 5 requests
Leak rate: 1 request per second

Time 0s: 3 requests arrive
Bucket: [R1][R2][R3][  ][  ]

Time 1s: R1 processed, 2 more arrive
Bucket: [R2][R3][R4][R5][  ]

Time 2s: R2 processed, 3 more arrive
Bucket: [R3][R4][R5][R6][R7] ← FULL
New requests: ❌ Rejected (bucket full)

Time 3s: R3 processed
Bucket: [R4][R5][R6][R7][  ]

Key Difference from Token Bucket:

Token Bucket: Allows bursts, then throttles
- Can process 100 requests instantly (if tokens available)

Leaky Bucket: Constant output rate
- Always processes exactly 1 request/second, no bursts

Pros:

✅ Constant, predictable output
✅ Smooths out bursts
✅ Protects downstream systems

Cons:

❌ No burst allowance
❌ Increased latency (requests queued)

Implementation:

class LeakyBucketRateLimiter {
  constructor(capacity, leakRate) {
    this.capacity = capacity;      // Max queue size
    this.leakRate = leakRate;      // Requests processed per second
    this.buckets = new Map();       // userId → queue
  }

  async isAllowed(userId) {
    let queue = this.buckets.get(userId) || [];

    // Process (leak) requests based on time passed
    const now = Date.now();
    const leakInterval = 1000 / this.leakRate;

    // Remove processed requests
    while (queue.length > 0) {
      const oldestRequest = queue[0];
      const timePassed = now - oldestRequest;

      if (timePassed >= leakInterval) {
        queue.shift(); // Remove processed request
      } else {
        break;
      }
    }

    // Check capacity
    if (queue.length >= this.capacity) {
      return false; // Bucket full
    }

    // Add new request to queue
    queue.push(now);
    this.buckets.set(userId, queue);

    return true;
  }
}

// Usage
const limiter = new LeakyBucketRateLimiter(10, 2); // Queue 10, process 2/sec

Algorithm Comparison Table

Algorithm	Accuracy	Memory	Complexity	Burst Allowed	Best For
Fixed Window	Low	Low	Simple	Yes (at boundaries)	Simple APIs, analytics
Sliding Log	High	High	Medium	No	Critical APIs, billing
Sliding Counter	Medium	Low	Medium	Somewhat	General APIs
Token Bucket	High	Low	Medium	Yes (controlled)	Most APIs (industry standard)
Leaky Bucket	High	Medium	Medium	No	Stream processing, queues

Which to Choose?

Need simplicity? → Fixed Window
Need accuracy? → Sliding Log
Need balance? → Sliding Counter
Need industry standard? → Token Bucket (recommended)
Need constant output? → Leaky Bucket

Implementation Examples

Node.js with Express

Using express-rate-limit (Simple)

const express = require('express');
const rateLimit = require('express-rate-limit');

const app = express();

// Apply rate limiting to all requests
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000,  // 15 minutes
  max: 100,                   // Limit each IP to 100 requests per windowMs
  message: 'Too many requests from this IP, please try again later.',
  standardHeaders: true,      // Return rate limit info in `RateLimit-*` headers
  legacyHeaders: false,       // Disable `X-RateLimit-*` headers
});

app.use(limiter);

// Or apply to specific routes
const createAccountLimiter = rateLimit({
  windowMs: 60 * 60 * 1000,   // 1 hour
  max: 5,                      // 5 accounts per hour
  message: 'Too many accounts created from this IP',
  skipSuccessfulRequests: true // Don't count successful requests
});

app.post('/api/create-account', createAccountLimiter, (req, res) => {
  // Create account logic
  res.json({ success: true });
});

app.listen(3000);

Using Redis (Production-Ready)

const express = require('express');
const rateLimit = require('express-rate-limit');
const RedisStore = require('rate-limit-redis');
const Redis = require('ioredis');

const app = express();
const redis = new Redis({
  host: process.env.REDIS_HOST,
  port: process.env.REDIS_PORT
});

// Production rate limiter with Redis
const limiter = rateLimit({
  store: new RedisStore({
    client: redis,
    prefix: 'rate_limit:',
  }),
  windowMs: 15 * 60 * 1000,
  max: 100,
  message: 'Too many requests',
  handler: (req, res) => {
    res.status(429).json({
      error: 'Too many requests',
      retryAfter: req.rateLimit.resetTime
    });
  },
  // Custom key generator (default is IP)
  keyGenerator: (req) => {
    // Rate limit by user ID if authenticated
    return req.user?.id || req.ip;
  }
});

app.use('/api/', limiter);

app.listen(3000);

Python with Flask

from flask import Flask, request, jsonify
from flask_limiter import Limiter
from flask_limiter.util import get_remote_address
import redis

app = Flask(__name__)

# Simple in-memory rate limiting
limiter = Limiter(
    app=app,
    key_func=get_remote_address,
    default_limits=["100 per hour", "20 per minute"]
)

# With Redis storage
redis_client = redis.Redis(host='localhost', port=6379, db=0)
limiter = Limiter(
    app=app,
    key_func=get_remote_address,
    storage_uri="redis://localhost:6379"
)

# Apply to all routes
@app.route('/api/data')
@limiter.limit("10 per minute")
def get_data():
    return jsonify({"data": "Success!"})

# Different limits for different routes
@app.route('/api/expensive')
@limiter.limit("1 per minute")
def expensive_operation():
    return jsonify({"result": "Done"})

# Custom key function (by user ID)
def get_user_id():
    return request.headers.get('X-User-ID', get_remote_address())

@app.route('/api/user-specific')
@limiter.limit("50 per hour", key_func=get_user_id)
def user_specific():
    return jsonify({"data": "Success!"})

# Handle rate limit exceeded
@app.errorhandler(429)
def ratelimit_handler(e):
    return jsonify({
        "error": "Rate limit exceeded",
        "message": str(e.description)
    }), 429

if __name__ == '__main__':
    app.run(debug=True)

What Happens When Rate Limit is Exceeded?

1. HTTP Response

Standard Response: 429 Too Many Requests

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705334400

{
  "error": "Too many requests",
  "message": "You have exceeded the rate limit of 100 requests per hour",
  "retryAfter": 60
}

Response Headers Explained:

Status Code: 429 - Standard HTTP code for rate limiting
Retry-After: Seconds to wait before retrying
X-RateLimit-Limit: Maximum requests allowed
X-RateLimit-Remaining: Requests left in current window
X-RateLimit-Reset: Unix timestamp when limit resets

2. Client Behavior

Good Client (Respects Rate Limits):

async function fetchWithRateLimit(url) {
  const response = await fetch(url);

  if (response.status === 429) {
    const retryAfter = response.headers.get('Retry-After');
    console.log(`Rate limited. Retrying after ${retryAfter} seconds`);

    // Wait and retry
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return fetchWithRateLimit(url); // Retry
  }

  return response.json();
}

Bad Client (Ignores Rate Limits):

// ❌ DON'T DO THIS
async function badClient(url) {
  let response = await fetch(url);

  if (response.status === 429) {
    // Immediately retry - making it worse!
    return badClient(url);
  }

  return response.json();
}

// This creates a retry loop that hammers the server even more

3. Different Strategies for Handling Exceeded Limits

Strategy 1: Reject Immediately (Most Common)

if (!await rateLimiter.isAllowed(userId)) {
  return res.status(429).json({
    error: 'Rate limit exceeded',
    retryAfter: 60
  });
}

// Process request

Pros: Simple, clear feedback to client

Cons: Request completely rejected

Strategy 2: Queue the Request

if (!await rateLimiter.isAllowed(userId)) {
  // Add to queue instead of rejecting
  await requestQueue.add({
    userId,
    requestData: req.body,
    timestamp: Date.now()
  });

  return res.status(202).json({
    message: 'Request queued due to rate limiting',
    estimatedProcessingTime: 30
  });
}

Pros: Request eventually processed

Cons: Increased latency, queue management complexity

Strategy 3: Tiered Response (Degraded Service)

const limit = await rateLimiter.getLimit(userId);

if (limit.exceeded) {
  // Return cached/degraded response instead of rejecting
  return res.json({
    data: await cache.get(`stale_data:${userId}`),
    notice: 'Serving cached data due to rate limit'
  });
}

// Return fresh data
const freshData = await database.query();
await cache.set(`stale_data:${userId}`, freshData);
return res.json({ data: freshData });

Pros: Some service better than none

Cons: Potentially stale data

Strategy 4: Exponential Backoff (For Internal Services)

async function callWithBackoff(url, maxRetries = 5) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url);

    if (response.status === 429) {
      const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s, 8s, 16s
      console.log(`Rate limited. Waiting ${delay}ms before retry ${i + 1}`);
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    return response;
  }

  throw new Error('Max retries exceeded');
}

Pros: Automatically handles rate limits

Cons: Increased latency

Rate Limiting Strategies

1. Per-User Rate Limiting

Best for: Public APIs with authenticated users

// Key by user ID
const key = req.user.id;
const allowed = await rateLimiter.isAllowed(key);

Example:

User A: 100 requests/hour
User B: 100 requests/hour
User C: 100 requests/hour

Each user gets their own quota.

2. Per-IP Rate Limiting

Best for: Public endpoints, DDoS protection

// Key by IP address
const key = req.ip;
const allowed = await rateLimiter.isAllowed(key);

Example:

IP 192.168.1.1: 100 requests/hour
IP 192.168.1.2: 100 requests/hour

Caveat: NAT issues - many users behind same IP

3. Per-API-Key Rate Limiting

Best for: B2B APIs, paid tiers

// Key by API key
const key = req.headers['x-api-key'];
const allowed = await rateLimiter.isAllowed(key);

Example:

Free tier: 100 requests/hour
Pro tier: 1,000 requests/hour
Enterprise: Unlimited

4. Global Rate Limiting

Best for: Protecting server capacity

// Single key for all users
const key = 'global';
const allowed = await rateLimiter.isAllowed(key);

Example:

All users combined: Max 10,000 requests/second
Prevents server overload

5. Tiered Rate Limiting

Best for: SaaS products, monetization

function getRateLimit(user) {
  switch (user.plan) {
    case 'free':
      return { limit: 100, window: 3600000 };  // 100/hour
    case 'pro':
      return { limit: 1000, window: 3600000 }; // 1000/hour
    case 'enterprise':
      return { limit: 10000, window: 3600000 }; // 10000/hour
    default:
      return { limit: 10, window: 3600000 };   // 10/hour (anonymous)
  }
}

const limits = getRateLimit(req.user);
const limiter = new TokenBucketRateLimiter(limits.limit, limits.window);

6. Endpoint-Specific Rate Limiting

Best for: Protecting expensive operations

// Different limits for different endpoints
app.get('/api/search', rateLimit({ max: 10, windowMs: 60000 })); // 10/min
app.get('/api/list', rateLimit({ max: 100, windowMs: 60000 }));   // 100/min
app.post('/api/upload', rateLimit({ max: 5, windowMs: 3600000 })); // 5/hour

7. Burst vs Sustained Rate

Best for: Handling traffic spikes

const limiter = new TokenBucketRateLimiter(
  100,  // Burst: 100 requests instantly
  10    // Sustained: 10 requests/second
);

// User can:
// - Make 100 requests instantly (burst)
// - Then limited to 10/second (sustained)

Best Practices

1. Return Proper Headers

res.set({
  'X-RateLimit-Limit': limit.total,
  'X-RateLimit-Remaining': limit.remaining,
  'X-RateLimit-Reset': limit.resetTime,
  'Retry-After': limit.retryAfter
});

2. Use Redis for Distributed Systems

// ❌ BAD: In-memory storage
const limiter = new Map(); // Doesn't work across multiple servers

// ✅ GOOD: Redis storage
const redis = new Redis();
const limiter = new RedisStore(redis);

Why Redis?

Shared state across multiple servers
Fast atomic operations
Built-in expiration
Persistence

3. Whitelist Critical IPs

const WHITELISTED_IPS = ['10.0.0.1', '10.0.0.2'];

function rateLimitMiddleware(req, res, next) {
  if (WHITELISTED_IPS.includes(req.ip)) {
    return next(); // Skip rate limiting
  }

  // Apply rate limiting for others
  const allowed = await rateLimiter.isAllowed(req.ip);
  if (!allowed) {
    return res.status(429).json({ error: 'Rate limit exceeded' });
  }

  next();
}

4. Monitor Rate Limit Metrics

// Track rate limit hits
const metrics = {
  totalRequests: 0,
  rateLimitedRequests: 0,
  topOffenders: new Map()
};

async function rateLimitMiddleware(req, res, next) {
  metrics.totalRequests++;

  const allowed = await rateLimiter.isAllowed(req.user.id);

  if (!allowed) {
    metrics.rateLimitedRequests++;

    // Track top offenders
    const count = metrics.topOffenders.get(req.user.id) || 0;
    metrics.topOffenders.set(req.user.id, count + 1);

    return res.status(429).json({ error: 'Rate limit exceeded' });
  }

  next();
}

// Expose metrics endpoint
app.get('/metrics', (req, res) => {
  res.json({
    totalRequests: metrics.totalRequests,
    rateLimited: metrics.rateLimitedRequests,
    rateLimitPercentage: (metrics.rateLimitedRequests / metrics.totalRequests) * 100,
    topOffenders: Array.from(metrics.topOffenders.entries())
      .sort((a, b) => b[1] - a[1])
      .slice(0, 10)
  });
});

5. Graceful Degradation

try {
  const allowed = await rateLimiter.isAllowed(userId);
  if (!allowed) {
    return res.status(429).json({ error: 'Rate limit exceeded' });
  }
} catch (error) {
  // Rate limiter failed (Redis down?)
  console.error('Rate limiter error:', error);

  // OPTION A: Fail open (allow request)
  console.warn('Allowing request due to rate limiter failure');

  // OPTION B: Fail closed (reject request)
  // return res.status(503).json({ error: 'Service temporarily unavailable' });
}

6. Document Your Rate Limits

/**
 * API Rate Limits:
 * 
 * Anonymous: 10 requests/hour
 * Free tier: 100 requests/hour
 * Pro tier: 1,000 requests/hour
 * Enterprise: 10,000 requests/hour
 * 
 * Endpoints with special limits:
 * - POST /api/upload: 5 requests/hour (all tiers)
 * - GET /api/search: 10 requests/minute (all tiers)
 */

// Add to API documentation
app.get('/api/limits', (req, res) => {
  const userLimits = getRateLimits(req.user);
  res.json({
    hourly: userLimits.hourly,
    perMinute: userLimits.perMinute,
    burst: userLimits.burst,
    specialEndpoints: {
      '/api/upload': '5 requests/hour',
      '/api/search': '10 requests/minute'
    }
  });
});

7. Use Different Keys for Different Resources

// Separate rate limits for different operations
const readLimiter = new TokenBucket(1000, 100);  // 1000 burst, 100/sec
const writeLimiter = new TokenBucket(100, 10);   // 100 burst, 10/sec

app.get('/api/data', async (req, res) => {
  const key = `read:${req.user.id}`;
  if (!await readLimiter.isAllowed(key)) {
    return res.status(429).json({ error: 'Read rate limit exceeded' });
  }
  // Handle read
});

app.post('/api/data', async (req, res) => {
  const key = `write:${req.user.id}`;
  if (!await writeLimiter.isAllowed(key)) {
    return res.status(429).json({ error: 'Write rate limit exceeded' });
  }
  // Handle write
});

Common Pitfalls

Pitfall #1: Not Handling Distributed Systems

Problem:

// ❌ Each server has its own rate limiter
const limiter = new Map(); // In-memory

// User makes 100 requests to Server A: OK
// User makes 100 requests to Server B: OK
// Total: 200 requests (should have been blocked at 100)

Solution:

// ✅ Use shared Redis store
const redis = new Redis();
const limiter = new RedisStore(redis);

Pitfall #2: Not Accounting for Clock Skew

Problem:

// Server A time: 12:00:00
// Server B time: 12:00:30 (30 seconds fast)
// Can cause inconsistent rate limiting

Solution:

// Use Redis time instead of server time
const now = await redis.time(); // Redis timestamp

Pitfall #3: Rate Limiting Internal Services

Problem:

// ❌ Frontend → Rate Limiter → Backend
//   Backend → Rate Limiter → Database
// Both limited - backend can't serve frontend!

Solution:

// ✅ Whitelist internal services
const INTERNAL_SERVICES = ['backend-service', 'worker-service'];

if (INTERNAL_SERVICES.includes(req.headers['x-service-name'])) {
  return next(); // Skip rate limiting
}

Pitfall #4: Not Considering NAT/Proxies

Problem:

// ❌ Rate limit by IP
// 1000 users behind corporate proxy → same IP → all blocked

Solution:

// ✅ Rate limit by authenticated user ID
const key = req.user?.id || req.ip;

// Or use X-Forwarded-For (with caution)
const ip = req.headers['x-forwarded-for']?.split(',')[0] || req.ip;

Pitfall #5: Too Aggressive Limits

Problem:

// ❌ 1 request per minute - too strict!
// User refreshes page → rate limited

Solution:

// ✅ Start lenient, tighten based on monitoring
// Initial: 100 requests/minute
// If abuse detected: Reduce to 50 requests/minute for that user

Pitfall #6: No Burst Allowance

Problem:

// ❌ User opens page with 20 images
// Loads 1 image/second → takes 20 seconds

Solution:

// ✅ Use Token Bucket with burst
const limiter = new TokenBucket(50, 10); // 50 burst, 10/sec sustained
// Page loads instantly, then throttled for additional requests

Real-World Examples

GitHub API

Authenticated: 5,000 requests/hour
Unauthenticated: 60 requests/hour

Headers:
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
X-RateLimit-Reset: 1705334400
X-RateLimit-Used: 1

Twitter API v2

Essential (Free): 500,000 tweets/month
Elevated: 2,000,000 tweets/month

Rate limits per endpoint:
- GET /tweets: 900 requests/15-min
- POST /tweets: 200 requests/15-min

Stripe API

100 read requests/second
100 write requests/second

Returns headers:
Stripe-RateLimit-Limit: 100
Stripe-RateLimit-Remaining: 99
Stripe-RateLimit-Reset: 1705334460

OpenAI API

GPT-4: 10,000 tokens/minute (TPM)
GPT-3.5: 90,000 tokens/minute

Rate limits by:
- Requests per minute (RPM)
- Tokens per minute (TPM)
- Tokens per day (TPD)

Tools and Libraries

Node.js

express-rate-limit: Simple rate limiting middleware
rate-limiter-flexible: Advanced, supports multiple algorithms
bottleneck: Job scheduler with rate limiting
ioredis: Redis client for distributed rate limiting

Python

Flask-Limiter: Flask rate limiting
django-ratelimit: Django rate limiting
slowapi: FastAPI rate limiting
redis-py: Redis client

Go

ulule/limiter: HTTP rate limiter
golang.org/x/time/rate: Token bucket implementation
throttled: HTTP rate limiting middleware

Infrastructure

Nginx: Built-in rate limiting
Kong: API gateway with rate limiting
AWS API Gateway: Managed rate limiting
Cloudflare: DDoS protection and rate limiting

Conclusion

Key Takeaways

Rate limiting is essential - Protects your API from abuse and overload
Choose the right algorithm - Token Bucket for most cases, Sliding Log for accuracy
Use Redis in production - Distributed systems need shared state
Return proper headers - Help clients understand and respect limits
Monitor and adjust - Watch metrics, tune limits based on usage
Document clearly - Tell users what limits they have
Graceful degradation - Handle rate limiter failures

The Mental Model

Rate Limiting = Speed Limit for APIs

Too fast? → Slow down (429 response)
Respect limits? → Smooth sailing (200 response)

Next Steps

Implement basic rate limiting in your current project
Monitor rate limit hits to understand usage patterns
Tune limits based on actual traffic
Add tiered limits for different user types
Document your rate limits for API consumers

Final Thought

Rate limiting isn't just about saying "no" to users—it's about ensuring fair, reliable, and sustainable service for everyone.

Implement it thoughtfully, monitor it carefully, and adjust it based on real-world usage. Your API (and your users) will thank you.

Questions or Feedback?

Have questions about implementing rate limiting? Want to share your approach? Drop a comment below!

Topics you'd like to see covered:

Advanced rate limiting patterns?
Rate limiting in microservices?
Handling rate limits as a client?
Building a custom rate limiting service?

Let me know! 🚀

This comprehensive guide covers everything you need to know about rate limiting. If you found it helpful, consider sharing it with other developers who might benefit from it!

The DevOps Guide to Managing Multiple Environments: One App, Many Faces

Niraj Maharjan — Thu, 15 Jan 2026 04:34:27 +0000

The Core Problem Every Developer Faces

Imagine this: You've built an amazing application. It works perfectly on your laptop. You push it to staging, and suddenly it breaks. You fix it, deploy to production, and... different error. Sound familiar?

Here's the truth: The same application behaves differently across environments—and that's not a bug, it's by design.

This article will teach you how professional DevOps teams manage the same codebase across development, staging, and production environments without changing a single line of code.

The Big Picture (In One Sentence)

Same application, different environments, different configurations—managed through environment variables, Docker Compose files, and CI/CD stages.

That's it. Now let's unpack it properly.

Understanding Environments
The Golden Rule: Never Change Code
The Three Pillars of Environment Management
Environment Variables Deep Dive
Docker Compose for Different Environments
CI/CD Pipeline Configuration
Real-World Example: E-commerce Application
Common Pitfalls and How to Avoid Them
Best Practices Checklist

Understanding Environments

Before we dive into solutions, let's understand what we're dealing with.

What Are Environments?

An environment is a complete setup where your application runs. Think of it as a stage in your application's journey from your laptop to serving real users.

The Three Main Environments

[Development] → [Staging] → [Production]
    (Dev)          (QA)         (Prod)

1. Development Environment (Local/Dev)

Where: Your laptop or development server
Purpose: Write code, test features, break things freely
Users: Developers only
Data: Fake data, test users
Example config:
- Database: localhost:5432
- Debug mode: enabled
- Email: Mock service (no real emails sent)
- Payment: Sandbox/test mode

2. Staging Environment (QA/Pre-Production)

Where: Server that mirrors production
Purpose: Test before releasing to real users
Users: QA team, product managers, stakeholders
Data: Sanitized production-like data
Example config:
- Database: staging-db.company.com
- Debug mode: enabled (with logging)
- Email: Real service, but to test addresses only
- Payment: Test mode with real payment processor

3. Production Environment (Live/Prod)

Where: Live servers accessible to users
Purpose: Serve real users
Users: Everyone (customers, clients)
Data: Real, sensitive data
Example config:
- Database: prod-db.company.com (high availability, replicas)
- Debug mode: disabled
- Email: Real service, to real users
- Payment: Live mode with real transactions

Why Can't We Use the Same Configuration Everywhere?

Simple answer: Because the needs are different.

Aspect	Development	Staging	Production
Performance	Can be slow	Should be fast	Must be fast
Security	Relaxed	Medium	Maximum
Data	Fake	Test	Real
Errors	Show full stack traces	Show some details	Hide details
Monitoring	Minimal	Moderate	Comprehensive
Cost	Minimal resources	Moderate resources	Auto-scaling, high availability

The Golden Rule: Never Change Code

Here's the most important principle in DevOps:

We do NOT change application code between environments.

What We DO Change:

✅ Environment variables (.env files)
✅ Docker Compose files (different services, volumes, networks)
✅ CI/CD pipeline stages (different deployment strategies)

What We DON'T Change:

❌ Application logic
❌ Business rules
❌ Core functionality
❌ Source code

Why This Rule Matters

Example of doing it WRONG:

// ❌ BAD: Hardcoding environment-specific logic
if (environment === 'production') {
  const dbHost = 'prod-db.company.com';
} else if (environment === 'staging') {
  const dbHost = 'staging-db.company.com';
} else {
  const dbHost = 'localhost';
}

Problems with this approach:

Code becomes a mess of if/else statements
Adding a new environment requires code changes
Easy to make mistakes and deploy wrong config
Violates the principle of configuration externalization

Example of doing it RIGHT:

// ✅ GOOD: Read from environment variables
const dbHost = process.env.DB_HOST || 'localhost';
const dbPort = process.env.DB_PORT || 5432;
const dbName = process.env.DB_NAME || 'myapp_dev';

Then use different .env files:

# .env.development
DB_HOST=localhost
DB_PORT=5432
DB_NAME=myapp_dev

# .env.staging
DB_HOST=staging-db.company.com
DB_PORT=5432
DB_NAME=myapp_staging

# .env.production
DB_HOST=prod-db.company.com
DB_PORT=5432
DB_NAME=myapp_prod

The Three Pillars of Environment Management

Let's explore the three mechanisms that make environment management possible.

1. Environment Variables (The Foundation)

What Are Environment Variables?

Environment variables are key-value pairs that configure your application's behavior without changing code.

Think of them as settings or preferences for your application.

Anatomy of an Environment Variable

# Format: KEY=VALUE
DATABASE_URL=postgresql://user:password@host:5432/dbname

KEY: The variable name (usually UPPERCASE_WITH_UNDERSCORES)
VALUE: The configuration value (can be string, number, URL, etc.)

What Environment Variables Control

Environment variables control behavior, not logic.

┌─────────────────────────────────────────┐
│   What Env Vars Control                 │
├─────────────────────────────────────────┤
│ ✅ Which database to connect to         │
│ ✅ API keys and secrets                 │
│ ✅ Feature flags (enable/disable)       │
│ ✅ Debug mode on/off                    │
│ ✅ Third-party service URLs             │
│ ✅ Timeouts and retry limits            │
│ ✅ Cache settings                        │
│ ✅ Logging levels                        │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│   What Env Vars DON'T Control           │
├─────────────────────────────────────────┤
│ ❌ How your authentication works         │
│ ❌ Business logic rules                  │
│ ❌ Algorithm implementations             │
│ ❌ User interface behavior               │
└─────────────────────────────────────────┘

Real-World Example: E-commerce App

# .env.development
NODE_ENV=development
PORT=3000

# Database
DB_HOST=localhost
DB_PORT=5432
DB_NAME=ecommerce_dev
DB_USER=dev_user
DB_PASSWORD=dev_password

# Redis Cache
REDIS_HOST=localhost
REDIS_PORT=6379

# Payment Gateway
STRIPE_API_KEY=sk_test_123456789
STRIPE_WEBHOOK_SECRET=whsec_test_abc

# Email Service
SMTP_HOST=localhost
SMTP_PORT=1025
EMAIL_FROM=dev@localhost

# Feature Flags
ENABLE_NEW_CHECKOUT=true
ENABLE_LOYALTY_POINTS=false

# Logging
LOG_LEVEL=debug
ENABLE_QUERY_LOGGING=true

# Session
SESSION_SECRET=dev-secret-change-in-prod
SESSION_TIMEOUT=86400

# File Upload
MAX_FILE_SIZE=10485760
ALLOWED_FILE_TYPES=jpg,png,pdf

# .env.production
NODE_ENV=production
PORT=8080

# Database (with connection pooling)
DB_HOST=prod-cluster.us-east-1.rds.amazonaws.com
DB_PORT=5432
DB_NAME=ecommerce_prod
DB_USER=prod_user
DB_PASSWORD=${DB_PASSWORD_FROM_SECRETS_MANAGER}
DB_POOL_MIN=10
DB_POOL_MAX=50

# Redis Cache (with SSL)
REDIS_HOST=prod-cache.abc123.cache.amazonaws.com
REDIS_PORT=6379
REDIS_TLS=true

# Payment Gateway (LIVE mode)
STRIPE_API_KEY=${STRIPE_LIVE_KEY_FROM_VAULT}
STRIPE_WEBHOOK_SECRET=${STRIPE_WEBHOOK_FROM_VAULT}

# Email Service (via SendGrid)
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASSWORD=${SENDGRID_API_KEY}
EMAIL_FROM=orders@mystore.com

# Feature Flags
ENABLE_NEW_CHECKOUT=true
ENABLE_LOYALTY_POINTS=true

# Logging (less verbose in prod)
LOG_LEVEL=warn
ENABLE_QUERY_LOGGING=false

# Session (secure settings)
SESSION_SECRET=${SESSION_SECRET_FROM_VAULT}
SESSION_TIMEOUT=3600
COOKIE_SECURE=true
COOKIE_HTTPONLY=true

# File Upload (stricter in prod)
MAX_FILE_SIZE=5242880
ALLOWED_FILE_TYPES=jpg,png

How to Use Environment Variables in Code

Node.js / JavaScript:

const express = require('express');
const app = express();

// Access environment variables via process.env
const PORT = process.env.PORT || 3000;
const NODE_ENV = process.env.NODE_ENV || 'development';
const DB_HOST = process.env.DB_HOST;

// Use them in your application
app.listen(PORT, () => {
  console.log(`Server running in ${NODE_ENV} mode on port ${PORT}`);
  console.log(`Connecting to database at ${DB_HOST}`);
});

Python:

import os

# Access environment variables via os.environ
PORT = int(os.environ.get('PORT', 3000))
NODE_ENV = os.environ.get('NODE_ENV', 'development')
DB_HOST = os.environ.get('DB_HOST')

print(f"Server running in {NODE_ENV} mode on port {PORT}")
print(f"Connecting to database at {DB_HOST}")

Go:

import "os"

// Access environment variables via os.Getenv
port := os.Getenv("PORT")
if port == "" {
    port = "3000"
}

nodeEnv := os.Getenv("NODE_ENV")
dbHost := os.Getenv("DB_HOST")

Best Practices for Environment Variables

Never commit .env files to Git

   # .gitignore
   .env
   .env.*
   !.env.example  # Only commit the example

Use .env.example as documentation

   # .env.example - Commit this to Git
   DB_HOST=localhost
   DB_PORT=5432
   DB_NAME=your_database_name
   DB_USER=your_database_user
   DB_PASSWORD=your_secure_password

Use default values in code

   const PORT = process.env.PORT || 3000;  // Fallback to 3000

Validate critical environment variables on startup

   const requiredEnvVars = ['DB_HOST', 'DB_PASSWORD', 'STRIPE_API_KEY'];

   requiredEnvVars.forEach(varName => {
     if (!process.env[varName]) {
       throw new Error(`Missing required environment variable: ${varName}`);
     }
   });

Use secrets management for sensitive data
- AWS Secrets Manager
- HashiCorp Vault
- Azure Key Vault
- Google Cloud Secret Manager

2. Docker Compose Files (The Orchestrator)

Docker Compose files define how your application's services are configured and connected. Different environments need different compose configurations.

Why Different Compose Files?

Development needs:

Mount source code as volumes (for hot-reloading)
Expose all ports for debugging
Run with minimal resources
Include development tools (debuggers, profilers)

Production needs:

Use optimized images
Expose only necessary ports
Configure health checks
Set resource limits
Enable auto-restart

File Structure

project/
├── docker-compose.yml              # Base configuration (shared)
├── docker-compose.dev.yml          # Development overrides
├── docker-compose.staging.yml      # Staging overrides
├── docker-compose.prod.yml         # Production overrides
├── .env.development
├── .env.staging
├── .env.production
└── .env.example

Base Configuration (docker-compose.yml)

This file contains shared configuration across all environments:

version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    environment:
      - NODE_ENV=${NODE_ENV}
      - DB_HOST=${DB_HOST}
      - DB_PORT=${DB_PORT}
      - DB_NAME=${DB_NAME}
      - DB_USER=${DB_USER}
      - DB_PASSWORD=${DB_PASSWORD}
    depends_on:
      - db
      - redis

  db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_DB=${DB_NAME}
      - POSTGRES_USER=${DB_USER}
      - POSTGRES_PASSWORD=${DB_PASSWORD}

  redis:
    image: redis:7-alpine

Development Overrides (docker-compose.dev.yml)

version: '3.8'

services:
  app:
    # Mount source code for hot-reloading
    volumes:
      - ./src:/app/src
      - ./node_modules:/app/node_modules
    # Expose debugging port
    ports:
      - "3000:3000"
      - "9229:9229"  # Node.js debugger
    # Override command to use nodemon
    command: npm run dev
    environment:
      - DEBUG=*  # Enable all debug logs

  db:
    # Expose database port for local tools (pgAdmin, DBeaver)
    ports:
      - "5432:5432"
    volumes:
      # Persist data locally
      - ./data/postgres:/var/lib/postgresql/data

  redis:
    ports:
      - "6379:6379"

  # Additional development tools
  mailhog:  # Catch all emails in development
    image: mailhog/mailhog
    ports:
      - "1025:1025"  # SMTP
      - "8025:8025"  # Web UI

Staging Overrides (docker-compose.staging.yml)

version: '3.8'

services:
  app:
    # Use pre-built image from registry
    image: myregistry.com/myapp:staging-latest
    # Don't mount source code
    # Expose only necessary port
    ports:
      - "8080:3000"
    # Add health check
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    # Restart policy
    restart: unless-stopped
    # Resource limits
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 512M

  db:
    # Use managed database (no local db in staging)
    # Remove this service, connect to external DB via DB_HOST env var
    profiles:
      - disabled  # This prevents it from starting

  redis:
    # Use managed Redis (ElastiCache, etc.)
    profiles:
      - disabled

Production Overrides (docker-compose.prod.yml)

version: '3.8'

services:
  app:
    # Use specific versioned image (not 'latest')
    image: myregistry.com/myapp:v1.2.3
    # Multiple replicas for load balancing
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: '2.0'
          memory: 2G
        reservations:
          cpus: '1.0'
          memory: 1G
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
        window: 120s
    # Strict health check
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 60s
    # Read-only root filesystem for security
    read_only: true
    tmpfs:
      - /tmp
    # No ports exposed (behind load balancer)
    # Load balancer handles external traffic

  # Use external managed services (RDS, ElastiCache)
  # No db or redis services defined

Using Different Compose Files

# Development
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

# Staging
docker-compose -f docker-compose.yml -f docker-compose.staging.yml up -d

# Production
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Pro Tip: Use Environment-Specific Scripts

Create helper scripts to simplify commands:

# scripts/dev.sh
#!/bin/bash
export $(cat .env.development | xargs)
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

# scripts/staging.sh
#!/bin/bash
export $(cat .env.staging | xargs)
docker-compose -f docker-compose.yml -f docker-compose.staging.yml up -d

# scripts/prod.sh
#!/bin/bash
export $(cat .env.production | xargs)
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

3. CI/CD Pipeline Stages (The Automation)

CI/CD (Continuous Integration / Continuous Deployment) pipelines automate the process of testing, building, and deploying your application to different environments.

The CI/CD Flow

[Code Push] → [CI Pipeline] → [Build] → [Test] → [Deploy to Env]
     ↓
  GitHub          ↓              ↓        ↓           ↓
  GitLab      Run Tests      Docker    Unit Tests   Dev/Staging/Prod
  Bitbucket   Lint Code      Build     Integration
                              Push      E2E Tests

Example: GitHub Actions Workflow

# .github/workflows/deploy.yml
name: Deploy to Environments

on:
  push:
    branches:
      - develop      # Triggers deployment to staging
      - main         # Triggers deployment to production
  pull_request:
    branches:
      - develop
      - main

jobs:
  # Job 1: Run tests (always run)
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install dependencies
        run: npm ci

      - name: Run linter
        run: npm run lint

      - name: Run unit tests
        run: npm test

      - name: Run integration tests
        run: npm run test:integration

  # Job 2: Build Docker image
  build:
    needs: test  # Only run if tests pass
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v2

      - name: Login to Container Registry
        uses: docker/login-action@v2
        with:
          registry: myregistry.com
          username: ${{ secrets.REGISTRY_USERNAME }}
          password: ${{ secrets.REGISTRY_PASSWORD }}

      - name: Build and push Docker image
        uses: docker/build-push-action@v4
        with:
          context: .
          push: true
          tags: |
            myregistry.com/myapp:${{ github.sha }}
            myregistry.com/myapp:latest

  # Job 3: Deploy to Development
  deploy-dev:
    needs: build
    if: github.ref == 'refs/heads/develop' && github.event_name == 'push'
    runs-on: ubuntu-latest
    environment: development
    steps:
      - name: Deploy to Development Server
        run: |
          # SSH into dev server and deploy
          ssh ${{ secrets.DEV_SERVER_USER }}@${{ secrets.DEV_SERVER_HOST }} << 'EOF'
            cd /opt/myapp
            docker pull myregistry.com/myapp:latest
            docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d
          EOF

  # Job 4: Deploy to Staging
  deploy-staging:
    needs: build
    if: github.ref == 'refs/heads/develop' && github.event_name == 'push'
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - name: Deploy to Staging
        run: |
          ssh ${{ secrets.STAGING_SERVER_USER }}@${{ secrets.STAGING_SERVER_HOST }} << 'EOF'
            cd /opt/myapp
            export $(cat .env.staging | xargs)
            docker pull myregistry.com/myapp:${{ github.sha }}
            docker-compose -f docker-compose.yml -f docker-compose.staging.yml up -d
          EOF

      - name: Run smoke tests
        run: |
          # Basic health check
          curl -f https://staging.myapp.com/health || exit 1

  # Job 5: Deploy to Production (manual approval required)
  deploy-production:
    needs: [build, deploy-staging]
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    runs-on: ubuntu-latest
    environment: 
      name: production
      url: https://myapp.com
    steps:
      - name: Deploy to Production
        run: |
          ssh ${{ secrets.PROD_SERVER_USER }}@${{ secrets.PROD_SERVER_HOST }} << 'EOF'
            cd /opt/myapp
            export $(cat .env.production | xargs)
            # Use specific version tag, not 'latest'
            docker pull myregistry.com/myapp:${{ github.sha }}
            docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
          EOF

      - name: Run production smoke tests
        run: |
          curl -f https://myapp.com/health || exit 1

      - name: Notify team
        uses: 8398a7/action-slack@v3
        with:
          status: ${{ job.status }}
          text: 'Production deployment completed!'
          webhook_url: ${{ secrets.SLACK_WEBHOOK }}

Key Concepts in CI/CD Stages

1. Jobs and Dependencies

jobs:
  test:      # Run tests first
  build:     # Build only if tests pass
    needs: test
  deploy:    # Deploy only if build succeeds
    needs: build

2. Branch-Based Deployment

# Deploy to staging when pushing to 'develop' branch
if: github.ref == 'refs/heads/develop'

# Deploy to production when pushing to 'main' branch
if: github.ref == 'refs/heads/main'

3. Environment Protection

GitHub allows you to configure environment protection rules:

Required reviewers: Deployment to production requires approval
Wait timer: Enforce a delay before deployment
Deployment branches: Only specific branches can deploy to production

environment: 
  name: production  # References GitHub environment with protection rules
  url: https://myapp.com

4. Secrets Management

Store sensitive data in GitHub Secrets:

Repository Settings → Secrets and variables → Actions → New repository secret

Access them in workflows:

password: ${{ secrets.DATABASE_PASSWORD }}

Real-World Example: E-commerce Application

Let's put it all together with a complete example.

Scenario

You're building an e-commerce platform with:

Web API (Node.js + Express)
PostgreSQL database
Redis cache
Payment processing (Stripe)
Email notifications
File uploads

Project Structure

ecommerce-app/
├── src/
│   ├── app.js
│   ├── config/
│   │   └── database.js
│   ├── routes/
│   ├── controllers/
│   └── services/
├── tests/
├── .env.example
├── .env.development
├── .env.staging
├── .env.production
├── docker-compose.yml
├── docker-compose.dev.yml
├── docker-compose.staging.yml
├── docker-compose.prod.yml
├── Dockerfile
├── .github/
│   └── workflows/
│       └── deploy.yml
└── package.json

1. Application Code (src/app.js)

const express = require('express');
const { Pool } = require('pg');
const redis = require('redis');
const stripe = require('stripe')(process.env.STRIPE_API_KEY);

const app = express();

// Configuration from environment variables
const PORT = process.env.PORT || 3000;
const NODE_ENV = process.env.NODE_ENV || 'development';

// Database connection
const pool = new Pool({
  host: process.env.DB_HOST,
  port: process.env.DB_PORT,
  database: process.env.DB_NAME,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
});

// Redis connection
const redisClient = redis.createClient({
  url: `redis://${process.env.REDIS_HOST}:${process.env.REDIS_PORT}`
});

// Health check endpoint
app.get('/health', async (req, res) => {
  try {
    // Check database
    await pool.query('SELECT 1');

    // Check Redis
    await redisClient.ping();

    res.json({ 
      status: 'healthy',
      environment: NODE_ENV,
      timestamp: new Date().toISOString()
    });
  } catch (error) {
    res.status(503).json({ 
      status: 'unhealthy', 
      error: error.message 
    });
  }
});

// API endpoints
app.post('/api/orders', async (req, res) => {
  // Order processing logic
  // Uses environment-specific configuration automatically
});

// Start server
app.listen(PORT, () => {
  console.log(`🚀 Server running in ${NODE_ENV} mode on port ${PORT}`);
});

2. Environment Files

.env.development:

# Application
NODE_ENV=development
PORT=3000
DEBUG=true

# Database (local)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=ecommerce_dev
DB_USER=dev_user
DB_PASSWORD=dev_password

# Redis (local)
REDIS_HOST=localhost
REDIS_PORT=6379

# Stripe (test mode)
STRIPE_API_KEY=sk_test_51A1B2C3D4E5F6
STRIPE_WEBHOOK_SECRET=whsec_test_abc123

# Email (local MailHog)
SMTP_HOST=localhost
SMTP_PORT=1025

# File Upload
UPLOAD_DIR=/tmp/uploads
MAX_FILE_SIZE=10485760

# Feature Flags
ENABLE_LOYALTY_PROGRAM=true
ENABLE_GIFT_CARDS=false

.env.staging:

# Application
NODE_ENV=staging
PORT=8080
DEBUG=false

# Database (AWS RDS)
DB_HOST=staging-db.abc123.us-east-1.rds.amazonaws.com
DB_PORT=5432
DB_NAME=ecommerce_staging
DB_USER=staging_user
DB_PASSWORD=${DB_PASSWORD_FROM_SECRETS}

# Redis (AWS ElastiCache)
REDIS_HOST=staging-cache.abc123.cache.amazonaws.com
REDIS_PORT=6379

# Stripe (test mode, but closer to production)
STRIPE_API_KEY=${STRIPE_TEST_KEY_FROM_VAULT}
STRIPE_WEBHOOK_SECRET=${STRIPE_TEST_WEBHOOK_FROM_VAULT}

# Email (SendGrid)
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASSWORD=${SENDGRID_KEY_FROM_VAULT}

# File Upload (S3)
UPLOAD_DIR=s3://ecommerce-staging-uploads
MAX_FILE_SIZE=5242880

# Feature Flags
ENABLE_LOYALTY_PROGRAM=true
ENABLE_GIFT_CARDS=true

.env.production:

# Application
NODE_ENV=production
PORT=8080
DEBUG=false

# Database (AWS RDS with replicas)
DB_HOST=prod-db.xyz789.us-east-1.rds.amazonaws.com
DB_PORT=5432
DB_NAME=ecommerce_prod
DB_USER=prod_user
DB_PASSWORD=${DB_PASSWORD_FROM_VAULT}
DB_POOL_MIN=20
DB_POOL_MAX=100

# Redis (AWS ElastiCache cluster)
REDIS_HOST=prod-cache.xyz789.cache.amazonaws.com
REDIS_PORT=6379
REDIS_TLS=true

# Stripe (LIVE mode)
STRIPE_API_KEY=${STRIPE_LIVE_KEY_FROM_VAULT}
STRIPE_WEBHOOK_SECRET=${STRIPE_LIVE_WEBHOOK_FROM_VAULT}

# Email (SendGrid with dedicated IP)
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASSWORD=${SENDGRID_PROD_KEY_FROM_VAULT}

# File Upload (S3 with CloudFront)
UPLOAD_DIR=s3://ecommerce-prod-uploads
CLOUDFRONT_URL=https://cdn.mystore.com
MAX_FILE_SIZE=5242880

# Feature Flags
ENABLE_LOYALTY_PROGRAM=true
ENABLE_GIFT_CARDS=true

# Security
SESSION_SECRET=${SESSION_SECRET_FROM_VAULT}
COOKIE_SECURE=true
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=900000

3. The Deployment Flow

┌──────────────────────────────────────────────────────────────┐
│                     Developer Workflow                        │
└──────────────────────────────────────────────────────────────┘

1. Local Development
   ├─ Developer writes code
   ├─ Uses .env.development
   ├─ Runs: docker-compose -f docker-compose.yml -f docker-compose.dev.yml up
   └─ Tests at http://localhost:3000

2. Commit & Push to 'develop' branch
   ├─ GitHub Actions triggers
   ├─ Runs tests
   ├─ Builds Docker image
   └─ Auto-deploys to Staging

3. Staging Environment
   ├─ Uses .env.staging
   ├─ QA team tests
   ├─ Runs: docker-compose -f docker-compose.yml -f docker-compose.staging.yml up
   └─ Accessible at https://staging.mystore.com

4. Merge to 'main' branch (after approval)
   ├─ GitHub Actions triggers
   ├─ Requires manual approval (protected environment)
   ├─ Deploys to Production
   └─ Uses .env.production

5. Production Environment
   ├─ Uses .env.production
   ├─ Runs: docker-compose -f docker-compose.yml -f docker-compose.prod.yml up
   ├─ Serves real customers
   └─ Accessible at https://mystore.com

4. What Changes Between Environments?

Component	Development	Staging	Production
Database	Local PostgreSQL	AWS RDS (small)	AWS RDS (large, replicated)
Cache	Local Redis	ElastiCache (small)	ElastiCache (cluster mode)
Email	MailHog (fake)	SendGrid (test mode)	SendGrid (live, dedicated IP)
Payment	Stripe test mode	Stripe test mode	Stripe LIVE mode
File Storage	Local /tmp	S3 (staging bucket)	S3 + CloudFront CDN
Debug Mode	ON	OFF	OFF
Logging	Verbose	Moderate	Errors only
Resources	Minimal	Medium	Auto-scaling
SSL/TLS	No	Yes	Yes (with cert pinning)
Monitoring	None	Basic	Comprehensive (DataDog)

Common Pitfalls and How to Avoid Them

Pitfall #1: Forgetting to Update .env Files

Problem:

# You update .env.development but forget .env.staging
# Staging deploys with old configuration

Solution:

Document all environment variables in .env.example
Add validation script to check for missing variables
Use environment variable management tools (Doppler, Infisical)

// scripts/validate-env.js
const required = ['DB_HOST', 'DB_PASSWORD', 'STRIPE_API_KEY'];
const missing = required.filter(key => !process.env[key]);

if (missing.length > 0) {
  console.error(`Missing required environment variables: ${missing.join(', ')}`);
  process.exit(1);
}

Pitfall #2: Using 'latest' Tag in Production

Problem:

# ❌ BAD: Unpredictable, hard to rollback
image: myregistry.com/myapp:latest

Solution:

# ✅ GOOD: Version-specific, easy to rollback
image: myregistry.com/myapp:v1.2.3
# Or use commit SHA
image: myregistry.com/myapp:a1b2c3d

Pitfall #3: Mixing Configuration Methods

Problem:

// ❌ BAD: Some config in code, some in env vars
const config = {
  port: 3000,  // Hardcoded
  dbHost: process.env.DB_HOST,  // From env
  debug: NODE_ENV === 'development' ? true : false  // Logic in code
};

Solution:

// ✅ GOOD: All configuration from environment
const config = {
  port: parseInt(process.env.PORT) || 3000,
  dbHost: process.env.DB_HOST,
  debug: process.env.DEBUG === 'true'
};

Pitfall #4: Exposing Secrets in Logs

Problem:

// ❌ BAD: Logs sensitive data
console.log('Connecting to database:', {
  host: DB_HOST,
  user: DB_USER,
  password: DB_PASSWORD  // Oops! Logged the password
});

Solution:

// ✅ GOOD: Redact sensitive data
console.log('Connecting to database:', {
  host: DB_HOST,
  user: DB_USER,
  password: '***REDACTED***'
});

Pitfall #5: No Rollback Strategy

Problem:

Deploy to production
Something breaks
No easy way to revert

Solution:

Use versioned images (not latest)
Keep previous version running until new version is verified
Blue-green deployment or canary releases

# Quick rollback example
docker-compose pull myapp:v1.2.2  # Previous working version
docker-compose up -d

Pitfall #6: Skipping Staging

Problem:

Push directly from dev to production
Miss environment-specific bugs
Customers affected by issues

Solution:

Always deploy to staging first
Run smoke tests in staging
Get approval before production deploy

Best Practices Checklist

✅ Environment Variables

[ ] Never commit .env files to Git
[ ] Use .env.example for documentation
[ ] Validate required variables on startup
[ ] Use secrets management for sensitive data (Vault, AWS Secrets Manager)
[ ] Set sane defaults in code where possible
[ ] Use consistent naming conventions (SCREAMING_SNAKE_CASE)
[ ] Document what each variable does
[ ] Separate secrets from config (config can be version-controlled, secrets cannot)

✅ Docker Compose

[ ] Use base docker-compose.yml + environment-specific overlays
[ ] Version control all compose files
[ ] Set resource limits in production
[ ] Configure health checks
[ ] Use restart policies
[ ] Don't expose unnecessary ports in production
[ ] Use named volumes for data persistence
[ ] Set appropriate logging drivers

✅ CI/CD Pipeline

[ ] Run tests before every deployment
[ ] Build once, deploy everywhere (same Docker image)
[ ] Use version tags, not latest
[ ] Implement deployment gates (manual approval for production)
[ ] Set up rollback procedures
[ ] Monitor deployments
[ ] Notify team of deployment status
[ ] Keep deployment logs

✅ Security

[ ] Never log sensitive data
[ ] Use HTTPS in staging and production
[ ] Rotate secrets regularly
[ ] Implement rate limiting
[ ] Use secure session management
[ ] Keep dependencies updated
[ ] Scan images for vulnerabilities
[ ] Follow principle of least privilege

✅ Monitoring

[ ] Set up health check endpoints
[ ] Implement logging (structured logs)
[ ] Monitor application metrics
[ ] Set up alerts for critical issues
[ ] Track deployment history
[ ] Monitor resource usage
[ ] Set up error tracking (Sentry, Rollbar)

Tools and Resources

Environment Management

Dotenv libraries: Load environment variables
- Node.js: dotenv
- Python: python-dotenv
- Go: godotenv
Secrets Management:

Container Management

Docker
Docker Compose
Kubernetes (for advanced orchestration)

CI/CD Platforms

Monitoring & Logging

Prometheus + Grafana
DataDog
New Relic
ELK Stack (Elasticsearch, Logstash, Kibana)
Sentry

Conclusion

Managing applications across multiple environments is a fundamental DevOps skill. Here's what you've learned:

Key Takeaways

Same code, different configs - Never change application logic for different environments
Three pillars - Environment variables, Docker Compose, and CI/CD stages
Env vars control behavior - Not business logic
Docker Compose orchestrates - Different configurations for different needs
CI/CD automates - Consistent, repeatable deployments
Security matters - Never expose secrets, always use proper management
Always test in staging - Before production deployment

The Mental Model

Think of your application as a template:

Application Code (Template)
      +
Configuration (Variables)
      =
Running Application (Instance)

The template stays the same. The variables change. The result is different instances optimized for each environment.

Next Steps

Now that you understand the concepts:

Practice: Set up a simple app with dev/staging/prod environments
Experiment: Try different Docker Compose configurations
Automate: Build your first CI/CD pipeline
Secure: Implement proper secrets management
Monitor: Add health checks and logging
Scale: Learn about Kubernetes for advanced orchestration

Final Thought

Environment management isn't just about technology—it's about discipline. It's about creating systems that are predictable, repeatable, and reliable. It's about making sure that what works on your laptop also works in production.

Master these concepts, and you'll be able to deploy with confidence, knowing that your application behaves consistently across all environments.

Questions or Feedback?

Did this guide help you understand environment management? Have questions about specific scenarios? Drop a comment below!

Want to see a follow-up article on:

Kubernetes environment management?
Advanced CI/CD patterns?
Secrets management deep-dive?
Production deployment strategies?

Let me know in the comments! 🚀

This article is designed to give you crystal-clear understanding of DevOps environment management. If something is unclear or you'd like more detail on any topic, don't hesitate to ask!

Load Balancing a Simple Static Site with Docker and Nginx: A Beginner's Journey

Niraj Maharjan — Mon, 12 Jan 2026 14:44:10 +0000

Introduction

Ever wondered how websites handle thousands of requests simultaneously without crashing? The answer is load balancing,distributing incoming traffic across multiple servers. In this article, I'll walk you through my journey of building a load-balanced static website using Docker and Nginx, including the real problems I faced and how I solved them.

By the end of this tutorial, you'll understand:

How to containerize a simple Node.js application with Docker
How to run multiple instances of the same app using Docker Compose
How to set up Nginx as a reverse proxy and load balancer
How to troubleshoot common issues like SELinux permission errors
How to access your application from other devices on your network

This guide is perfect for beginners who want to understand the fundamentals of containerization and load balancing.

What We're Building

We're going to create:

A simple static website with vanilla HTML, CSS, and JavaScript
An Express.js server to serve our static files
Three Docker containers running identical instances of our app
An Nginx load balancer to distribute traffic between the three instances

Architecture Overview:

Step 1: Creating the Static Site with Express

First, let's create a simple Node.js application that serves static HTML, CSS, and JavaScript files.

Project Structure

simple-static-site/
├── public/
│   ├── index.html
│   ├── style.css
│   └── script.js
├── server.js
├── package.json
├── Dockerfile
└── docker-compose.yml

The Express Server (server.js)

const express = require('express');
const path = require('path');

const app = express();
const PORT = process.env.PORT || 3001;
const APP_NAME = process.env.APP_NAME || 'Default App';

// Serve static files from the 'public' directory
app.use(express.static(path.join(__dirname, 'public')));

// Add a simple API endpoint to identify which instance is responding
app.get('/api/info', (req, res) => {
  res.json({
    appName: APP_NAME,
    port: PORT,
    timestamp: new Date().toISOString()
  });
});

app.listen(PORT, () => {
  console.log(`${APP_NAME} listening on port ${PORT}`);
});

package.json

{
  "name": "simple-static-site",
  "version": "1.0.0",
  "description": "A simple static site with Express server",
  "main": "server.js",
  "scripts": {
    "start": "node server.js"
  },
  "dependencies": {
    "express": "^4.18.2"
  }
}

Key Points:

We use express.static() to serve files from the public directory
The APP_NAME environment variable helps us identify which container is responding
The /api/info endpoint is useful for verifying load balancing is working

github link for the project : https://github.com/NirajMaharjan/Static_Site.git

Step 2: Dockerizing the Application

Now let's containerize our application so we can run multiple instances easily.

Creating the Dockerfile

# Use official Node.js runtime as base image
FROM node:18-alpine

# Set working directory inside container
WORKDIR /app

# Copy package.json and package-lock.json
COPY package*.json ./

# Install dependencies
RUN npm install --production

# Copy application code
COPY . .

# Expose port 3001
# Note: This is just documentation - it doesn't actually publish the port
EXPOSE 3001

# Start the application
CMD ["npm", "start"]

Important Note about EXPOSE:
The EXPOSE instruction in the Dockerfile is purely documentation. It tells other developers which port the application uses, but it doesn't actually make the port accessible from outside the container. We'll handle actual port publishing in our docker-compose.yml file.

Building the Docker Image

# Build the image
docker build -t simple-static-site .

# Verify the image was created
docker images

You should see your simple-static-site image in the list.

Step 3: Running Multiple Instances with Docker Compose

Docker Compose allows us to define and run multiple containers with a single configuration file. We'll create three instances of our application, each with a unique name and port.

docker-compose.yml

version: '3.8'

services:
  app1:
    build: .
    container_name: app1
    environment:
      - APP_NAME=App1
      - PORT=3001
    ports:
      - "3002:3001"
    restart: unless-stopped

  app2:
    build: .
    container_name: app2
    environment:
      - APP_NAME=App2
      - PORT=3001
    ports:
      - "3003:3001"
    restart: unless-stopped

  app3:
    build: .
    container_name: app3
    environment:
      - APP_NAME=App3
      - PORT=3001
    ports:
      - "3004:3001"
    restart: unless-stopped

Breaking Down the Configuration:

build: . - Builds the Docker image from the Dockerfile in the current directory
container_name - Gives each container a friendly name
environment - Sets environment variables inside each container
- APP_NAME - Used to identify which instance is responding
- PORT - The internal port the app listens on (always 3001 inside the container)
ports - Maps host ports to container ports
- Format: "HOST_PORT:CONTAINER_PORT"
- "3002:3001" means: "Map host port 3002 to container port 3001"
restart: unless-stopped - Automatically restart the container if it crashes

Starting the Containers

# Start all services
docker-compose up -d

# Verify all containers are running
docker-compose ps

# Check logs
docker-compose logs -f

Testing Individual Instances

Test each instance directly to ensure they're working:

# Test App1
curl http://localhost:3002/api/info

# Test App2
curl http://localhost:3003/api/info

# Test App3
curl http://localhost:3004/api/info

Each should return different app names, confirming all three instances are running independently.

Step 4: Setting Up Nginx as a Load Balancer

Now comes the exciting part—configuring Nginx to distribute traffic across our three application instances.

Two Deployment Approaches

There are two common ways to deploy Nginx with Docker:

Nginx on the host VM (what we'll use)
- Nginx runs directly on your virtual machine
- Docker containers run your application
- Best for learning and understanding how reverse proxies work
Nginx in a Docker container
- Everything runs in Docker
- Easier to manage and deploy
- Better for production environments

We'll focus on approach #1 because it helps you understand the fundamentals better.

Installing Nginx on Your VM

# Update package list
sudo apt update

# Install Nginx
sudo apt install nginx -y

# Start Nginx
sudo systemctl start nginx

# Enable Nginx to start on boot
sudo systemctl enable nginx

# Check status
sudo systemctl status nginx

Configuring Nginx for Load Balancing

Create a new Nginx configuration file:

sudo nano /etc/nginx/sites-available/loadbalancer

Add this configuration:

# Define upstream servers (your Docker containers)
upstream app_backend {
    # Round-robin load balancing (default)
    server localhost:3002;
    server localhost:3003;
    server localhost:3004;
}

server {
    listen 8080;
    server_name localhost;

    location / {
        # Proxy requests to the upstream backend
        proxy_pass http://app_backend;

        # Important proxy headers
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Understanding the Configuration:

upstream app_backend - Defines a group of backend servers
- Nginx will distribute requests among these servers using round-robin by default
server localhost:3002/3003/3004 - Points to our Docker containers
- Remember: Docker published these ports on the host
listen 8080 - Nginx listens on port 8080 for incoming requests
proxy_pass http://app_backend - Forwards requests to one of the upstream servers
proxy_set_header directives - Preserve important request information
- The backend servers can see the original client IP, not just Nginx's IP

Activating the Configuration

# Create symbolic link to enable the site
sudo ln -s /etc/nginx/sites-available/loadbalancer /etc/nginx/sites-enabled/

# Test configuration for syntax errors
sudo nginx -t

# Reload Nginx to apply changes
sudo systemctl reload nginx

Step 5: The Problem—"Bad Gateway" Error

When I first tried to access http://localhost:8080, I got a 502 Bad Gateway error. This is a common issue, so let's troubleshoot it step-by-step.

Debugging Process

1. Check if Nginx is running:

sudo systemctl status nginx

✅ Nginx was running fine.

2. Check if Docker containers are accessible:

curl -v http://localhost:3002
curl -v http://localhost:3003
curl -v http://localhost:3004

✅ All containers responded correctly.

3. Check Nginx error logs:

sudo tail -f /var/log/nginx/error.log

❌ Found the problem!

2026/01/12 14:11:15 [crit] 35238#35238: *16 connect() to 127.0.0.1:3004 
failed (13: Permission denied) while connecting to upstream, 
client: 127.0.0.1, server: localhost, request: "GET / HTTP/1.1", 
upstream: "http://127.0.0.1:3004/", host: "localhost:8080"

The key phrase here is "Permission denied (13)". This is a SELinux security issue.

Step 6: Understanding and Fixing SELinux

What is SELinux?

SELinux (Security-Enhanced Linux) is a security module that enforces strict access controls on Linux systems. By default, SELinux prevents Nginx from making network connections to other services—even on localhost!

This is a security feature, not a bug. SELinux operates on the principle of least privilege: programs should only have the permissions they absolutely need.

The Solution

We need to allow Nginx to make network connections:

# Check current SELinux status
sudo getsebool -a | grep httpd_can_network_connect

# Allow Nginx to make network connections
sudo setsebool -P httpd_can_network_connect 1

# Verify the change
sudo getsebool httpd_can_network_connect

What this command does:

setsebool - Set SELinux boolean (a true/false configuration)
-P - Make the change persistent (survives reboots)
httpd_can_network_connect - The specific permission we're enabling
1 - Enable (use 0 to disable)

Testing the Fix

Now try accessing your site again:

curl http://localhost:8080

🎉 Success! You should now see your static site being served through Nginx.

Verifying Load Balancing

Let's verify that Nginx is actually distributing requests across all three containers:

# Make multiple requests to the /api/info endpoint
for i in {1..9}; do
  curl -s http://localhost:8080/api/info | grep appName
done

You should see responses rotating between App1, App2, and App3:

{"appName":"App1",...}
{"appName":"App2",...}
{"appName":"App3",...}
{"appName":"App1",...}
{"appName":"App2",...}
{"appName":"App3",...}
...

This confirms that Nginx is using round-robin load balancing—distributing requests evenly across all three backend servers.

Step 7: Accessing from Other Devices on Your Network

Want to access your site from your phone or another computer on the same network? There's one more configuration needed.

The Problem: NAT Mode

If you're running this in a virtual machine (like VirtualBox or VMware), your VM's network adapter is likely in NAT mode by default.

What is NAT mode?

NAT (Network Address Translation) allows your VM to access the internet
But other devices on your network can't directly access your VM
The VM gets a private IP that's only accessible from the host machine

The Solution: Bridged Mode

Switch your VM's network adapter to Bridged mode:

In VirtualBox:

Power off your VM
Go to VM Settings → Network → Adapter 1
Change "Attached to:" from "NAT" to "Bridged Adapter"
Select your physical network adapter (usually your WiFi or Ethernet card)
Start your VM

After switching to Bridged mode:

Your VM will get its own IP address on your local network, just like any other device.

Finding Your VM's IP Address

# Find your IP address
ip addr show

# Or use
hostname -I

Look for an IP address like 192.168.1.x or 10.0.0.x.

Accessing from Other Devices

Now you can access your load-balanced site from any device on your network:

http://YOUR_VM_IP:8080

For example:

http://192.168.1.100:8080

Testing from your phone:

Connect your phone to the same WiFi network
Open a browser and go to http://YOUR_VM_IP:8080
Refresh the page multiple times and check the /api/info endpoint
You'll see different app names, proving load balancing works across devices!

Understanding the Complete Flow

Let's trace what happens when you access http://YOUR_VM_IP:8080:

Client Request → Your browser sends a request to port 8080
Nginx Receives → Nginx running on the VM accepts the request
Load Balancing → Nginx selects one of the three upstream servers (round-robin)
Proxy to Docker → Nginx forwards the request to localhost:3002, 3003, or 3004
Docker Routes → Docker routes the request to the corresponding container
Express Responds → The Express server in the container processes and responds
Nginx Returns → Nginx sends the response back to your browser

All of this happens in milliseconds!

Alternative Approach: Nginx in Docker

Earlier, I mentioned there are two ways to deploy Nginx. Let's briefly explore the second approach.

Docker Compose with Nginx

You can run Nginx inside a Docker container too:

version: '3.8'

services:
  nginx:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - app1
      - app2
      - app3

  app1:
    build: .
    environment:
      - APP_NAME=App1
    # No ports mapping needed - Nginx accesses via Docker network

  app2:
    build: .
    environment:
      - APP_NAME=App2

  app3:
    build: .
    environment:
      - APP_NAME=App3

Key Differences:

No port mapping on app containers—they're only accessible within the Docker network
Service names as hostnames—Nginx references app1, app2, app3 directly
Everything in Docker—easier to deploy and tear down

Nginx Configuration for Docker

upstream app_backend {
    server app1:3001;  # Use service names, not localhost
    server app2:3001;
    server app3:3001;
}

server {
    listen 80;

    location / {
        proxy_pass http://app_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Benefits of this approach:

Everything is containerized and portable
Docker handles networking automatically
Easier to deploy to production (just copy docker-compose.yml)
No SELinux issues since everything is in Docker

Common Issues and Solutions

Issue 1: "Cannot connect to Docker daemon"

Problem: Docker service isn't running.

Solution:

sudo systemctl start docker
sudo systemctl enable docker

Issue 2: Port Already in Use

Problem: Another service is using ports 3002, 3003, 3004, or 8080.

Solution:

# Find what's using the port
sudo lsof -i :8080

# Kill the process or change your port in docker-compose.yml

Issue 3: Containers Start Then Immediately Stop

Problem: Application crashes on startup.

Solution:

# Check container logs
docker-compose logs app1

# Common causes:
# - Missing dependencies in package.json
# - Syntax errors in server.js
# - Wrong working directory in Dockerfile

Issue 4: Changes Not Reflected

Problem: Modified code but container still runs old version.

Solution:

# Rebuild containers
docker-compose up -d --build

# Or completely rebuild
docker-compose down
docker-compose build --no-cache
docker-compose up -d

Issue 5: SELinux Blocks Connections (Even After Fix)

Problem: Still getting permission denied errors.

Solution:

# Check SELinux logs for specific denials
sudo ausearch -m avc -ts recent

# Temporarily disable SELinux for testing (NOT for production)
sudo setenforce 0

# Re-enable when done
sudo setenforce 1

Best Practices and Production Considerations

Security

Never disable SELinux in production—configure it properly instead
Use environment variables for sensitive data—never hardcode credentials
Limit exposed ports—only expose what's necessary
Use HTTPS in production—set up SSL/TLS certificates with Let's Encrypt
Run containers as non-root users—add a USER directive in your Dockerfile

Performance

Use health checks—ensure Nginx doesn't route to unhealthy containers

   upstream app_backend {
       server app1:3001 max_fails=3 fail_timeout=30s;
       server app2:3001 max_fails=3 fail_timeout=30s;
       server app3:3001 max_fails=3 fail_timeout=30s;
   }

Configure connection pooling—keep persistent connections to backends

   upstream app_backend {
       server app1:3001;
       keepalive 32;  # Maintain 32 connections
   }

Enable caching—reduce load on backend servers

   proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m;

   location / {
       proxy_cache my_cache;
       proxy_pass http://app_backend;
   }

Monitoring

Add health check endpoints to your Express app:

   app.get('/health', (req, res) => {
     res.status(200).json({ status: 'healthy' });
   });

Monitor Nginx status:

   location /nginx_status {
       stub_status;
       allow 127.0.0.1;
       deny all;
   }

Collect logs centrally—use tools like ELK stack or Grafana Loki

Scaling

Horizontal scaling—add more containers in docker-compose.yml
Use Docker Swarm or Kubernetes—for automatic scaling and orchestration
Implement session persistence—if your app needs sticky sessions

   upstream app_backend {
       ip_hash;  # Route same IP to same backend
       server app1:3001;
       server app2:3001;
       server app3:3001;
   }

Conclusion

Congratulations! You've successfully:

✅ Created a containerized Node.js application

✅ Run multiple instances using Docker Compose

✅ Set up Nginx as a reverse proxy and load balancer

✅ Debugged SELinux permission issues

✅ Made your application accessible across your network

✅ Learned two different deployment approaches

Key Takeaways

Docker simplifies deployment—build once, run anywhere
Load balancing improves reliability—if one container fails, others handle the traffic
SELinux is your friend—configure it properly rather than disabling it
Nginx is powerful—reverse proxy, load balancer, cache, and more
Debugging is systematic—check logs, test components individually, isolate issues

Next Steps

Ready to level up? Try these challenges:

Add SSL/TLS encryption—secure your site with HTTPS
Implement session management—use Redis for shared sessions across containers
Add a database—connect your app to PostgreSQL or MongoDB
Deploy to the cloud—try AWS, DigitalOcean, or Heroku
Set up CI/CD—automate deployment with GitHub Actions
Monitor performance—add Prometheus and Grafana
Try Kubernetes—graduate to container orchestration

Resources

Questions or Feedback?

Did you encounter different issues? Have suggestions for improving this guide? Drop a comment below! I'd love to hear about your experience and help troubleshoot any problems you face.

Happy coding! 🚀

This article is based on my real experience building and troubleshooting a load-balanced application. All errors and solutions are documented as they happened—because learning from mistakes is the best way to truly understand technology.

DEV Community: Niraj Maharjan

A Practical Guide to Structuring a Go Backend

1. Follow One Request Through the System

2. The Full File & Folder Catalog

Root-level files

cmd/ — your executables

internal/main.go — what it's actually doing

Other common internal/ folders

Outside internal/

pkg/ — the controversial one

Core vs. optional, at a glance

3. Why Bother With a Repository Interface at All?

4. Validation Isn't One Thing — It's (At Least) Two

5. What Actually Needs a _test.go File?

6. Misconceptions and Pitfalls Worth Naming Explicitly

The One Thing to Actually Remember

Understanding Go Concurrency Through Pipelines: Channels, Goroutines, and the Questions Everyone Asks

The big picture

1. Why is there a return if two goroutines are supposed to be communicating?

2. What does close actually do?

3. The channel is unbuffered — so why does looping over it make sense?

4. How main() actually executes, concurrently

5. Read-only channels and why functions return them

6. What happens if you forget to close? (Deliberately breaking it)

7. What changes if you add buffering?

Putting it all together — a mental model

Quick reference

How to Get a Free .np Domain and Host Your Developer Portfolio

Why I Wanted This in the First Place

Step 1: Registering My .np Domain

Step 2: Building the Portfolio Site

Step 3: Deploying to GitHub Pages

The Problem I Hit (And How I Fixed It)

Step 4: Setting Up DNS with Cloudflare

Here's what I did:

Step 5: Connecting the Custom Domain to GitHub

The Full Flow at a Glance

What I'd Tell My Past Self

Final Thoughts

The Essential Guide to Application Logging: From Basics to Production

Introduction: The Black Box Problem

What is Logging?

The Simple Definition

Think of It Like This:

Log Levels Explained

The Standard Hierarchy

When to Use Each Level

1. DEBUG - Development Details

2. INFO - Normal Operations

3. WARNING - Something's Off

4. ERROR - Something Failed

5. CRITICAL - Everything's on Fire 🔥

Quick Decision Tree

Implementation: Python

Basic Logging

Production-Ready Setup

Structured Logging (JSON)

Using python-json-logger (Easier)

Implementation: Node.js

Basic Logging with Winston (Industry Standard)

Production Setup with Winston

Simple Console Logging (Quick Start)

What to Log (and What NOT to Log)

✅ DO Log

❌ DO NOT Log

Best Practices

1. Use Structured Logging

2. Include Context

3. Use Correlation IDs

4. Log at the Right Level

5. Rotate Log Files

6. Don't Log in Loops (Unless Necessary)

7. Use Appropriate Formats for Environments

Common Mistakes

Mistake #1: Logging Too Much in Production

Mistake #2: Not Logging Enough Context

Mistake #3: Using print() Instead of Logger

Mistake #4: Logging Synchronously in High-Traffic Apps

Mistake #5: Not Including Stack Traces for Errors

Log Aggregation Tools

`cmd/` — your executables

`internal/main.go` — what it's actually doing

Other common `internal/` folders

Outside `internal/`

`pkg/` — the controversial one

5. What Actually Needs a `_test.go` File?

1. Why is there a `return` if two goroutines are supposed to be communicating?

2. What does `close` actually do?

4. How `main()` actually executes, concurrently

6. What happens if you forget to `close`? (Deliberately breaking it)