Containerise a Node.js Web Application with Docker | Engineering Modules | DevOps Network

Step-by-Step Implementation Guide

### Step 1: Install Docker and Create the Application First install Docker Desktop from the official website. Docker Desktop includes everything you need — the Docker Engine, Docker Compose, and a GUI to see your containers. ```bash ## Verify Docker is installed correctly docker --version ## Expected: Docker version 24.x.x or higher docker compose version ## Expected: Docker Compose version v2.x.x or higher ``` Create your project directory and a simple Node.js application: ```bash mkdir my-docker-app && cd my-docker-app ``` Create `package.json`: ```json { "name": "my-docker-app", "version": "1.0.0", "main": "src/index.js", "scripts": { "start": "node src/index.js", "dev": "nodemon src/index.js" }, "dependencies": { "express": "^4.18.2" } } ``` Create `src/index.js`: ```javascript const express = require('express'); const app = express(); const PORT = process.env.PORT || 3000; // Health check endpoint // Docker and Kubernetes use this to verify the app is alive app.get('/health', (req, res) => { res.json({ status: 'healthy', timestamp: new Date().toISOString(), version: process.env.APP_VERSION || '1.0.0' }); }); // Main endpoint app.get('/', (req, res) => { const name = process.env.APP_NAME || 'DevOps App'; res.json({ message: `Hello from ${name}!`, environment: process.env.NODE_ENV || 'development' }); }); app.listen(PORT, () => { console.log(`Server running on port ${PORT}`); }); ``` > 📌 **Remember:** The `/health` endpoint is not just for testing. In production, Kubernetes, ECS, and load balancers all call this endpoint automatically to check if your container is alive. Always include it. ### Step 2: Write Your First Dockerfile A `Dockerfile` is a text file with instructions that Docker reads top to bottom to build your image. Think of it as a recipe — each line adds a layer to the image. Create `Dockerfile` in your project root: ```dockerfile ## Stage 1: Start from an official Node.js base image ## alpine = lightweight Linux (only 5MB vs 900MB for full Ubuntu) FROM node:20-alpine ## Set the working directory inside the container ## All subsequent commands run from this directory WORKDIR /app ## Copy package files FIRST (before copying source code) ## Why? Docker caches each layer. If package.json does not change, ## Docker reuses the cached npm install layer — much faster builds COPY package*.json ./ ## Install dependencies inside the container RUN npm install --only=production ## Now copy your source code ## This layer changes every time you edit code COPY src/ ./src/ ## Document which port the app listens on ## This is documentation only — does not actually expose the port EXPOSE 3000 ## Security: run as non-root user ## The node user comes pre-created in the official node image USER node ## The command to start the application CMD ["node", "src/index.js"] ``` Create `.dockerignore` to exclude files from the image: ```text node_modules .git .gitignore *.log README.md ``` > 💡 **Tip:** The `.dockerignore` file works exactly like `.gitignore`. Always add `node_modules` here — you never want to copy your local `node_modules` into the image. The `RUN npm install` step inside Docker installs them fresh for the container's operating system. ### Step 3: Build and Run Your Docker Image ```bash ## Build the image and tag it with a name ## The dot at the end means 'use the Dockerfile in the current directory' docker build -t my-docker-app:v1 . ## Watch the build output — you will see each layer being processed ## Expected output includes: ## => [1/5] FROM node:20-alpine ## => [2/5] WORKDIR /app ## => [3/5] COPY package*.json ./ ## => [4/5] RUN npm install ## => [5/5] COPY src/ ./src/ ## => exporting to image ## List your images docker images | grep my-docker-app ## Expected: my-docker-app v1 abc123 2 minutes ago ~150MB ## Run the container ## -d = detached (run in background) ## -p 3000:3000 = map port 3000 on your machine to port 3000 in container ## --name = give it a readable name docker run -d -p 3000:3000 --name webapp my-docker-app:v1 ## Verify it is running docker ps ## Expected: webapp container showing status Up ## Test the application curl http://localhost:3000 ## Expected: {"message":"Hello from DevOps App!","environment":"development"} curl http://localhost:3000/health ## Expected: {"status":"healthy","timestamp":"...","version":"1.0.0"} ``` ### Step 4: Add Docker Compose for Multi-Container Setup Docker Compose lets you define and run multiple containers together. You will add a Redis container alongside your app — this is how real applications work in production. Create `docker-compose.yml`: ```yaml version: '3.8' services: # Your Node.js application webapp: build: . # Build from the Dockerfile in current directory ports: * "3000:3000" environment: * NODE_ENV=development * APP_NAME=DevOps Network App * APP_VERSION=1.0.0 * REDIS_URL=redis://redis:6379 depends_on: * redis # Start redis before the webapp restart: unless-stopped # Redis cache container # Notice: no Dockerfile needed — we use the official image directly redis: image: redis:7-alpine ports: * "6379:6379" volumes: * redis-data:/data # Persist Redis data between restarts restart: unless-stopped ## Named volume for Redis persistence volumes: redis-data: ``` ```bash ## Stop the container you ran manually docker stop webapp && docker rm webapp ## Start everything with Docker Compose docker compose up -d ## Check both containers are running docker compose ps ## Expected: webapp and redis both showing status running ## View logs from all containers docker compose logs ## View logs from just the webapp, follow in real time docker compose logs -f webapp ## Test the app is still working curl http://localhost:3000 ``` > 📌 **Remember:** In Docker Compose, containers communicate using their service names as hostnames. Your webapp reaches Redis at `redis://redis:6379` — the hostname `redis` resolves to the Redis container automatically. This is Docker's built-in DNS. ### Step 5: Understand Image Layers and Caching This step teaches you the most important Docker optimisation — layer caching. Run these commands and observe how much faster the second build is. ```bash ## Make a small change to your source code echo "// updated" >> src/index.js ## Rebuild the image — time it time docker build -t my-docker-app:v2 . ## Watch the output carefully: ## => CACHED [2/5] WORKDIR /app <- reused from cache ## => CACHED [3/5] COPY package*.json ./ <- reused from cache ## => CACHED [4/5] RUN npm install <- reused from cache (no package change) ## => [5/5] COPY src/ ./src/ <- rebuilt (source code changed) ## Now change package.json (add a new dependency) npm install --save lodash ## Rebuild and observe time docker build -t my-docker-app:v3 . ## This time npm install runs again because package.json changed ## The layers after the change are all rebuilt ## This is why we copy package.json BEFORE source code in the Dockerfile ``` > 🔴 **Common Mistake:** Beginners often write the Dockerfile like this: copy all files first, then run npm install. This means EVERY code change invalidates the npm install cache and npm install runs every single build. Always copy `package*.json` and run `npm install` BEFORE copying your source code. ### Step 6: Push to Docker Hub Docker Hub is the public registry for Docker images — like GitHub for code, but for container images. ```bash ## Create a free account at hub.docker.com ## Then log in from your terminal docker login ## Enter your Docker Hub username and password ## Tag your image with your Docker Hub username ## Format: username/image-name:tag docker tag my-docker-app:v1 YOUR_DOCKERHUB_USERNAME/my-docker-app:v1 docker tag my-docker-app:v1 YOUR_DOCKERHUB_USERNAME/my-docker-app:latest ## Push to Docker Hub docker push YOUR_DOCKERHUB_USERNAME/my-docker-app:v1 docker push YOUR_DOCKERHUB_USERNAME/my-docker-app:latest ## Verify — pull the image from Docker Hub to confirm it was uploaded docker rmi YOUR_DOCKERHUB_USERNAME/my-docker-app:v1 docker pull YOUR_DOCKERHUB_USERNAME/my-docker-app:v1 docker run -d -p 3001:3000 YOUR_DOCKERHUB_USERNAME/my-docker-app:v1 curl http://localhost:3001 ## Expected: Same response — image runs identically from Docker Hub ```

Containerise a Node.js Web Application with Docker

What You'll Learn

Architecture Overview

Problem Solved

Step-by-Step Implementation Guide

Validation & Testing

Skills You'll Master

Curriculum Index

Architecture Overview

Problem Solved

Step-by-Step Implementation Guide

Validation & Testing

Career Impact

Troubleshooting & Lab Guides

How to Troubleshoot a Linux Production Server: A Systematic Approach

Next Modules

Build & Package Management

Containers (Core DevOps Skill)

CI/CD (Automation Pipeline)

Related Guides

What Is AI SRE? How AI Agents Are Changing Incident Response

GitOps Showdown: ArgoCD vs FluxCD for Kubernetes Teams

Platform Engineering 101: Building an Internal Developer Platform with Backstage