Kestrel listening on localhost works perfectly on your laptop — and silently refuses every request an orchestrator ever routes to it. Get this one binding right and most of the rest of containerizing ASP.NET Core falls into place.

Lesson 298 covered the general shape of a .NET Dockerfile — the multi-stage build, the small runtime base image, the layer caching trick. Build that image, run it, and hit it from your browser at localhost:8080, and it works. Deploy the exact same image behind an orchestrator's load balancer, and requests simply time out — nothing reaches the app at all, with no obvious error message pointing at why.

This is one of the single most common first-time container gotchas for ASP.NET Core specifically, and it comes down to one line of network configuration that behaves completely differently inside a container than it does on a developer's machine.

In this lesson, you'll learn exactly why Kestrel has to bind to 0.0.0.0 instead of localhost inside a container, how to configure that correctly, what a .dockerignore file is for, why running as a non-root user matters, and how to put all of it together into one complete, production-ready Dockerfile for an ASP.NET Core Web API.

What Is It?

The Simple Explanation

Containerizing ASP.NET Core well means more than just following the multi-stage Dockerfile pattern from Lesson 298. It means configuring Kestrel — the web server that actually handles HTTP requests for ASP.NET Core — so it's actually reachable from outside the container, keeping the image clean of files it doesn't need, and running the app as securely as the official images make easy.

The Technical Definition

Every container gets its own network namespace — its own private view of network interfaces, isolated from the host's. Inside that namespace, localhost (127.0.0.1) refers only to the container's own loopback interface — traffic that never leaves that one container. Binding a server there means it only accepts connections that originate from within the same container. To accept connections arriving from outside — from the host, from another container, or from an orchestrator's load balancer — Kestrel must bind to 0.0.0.0, meaning "listen on every available network interface," not just the loopback one.

Why Does It Exist?

The Problem — Traffic From Outside the Container Has to Enter Through a Real Interface

When an orchestrator routes a request to a container, that traffic arrives over the container's actual network interface — not over its internal loopback. If Kestrel is only listening on the loopback interface (127.0.0.1), that incoming traffic has nowhere to land: the connection is refused or simply times out, because nothing inside the container is listening on the interface the traffic is actually arriving on. Locally, on a laptop without containers, this distinction is invisible — localhost just means "this machine," and a browser on the same machine reaches it fine. Inside a container, "this machine" (the container's own network namespace) and "where traffic from outside actually enters" are two genuinely different things.

The Solution — Bind to All Interfaces

Telling Kestrel to bind to 0.0.0.0 makes it listen on every network interface available inside the container's namespace — including the one that traffic routed in from outside actually arrives on. This is configured with the ASPNETCORE_URLS environment variable (or the modern ASPNETCORE_HTTP_PORTS shorthand, which implicitly binds to all interfaces on the given port).

Big Picture

How It Works — Building a Container-Ready ASP.NET Core Image

ENV ASPNETCORE_URLS=http://0.0.0.0:8080

EXPOSE 8080

USER app

A Typical .dockerignore

This should look familiar — it directly mirrors the purpose of .gitignore: keep files that only make sense on a local dev machine out of the thing you're packaging. Every file sent to Docker as part of the "build context" gets uploaded to the Docker daemon before the build even starts, so excluding a bulky, irrelevant bin/ or obj/ folder keeps builds noticeably faster, not just tidier.

Simple Example — Diagnosing the Silent Timeout

Here's the exact symptom this lesson is centered on, and the one-line fix:

Meaning: Nothing about the application's routing, controllers, or middleware pipeline changed at all — the entire fix is which network interface Kestrel is told to listen on. This is precisely why the bug is so easy to miss: the app runs, starts up cleanly, logs "Now listening on..." — and still never receives a single request.

Real-World Example

A team containerizes their notification service and deploys it behind an orchestrator's load balancer. Health checks (the ASP.NET Core side of which you already know from Lesson 268) immediately start failing — the orchestrator can't reach the liveness endpoint at all, and eventually kills and restarts the container, which then fails the exact same way again. The application logs show it started successfully and is "listening" — which is exactly what makes this bug so disorienting the first time. The fix is a one-line environment variable change (ASPNETCORE_URLS=http://0.0.0.0:8080, set in the Dockerfile or the orchestrator's container spec), after which the exact same probe that was timing out starts succeeding immediately, with no code change anywhere in the app.

Analogy

Under the Hood — Running as a Non-Root User

By default, a process inside a container that isn't otherwise configured typically runs as root — the same all-powerful account a root user has on a normal Linux machine, just scoped to that container's namespace. If an attacker ever manages to exploit a vulnerability in the running app, running as root inside the container hands them more capability within that container's namespace than running as an unprivileged account would.

This used to mean extra Dockerfile work — creating a dedicated user, setting file permissions correctly. Current official Microsoft .NET container images make this close to free: they already ship a built-in, non-root app user, ready to switch to with one instruction:

This is a real, current, low-effort security improvement — not a theoretical best practice requiring you to build user management from scratch. One line, and the running process no longer has root privileges inside the container.

Common Confusion

1. "Binding to 0.0.0.0 exposes the app to the whole internet" — no, that's a separate concern

0.0.0.0 only controls which interfaces inside the container Kestrel listens on. Whether traffic from the public internet, or another network, can actually reach that container at all is governed entirely separately — by docker run -p port publishing, firewall rules, an orchestrator's network policies, and (if present) a reverse proxy or gateway in front of it. Binding broadly inside the container doesn't bypass any of those outer layers.

2. "This is an ASP.NET Core bug" — no, it's the correct, expected behavior of network namespaces

Kestrel is behaving exactly as configured in both cases — the surprise isn't a defect, it's that "localhost" quietly means something narrower inside a container's own network namespace than it does on an un-containerized machine. Understanding that namespace distinction is the actual fix, not a workaround for broken framework behavior.

Common Mistakes

Mistake 1 — Never setting ASPNETCORE_URLS explicitly and assuming the local-dev default is fine everywhere

Relying on whatever binding behavior worked during local development, without confirming it also binds broadly inside the container. Set ASPNETCORE_URLS (or ASPNETCORE_HTTP_PORTS) explicitly in the Dockerfile or the orchestrator's container spec, so the binding is intentional and documented, not inherited by accident.

Mistake 2 — Skipping .dockerignore entirely

Letting a stale local bin/ or obj/ folder ride along into the Docker build context — slower builds, and a real risk of stale, locally-built binaries silently getting copied in ahead of a fresh dotnet publish output. Add a .dockerignore excluding exactly the kind of local-only artifacts .gitignore already excludes.

Mistake 3 — Never switching away from the default root user

Leaving the final container running as root because it "just works" and nobody added the one extra line. Add USER app in the final stage — current official .NET images ship this user specifically so there's no excuse not to.

When Should I Use It?

• Binding to 0.0.0.0 — always, for any ASP.NET Core app that will run inside a container and needs to be reachable from outside it. There's no scenario in a real deployment where localhost-only binding is what you actually want.
• .dockerignore — every containerized .NET project, exactly as consistently as you'd already add a .gitignore.
• Non-root USER app — the default for any production container; the rare exception is a workload that genuinely requires elevated container privileges for a specific, understood reason.

Mental Model

Key Takeaway

Check Your Understanding

You've seen the single most common ASP.NET Core containerization gotcha, along with .dockerignore and non-root users. Let's confirm it clicked.

You now know exactly why containerized ASP.NET Core apps go unreachable, and how to build a lean, secure image that avoids it. Next: cloud-specific environment variable patterns, building on what you already know from configuration in the Intermediate book.

dotnetmadeeasy.com — Learn C# and .NET, the right way.