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
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
- A Linux VPS with Docker Engine installed. See Install Docker and Docker Compose.
- A user that can run
dockercommands. - Basic knowledge of images and containers. Docker basics covers the terms.
Create a small app to package
Make a project folder:
mkdir -p ~/hello-app && cd ~/hello-appCreate server.js:
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:
{
"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:
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
/appand 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 ciinstead if your project has apackage-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;
-pdoes that. - `USER node` runs the app as the unprivileged
nodeuser 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:
node_modules
npm-debug.log
.git
.env
*.md
Dockerfile
.dockerignoreThis keeps builds fast and stops secrets in .env or your Git history from ending up inside the image.
Anything copied into an image can be read by anyone who can pull it. Never COPY passwords, API keys or private keys into an image. Pass them at run time instead.
Build and tag the image
From the project folder:
docker build -t hello-app:1.0 .-t hello-app:1.0names 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:
docker image ls hello-appRun and test the container
docker run -d --name hello -p 127.0.0.1:3000:3000 hello-app:1.0
docker logs helloThe log should show Listening on 3000.
Check it works
Request the page from the VPS itself:
curl http://127.0.0.1:3000You should get Hello from Docker. Confirm the app is not running as root:
docker exec hello idThe output should show uid=1000(node). When you are done testing, remove the container:
docker rm -f helloTroubleshooting
- `failed to read dockerfile`: the file is not called exactly
Dockerfile, or you ran the build from a different folder. Use-f path/to/Dockerfileif 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 inCMDor 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
chownit to the app user beforeUSER node.
Next steps
- Make the image smaller and safer: Smaller Docker images with multi-stage builds.
- Share it with your servers: Push images to Docker Hub or GitHub Container Registry.
- Build and host your app on a Linux VPS.
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.
Related guides
Docker & DevOps
Self-host Jellyfin with Docker and hardware transcoding
Install Jellyfin in Docker on a Linux VPS, mount your media library, publish it over HTTPS and switch on hardware transcoding with VAAPI or Intel Quick Sync.
- Intermediate
- Linux VPS
- 6 min read
Docker & DevOps
Deploy a Self-Hosted App with Docker Compose from Scratch
Write a compose.yaml, keep your secrets in .env, start the stack with docker compose up -d, then verify it and update it later without losing data.
- Beginner
- Linux VPS
- 7 min read
Docker & DevOps
Manage secrets and environment variables in Docker Compose
Keep API keys and database passwords out of your compose file using .env files, environment keys and Docker secrets, then confirm containers read them correctly.
- Intermediate
- Linux VPS
- 7 min read