How Backend Devs Stop 'Works on My Machine' Bugs

Why does my app work locally but crash in production?

Because your Prod environment is missing a library, dependency, or configuration that exists on your laptop and your Test server. Piyush calls this environment misconfiguration, and it's the single most frequent cause of build-promotion failures in pre-container workflows. A Node.js API that runs fine on your machine and passes in Test can crash in Prod with a missing-library error simply because the exact package version was never installed there.

The Build-Ship-Run framework eliminates this class of failure by making the environment irrelevant. You package the application code, all libraries, dependencies, and a bare-minimum OS image together as one shippable unit — the Docker image. That unit runs identically everywhere.

How do I containerise my backend service?

Follow the workflow in order. First, diagnose the promotion problem: document exactly what was present in Dev and Test but missing in Prod. If it's a dependency or config difference, containers solve it directly.

Then author the Dockerfile — one file named exactly `Dockerfile` with a capital D:

1. Select a base image (e.g. a Node base image).

2. Install the exact dependencies (`npm install`).

3. Copy your application source into the image.

4. Define the start command.

Keep it lean — only the libraries your app actually needs. This is the One Dockerfile Per Application principle: a single source of truth for how the image is built.

Next, build with `docker build`. The Docker Client sends this to the Docker Daemon (dockerd), which reads your Dockerfile and produces a versioned image stored locally.

How do I get the same image running in every environment?

Never deploy straight from your build host. Ship the image with `docker push` to a registry — Docker Hub, Artifact Registry, JFrog Artifactory, or Nexus. Think of the registry as GitHub for your binaries: versioned, trackable, auditable storage that makes promotion safe.

Then on each environment, run the image: `docker pull` retrieves the identical image, and `docker run` spins up the container. Because Dev, Test, and Prod all pull the same image, the missing-library failure that plagued your API cannot happen again — the library is baked inside.

What mistakes trip up backend developers first?

- Pushing directly to Prod without a registry. This removes versioning and breaks safe promotion. Always ship through the registry.

- Rebuilding per environment. If you rebuild in each environment you reintroduce drift. Build once, push once, pull everywhere.

- Using floating version tags in your Dockerfile. Pin dependency versions so the same image is genuinely reproducible.

- Confusing image and container. The image is the shippable package; only `docker run` turns it into a live container instance.

- Naming the file `dockerfile` or `Dockerfile.txt`. Use the exact default name so `docker build` detects it.

How do I know the pipeline is correct?

Validate against the Docker component model: Docker Client → Docker Daemon → local image storage → registry → Docker Daemon on target → Container Runtime → running container. Each of build, push, pull, and run maps to a specific component, so any breakage is traceable to one place. If a container fails to start, you know to look at the run command and the Container Runtime, not the registry.

Next step: Take your most fragile service — the one with recurring Prod-only bugs — and write its first Dockerfile today. Build it, push it to Docker Hub, then pull and run it in a clean environment. When it runs identically, you've eliminated an entire class of deployment failure.