Write a Dockerfile and build your first image

A step-by-step Dockerfile tutorial. Write FROM, RUN, COPY and CMD instructions for a small web app, add a .dockerignore, build and tag the image on your VPS and test the container.

  • Beginner
  • Linux VPS
  • 5 min read

By RunRacks Team · Published

Official images cover databases and popular apps, but your own code needs its own image. A Dockerfile is a short text file that lists the steps to build that image. This guide writes a Dockerfile for a small Node.js web app, builds it on your VPS and runs it, explaining each instruction on the way. The same pattern works for Python, PHP or Go.

Before you start

Create a small app to package

Make a project folder:

Terminal
mkdir -p ~/hello-app && cd ~/hello-app

Create server.js:

Text
const http = require("http");
const port = process.env.PORT || 3000;
http.createServer((req, res) => {
  res.end("Hello from Docker\n");
}).listen(port, () => console.log(`Listening on ${port}`));

And a minimal package.json:

JSON
{
  "name": "hello-app",
  "version": "1.0.0",
  "main": "server.js",
  "scripts": { "start": "node server.js" }
}

Write the Dockerfile

Create a file named Dockerfile, with no extension, in the same folder:

Text
FROM node:22-alpine

WORKDIR /app

COPY package*.json ./
RUN npm install --omit=dev

COPY . .

ENV PORT=3000
EXPOSE 3000

USER node

CMD ["node", "server.js"]

What each line does:

  • `FROM node:22-alpine` picks the base image: Node.js 22 on Alpine Linux, which is small. Always pin a version tag rather than latest.
  • `WORKDIR /app` creates /app and makes it the current directory for the following steps.
  • *`COPY package.json ./`** copies only the dependency files first. This matters for caching, explained below.
  • `RUN npm install --omit=dev` runs a command at build time and saves the result as a layer. Use npm ci instead if your project has a package-lock.json.
  • `COPY . .` copies the rest of your code into /app.
  • `ENV PORT=3000` sets a default environment variable. You can override it at run time with -e.
  • `EXPOSE 3000` documents the port the app uses. It does not publish the port; -p does that.
  • `USER node` runs the app as the unprivileged node user that the official image provides, rather than root.
  • `CMD ["node", "server.js"]` is the command the container runs when it starts. Use the JSON array form so signals such as stop requests reach your app directly.

Why the order of instructions matters

Docker caches each layer. When you rebuild, it reuses every layer up to the first instruction whose inputs changed. Copying package.json and installing dependencies before copying the code means a code change does not trigger a full npm install. Builds go from minutes to seconds.

Put the instructions that change least at the top and the ones that change most at the bottom.

Add a .dockerignore file

COPY . . sends everything in the folder to the build. Exclude what does not belong in the image with a .dockerignore file:

Text
node_modules
npm-debug.log
.git
.env
*.md
Dockerfile
.dockerignore

This keeps builds fast and stops secrets in .env or your Git history from ending up inside the image.

Build and tag the image

From the project folder:

Terminal
docker build -t hello-app:1.0 .
  • -t hello-app:1.0 names and tags the image.
  • . is the build context, the folder Docker reads files from.

The build prints each step. On a rebuild with no changes, every step shows CACHED.

List your new image:

Terminal
docker image ls hello-app

Run and test the container

Terminal
docker run -d --name hello -p 127.0.0.1:3000:3000 hello-app:1.0
docker logs hello

The log should show Listening on 3000.

Check it works

Request the page from the VPS itself:

Terminal
curl http://127.0.0.1:3000

You should get Hello from Docker. Confirm the app is not running as root:

Terminal
docker exec hello id

The output should show uid=1000(node). When you are done testing, remove the container:

Terminal
docker rm -f hello

Troubleshooting

  • `failed to read dockerfile`: the file is not called exactly Dockerfile, or you ran the build from a different folder. Use -f path/to/Dockerfile if it lives elsewhere.
  • `COPY failed: file not found in build context`: the file is outside the build folder or listed in .dockerignore.
  • Every build reinstalls dependencies: you copy the whole project before RUN npm install. Copy the package files first, as shown above.
  • The container exits straight away: read docker logs hello. A typo in CMD or a missing file is the usual cause.
  • `EACCES` or permission errors at run time: the app tries to write to a folder owned by root. Create it in the Dockerfile and chown it to the app user before USER node.

Next steps

Was this guide helpful?

Still stuck?

Ask RunRacks AI for a quick answer, or open a ticket and our team will take a look at your server.