The "Works on My Machine" Problem

The deployment gap

Every course in this series builds an app with npm run dev. The app runs on your laptop. But your laptop is not production. Getting the app from your machine to a server that users can reach is where most developers struggle.

What goes wrong

Node.js version mismatch. You develop on Node 22. The server has Node 18. Your code uses a feature added in Node 20. It crashes.

Missing dependencies. You install sharp on macOS. It compiles native bindings for macOS. You deploy to a Linux server. The bindings do not work.

Different OS. Your macOS file system is case-insensitive. You import ./DB.ts when the file is ./db.ts. Works locally. Fails on Linux (case-sensitive).

Environment variables. Locally, you have a .env file with DATABASE_URL. On the server, no one set it. The app crashes at startup with “DATABASE_URL is undefined.”

System dependencies. sharp needs libvips. bcrypt needs build tools. better-sqlite3 needs python3 and make. Your laptop has them installed from some other project. The fresh server does not.

The container idea

A container packages your app, its dependencies, the correct Node.js version, and the right OS libraries into a single artifact. You build the container once on your machine (or in CI), and it runs identically everywhere: your laptop, a VPS, AWS, a colleague’s machine.

The container is a promise: “This exact environment, every time.”

Docker

Docker is the tool that creates and runs containers. It has been the industry standard since 2013. When someone says “containerize your app,” they mean Docker.

This course uses Docker to take a Hectoday HTTP app from npm run dev to a running production deployment with HTTPS, a database, and automated deploys.

What you need

Install Docker Desktop (macOS/Windows) or Docker Engine (Linux):

# Verify installation
docker --version
# Docker version 24.x.x or later

docker compose version
# Docker Compose version v2.x.x

[!NOTE] Docker Desktop includes Docker Engine, Docker CLI, and Docker Compose. On Linux, you can install just Docker Engine and the compose plugin. Both work for this course.

Exercises

Exercise 1: Install Docker if you have not already. Run docker --version and docker compose version. Verify both work.

Exercise 2: Run docker run hello-world. This pulls a tiny test image and runs it. If it prints “Hello from Docker!”, your setup works.

Exercise 3: Think about a deployment that went wrong for you. Was the cause an environment difference? Would a container have prevented it?