16.1. Dockerizing a Simple Web App
Table of Contents
From Local App to Dockerized Web Service
In this chapter you will walk through the process of taking a very simple web application that runs on your local machine and turning it into a Dockerized service. The goal is to understand the practical steps from “I have some code” to “I can run it in a container on any machine with Docker installed.”
We will not focus on any specific programming language framework in depth, because the ideas are the same for a small application whether it is written in Node.js, Python, or another common web technology.
Defining the Minimal Web Application
To Dockerize a simple web app, you first need a minimal application that listens on a TCP port and responds to HTTP requests. For example, this might be a small HTTP server that listens on port 8000 and returns “Hello, Docker” when you visit it in a browser.
Before you think about containers, always confirm that your app runs correctly on your development machine without Docker. If your app requires a runtime such as Node.js or Python, or relies on package managers such as npm or pip, make sure you can install dependencies and start the server with a single command like npm start or python app.py.
Always verify that your web app runs correctly on your host before Dockerizing it. Docker will not fix a broken application.
Once you can start the server and see a response in the browser, you are ready to capture this environment and behavior in a container image.
Choosing a Base Image
The Dockerization process starts in your Dockerfile with the choice of a base image. For a simple web app this is usually an official language runtime image. For instance, if your app is in Node.js you might choose node:20-alpine. If it is in Python you might choose python:3.12-alpine.
Your choice affects image size, available tools, and performance. For a small example project, an official language image with a recent tag is usually enough. Alpine based images are often preferred for their smaller size, but they might require extra setup for native dependencies.
You do not need to understand every possible base image at this point, but you must select one that matches the language and runtime that your simple web app needs.
Writing a Basic Dockerfile for the App
With the base image chosen, you can write a minimal Dockerfile that turns your source code into a runnable container. The structure will follow the same basic pattern you learned in the Dockerfile chapters, but here the focus is on expressing your web app’s startup process.
A typical flow for a simple app is:
Start from the chosen base image with a FROM instruction.
Set a working directory inside the container.
Copy the application files into that directory.
Install dependencies inside the container.
Expose the port that the app uses.
Specify the default command or entrypoint that starts the web server.
Each of these steps mirrors something you would normally do on your host machine. The Dockerfile converts these manual steps into an image build recipe.
If your application uses configuration files or static assets such as HTML or CSS, you will usually copy them into the image in the same stage as your source code, so they are available when the container runs.
Building the Image from the Project
Once you have a Dockerfile in the project folder, you can build your first image for the web app. You will use docker build from the root of the project, where the Dockerfile resides, and tag the resulting image with a simple name.
During this build, Docker executes the instructions from your Dockerfile, creating layers at each step. For a small application this process will usually be quick, although dependency installation may still take some time.
It is common to rebuild the image several times as you refine the Dockerfile. For example, you might adjust which files are copied, tweak the working directory, or alter the command that starts the server. Each time you rebuild, Docker will reuse any layers that have not changed, which speeds up the feedback loop.
Running the Web App Container
After a successful build, you can run your containerized web app with docker run. This is where you turn the image into a live container that listens on a port and can be reached from your browser.
Running a web app container always involves two key elements.
First, you must publish or map the container’s internal port to a port on your host, so you can open it in a browser. If your app listens on port 8000 inside the container, you might map it to port 8000 or 8080 on your host.
Second, you must use the correct image tag that you built. If you built an image called simple-web-app, then you run that exact name in your command.
If everything is configured correctly, the container will start, and your web app will respond on the mapped host port just as it did when you ran it directly on the host.
If your web app returns responses on the host but not inside Docker, the first things to check are the port mapping and the port the app is actually listening on inside the container.
Managing Source Code and Changes
When you make changes to the application code, you must decide how those changes reach the running container. For a very simple example that you share or deploy, you will usually rebuild the image and restart the container with the updated image.
For active development, you might use bind mounts to keep the container in sync with your source directory, but that pattern belongs to development workflows more generally. For a small demo web app intended as a teaching project, the simpler approach is to rebuild the image after each set of code changes.
This rebuild process helps reinforce the idea that a container image is a snapshot of your code and dependencies at a point in time. Whenever the code changes, you can create a new snapshot by rebuilding.
Basic Configuration inside the Container
Even very simple web apps often rely on some configuration values, such as the port number, a debug flag, or the environment mode. When Dockerizing the app, you will usually pass these values into the container as environment variables at runtime rather than hardcoding them in the image.
Your Dockerfile should contain the general logic of how the app runs, while docker run arguments such as -e for environment variables allow you to define settings that might change between environments. For a beginner level simple app, this might only mean choosing the port or whether to run in development or production mode.
If your application reads configuration from a .env file or similar mechanism, you can still use that approach, but you need to ensure that the file is present in the container or that you pass equivalent values through Docker when you start the container.
Testing the Dockerized Web App
Once your container is running and the port is mapped, you should test the web app through the browser or with an HTTP client, to ensure it behaves as expected in its containerized form.
The basic checks for a simple project are:
Confirm that you can reach the app using the host port you published.
Verify that the main endpoint returns the expected response.
Observe the logs inside Docker to see startup messages and any errors.
Stop and restart the container to ensure it behaves consistently.
If your app uses static files, templates, or simple routing, verify that each piece works just as it did when running directly on the host. This gives you confidence that the Dockerized version is a faithful representation of your original simple web app.
Sharing and Reusing the Dockerized App
One of the main advantages you gain by Dockerizing even a tiny web application is repeatability. Anyone with Docker installed can pull your image from a registry or build it from your Dockerfile and run the app with a single command.
For a learning project, you may keep the image local. For broader sharing, you would eventually push it to a registry such as Docker Hub under a repository name that others can access. Consumers then do not need any knowledge of the underlying programming language or dependency installation. They only need Docker and the image tag.
This separation of code runtime from the host environment is the central benefit you see clearly when Dockerizing a simple app. The same container can run on different operating systems and machines, and produce the same behavior, as long as Docker itself is available.
Views: 0
Where to Move
Move chapter:
- ☰ 1. Introduction
- ☰ 1.1. What is Docker?
- ☰ 1.2. Why Docker?
- ☰ 1.3. Virtual Machines vs Containers
- ☰ 1.4. When Not to Use Docker
- ☰ 1.5. How Docker Is Used in Real Projects
-
- ☰ 2. Core Concepts
- ☰ 2.1. Images
- ☰ 2.2. Containers
- ☰ 2.3. Docker Engine and Architecture
- ☰ 2.4. Docker Hub and Container Registries
- ☰ 2.5. Tags, Versions, and Digests
-
- ☰ 3. Installing Docker
- ☰ 3.1. Docker on Linux
- ☰ 3.2. Docker on Windows
- ☰ 3.3. Docker on macOS
- ☰ 3.4. Verifying the Installation
- ☰ 3.5. Common Installation Issues
-
- ☰ 4. Your First Docker Container
- ☰ 4.1. Running Your First Container
- ☰ 4.2. Understanding `docker run`
- ☰ 4.3. Interactive vs Detached Mode
- ☰ 4.4. Stopping and Removing Containers
- ☰ 4.5. Listing Containers
-
- ☰ 5. Working with Docker Images
- ☰ 5.1. Pulling Images from Docker Hub
- ☰ 5.2. Listing and Removing Images
- ☰ 5.3. Image Layers Explained
- ☰ 5.4. Image Size Optimization
- ☰ 5.5. Inspecting Images
-
- ☰ 6. Dockerfiles – Building Your Own Images
- ☰ 6.1. What Is a Dockerfile?
- ☰ 6.2. Basic Dockerfile Structure
- ☰ 6.3. Common Instructions (`FROM`, `RUN`, `COPY`, `CMD`, `ENTRYPOINT`)
- ☰ 6.4. Building Images with `docker build`
- ☰ 6.5. Best Practices for Dockerfiles
- ☰ 6.6. Multi-Stage Builds
-
- ☰ 7. Managing Data with Volumes
- ☰ 7.1. Why Containers Are Ephemeral
- ☰ 7.2. Bind Mounts vs Volumes
- ☰ 7.3. Creating and Using Volumes
- ☰ 7.4. Inspecting and Removing Volumes
- ☰ 7.5. Real-World Examples
-
- ☰ 8. Networking in Docker
- ☰ 8.1. Docker Networking Basics
- ☰ 8.2. Bridge Networks
- ☰ 8.3. Port Mapping
- ☰ 8.4. Container-to-Container Communication
- ☰ 8.5. Custom Networks
-
- ☰ 9. Docker Compose
- ☰ 9.1. Why Docker Compose?
- ☰ 9.2. `docker-compose.yml` Structure
- ☰ 9.3. Defining Services, Networks, and Volumes
- ☰ 9.4. Running Multi-Container Applications
- ☰ 9.5. Web App and Database Example
- ☰ 9.6. Docker Compose Best Practices
-
- ☰ 10. Debugging and Monitoring Containers
- ☰ 10.1. Viewing Logs
- ☰ 10.2. Executing Commands in Running Containers
- ☰ 10.3. Inspecting Containers
- ☰ 10.4. Resource Usage
- ☰ 10.5. Common Errors and Fixes
-
- ☰ 11. Security Basics
- ☰ 11.1. Running Containers as Non-Root
- ☰ 11.2. Image Trust and Verification
- ☰ 11.3. Secrets and Environment Variables
- ☰ 11.4. Reducing Attack Surface
- ☰ 11.5. Security Best Practices
-
- ☰ 12. Performance and Optimization
- ☰ 12.1. Reducing Image Size
- ☰ 12.2. Caching and Layer Ordering
- ☰ 12.3. Resource Limits
- ☰ 12.4. Choosing the Right Base Image
-
- ☰ 13. Docker in Development Workflows
- ☰ 13.1. Docker for Local Development
- ☰ 13.2. Hot Reloading with Volumes
- ☰ 13.3. Docker and Git
- ☰ 13.4. Docker in CI/CD Pipelines
- ☰ 13.5. Common Development Patterns
-
- ☰ 14. Deployment Basics
- ☰ 14.1. Running Containers in Production
- ☰ 14.2. Environment Configuration
- ☰ 14.3. Restart Policies
- ☰ 14.4. Logging Strategies
- ☰ 14.5. Basic Scaling Concepts
-
- ☰ 15. Beyond the Basics
- ☰ 15.1. Docker Swarm Overview
- ☰ 15.2. Kubernetes vs Docker
- ☰ 15.3. Container Registries
- ☰ 15.4. When to Move Beyond Docker
-
- ☰ 16. Practical Projects
- ☰ 16.1. Dockerizing a Simple Web App
- ☰ 16.2. Dockerizing a Backend API
- ☰ 16.3. Full-Stack App with Docker Compose
- ☰ 16.4. Common Project Pitfalls
-
- ☰ 17. Troubleshooting and FAQ
- ☰ 17.1. Common Beginner Mistakes
- ☰ 17.2. Docker Command Cheat Sheet
- ☰ 17.3. FAQ
- ☰ 17.4. Useful Resources
-
Comments
Please login to add a comment.
Don't have an account? Register now!