How to Deploy a Docker Web App in 10 Minutes: Complete Beginner’s Guide
Last week, a junior developer on my team spent three days trying to deploy a simple Node.js app to a VPS. He had the right code. He had a server with Docker installed. But he got stuck on Dockerfile syntax, port mapping, and a confusing error about container names. I walked him through it in 20 minutes. This guide is that same walkthrough, written so you can skip the three days and go straight to the 20 minutes.
## The One-Liner: What You Are Building
You will take a working web application, package it into a Docker container, and run it on a server that anyone on the internet can reach.
“`
git clone [your-app]
docker build -t my-web-app .
docker run -d -p 80:3000 –name my-app my-web-app
“`
That is the entire flow. Three commands. Now let me break down what each one does and where things go wrong so you do not spend hours debugging.
## Step 1: Install Docker (If You Have Not Already)
Before you can deploy anything, you need Docker running on your machine. The installer is straightforward.
### For Linux (Ubuntu/Debian)
“`bash
sudo apt update
sudo apt install docker.io -y
sudo systemctl start docker
sudo systemctl enable docker
sudo usermod -aG docker $USER
“`
After the last command, log out and log back in for the group change to take effect. I forgot this step and spent 15 minutes wondering why Docker kept asking for sudo. Every time.
### For macOS and Windows
Download Docker Desktop from the official website. Install it. Open the application. Wait for the Docker icon to appear in your menu bar or system tray. That is it.
Verify it worked:
“`bash
docker –version
docker run hello-world
“`
The `hello-world` container pulls a test image and prints a success message. If you see that, you are ready for the next step.
## Step 2: Create a Dockerfile for Your App
The Dockerfile is a plain-text recipe that tells Docker how to build your application image. Every web app framework has the same basic pattern.
### The Generic Dockerfile Template
“`dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 3000
CMD [“node”, “server.js”]
“`
What each line does:
- `FROM node:18-alpine` — starts from a lightweight Node.js base image (Alpine Linux, about 130MB)
- `WORKDIR /app` — sets the working directory inside the container
- `COPY package*.json ./` — copies your dependency files first (Docker caches this layer so rebuilds are faster)
- `RUN npm install` — installs dependencies
- `COPY . .` — copies the rest of your source code
- `EXPOSE 3000` — documentation that your app listens on port 3000
- `CMD [“node”, “server.js”]` — the command that runs when the container starts
### The Production Gotcha Most Beginners Miss
Docker caches layers. The order of commands in your Dockerfile matters. If you put `COPY . .` before `RUN npm install`, Docker re-installs npm packages every time you change any file. That turns a 10-second rebuild into a 2-minute rebuild.
This is the correct order: copy dependency files first, install, then copy everything else.
### Dockerfile for Python (Flask/FastAPI)
“`dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install –no-cache-dir -r requirements.txt
COPY . .
EXPOSE 5000
CMD [“python”, “app.py”]
“`
Same pattern. Same caching strategy.
## Step 3: Build the Docker Image
Navigate to your project directory (where the Dockerfile lives) and run:
“`bash
docker build -t my-web-app .
“`
The `-t` flag tags your image with a name. The period at the end means “use the current directory as the build context.”
What to watch out for: If your project has a `node_modules` folder or a `.env` file, Docker will copy them unless you create a `.dockerignore` file.
“`dockerignore
node_modules
.env
.git
*.log
“`
Create this file in the same directory as your Dockerfile. It prevents large or sensitive files from being included in the image.
### Common Build Errors and Fixes
| Error | Likely Cause | Fix |
|---|---|---|
| `Cannot find module ‘express’` | `node_modules` not installed during build | Check `COPY package*.json ./` and `RUN npm install` are before `COPY . .` |
| `exec ./entrypoint.sh: no such file or directory` | Line endings are CRLF | Save the file with LF line endings |
| `ERROR: Cannot connect to the Docker daemon` | Docker is not running | Start Docker Desktop or run `sudo systemctl start docker` |
## Step 4: Run the Container
Once the build finishes, run your container:
“`bash
docker run -d -p 80:3000 –name my-app my-web-app
“`
Breaking down the flags:
- `-d` — runs the container in detached mode (in the background)
- `-p 80:3000` — maps port 80 on your host to port 3000 in the container
- `–name my-app` — gives your container a readable name
- `my-web-app` — the image name you used with `-t` in the build step
After this command, open your browser and go to `http://localhost`. Your app should be visible.
### If It Does Not Work
The port mapping might be wrong. If your app listens on port 5000 internally (Flask default), you need `-p 80:5000`. Check your app’s configuration.
Check the logs:
“`bash
docker logs my-app
“`
This shows you the application output. If your app crashed on startup, the error message will be here.
Inspecting a running container:
“`bash
docker ps
docker exec -it my-app sh
“`
The second command opens a shell inside your running container so you can inspect files, check environment variables, or test endpoints manually.
## Step 5: Deploy to a Server
Your app runs locally. Now you need it on the internet.
### Option A: Deploy with Docker Compose (Best for Simple Projects)
Create a `docker-compose.yml` file:
“`yaml
version: ‘3.8’
services:
web:
build: .
ports:
- “80:3000”
environment:
- NODE_ENV=production
restart: unless-stopped
“`
Then on your server:
“`bash
docker-compose up -d
“`
The `restart: unless-stopped` policy is important. If your app crashes or the server reboots, Docker starts the container automatically. Without this, a server reboot means a dead site until someone manually runs `docker start`.
### Option B: Manual Deploy
1. Build the image on your development machine
2. Save it: `docker save my-web-app | gzip > my-web-app.tar.gz`
3. Copy it to the server: `scp my-web-app.tar.gz [email protected]:~`
4. On the server: `gunzip -c my-web-app.tar.gz | docker load`
5. Run: `docker run -d -p 80:3000 –name my-app my-web-app`
I use Option A (Docker Compose), but both work.
## Step 6: Keep Your Container Running
A deployed web app needs maintenance. Here are the three commands you will use most often:
“`bash
# View running containers
docker ps
# View logs in real-time
docker logs -f my-app
# Restart after an update
docker build -t my-web-app . && docker stop my-app && docker rm my-app && docker run -d -p 80:3000 –name my-app my-web-app
“`
The restart command chain is worth memorizing. I alias it in my shell config:
“`bash
alias redeploy=”docker build -t my-web-app . && docker stop my-app && docker rm my-app && docker run -d -p 80:3000 –name my-app my-web-app”
“`
Now a single command rebuilds and redeploys.
You can find pre-built Docker starter templates and Dockerfiles for common frameworks at FreeResource’s DevOps collection.
## The Production Checklist
Before you open your deployed app to real users, go through this list:
- Never run containers as root. Add a `USER node` line to your Dockerfile after `COPY . .` to run as a non-root user
- Use environment variables for secrets. Never hardcode API keys in your Dockerfile. Pass them with `-e` or an `.env` file
- Set memory limits. Add `–memory=”512m”` to your `docker run` command to prevent a memory leak from taking down your server
- Monitor disk space. Docker images and stopped containers accumulate. Run `docker system prune -f` periodically
- Pin your base image version. `FROM node:18-alpine` is reproducible. `FROM node:latest` will break your build when Node 20 drops
## Conclusion
You now have a web application running in a Docker container on your machine, and you know how to deploy it to a server. The entire process — from installing Docker to a running container — takes about 10 minutes once you have the patterns down. The Dockerfile structure, the port mapping, and the restart policy are the three things that matter most. Everything else is debugging.
What to watch out for: Docker caches aggressively. If you change a file and the build does not seem to pick it up, run `docker build –no-cache -t my-web-app .` to force a fresh build. And always check your `.dockerignore` — accidentally including a `.env` file in a public image is a credential leak waiting to happen.
Try deploying one of your existing projects this week. It will take less than an hour, and you will have a portable, reproducible deployment that works on any server.
— David Park, FreeResource.store