Working with Docker sometimes requires running containers not only on servers but also on a local machine. Below, we will look at how to run a Docker container on the local machine and how to use a Dockerfile.
The short version: open a terminal in the folder with your Dockerfile, build an image, and start a container from it with the app's port published:
shell
1docker build -t test-image .2docker run -d -p 9000:3000 --name test-app test-imageThen open http://localhost:9000. The dot at the end of docker build is the build context, and -p 9000:3000 connects port 9000 on your machine to port 3000 inside the container. Use the port your app actually listens on. The rest of this guide explains each step, gives you a working Dockerfile, and covers the errors you're most likely to hit.
Before you start, make sure Docker is installed. On macOS and Windows that's usually Docker Desktop. It runs your containers inside one lightweight Linux virtual machine that it manages for you, and Docker Desktop for Linux does the same. Docker Engine installed directly on Linux runs containers on the host itself. Either way, a container isn't a virtual machine of its own: it's an isolated environment for your app's processes. Run docker version to check that both the client and the server respond.
Frequently Used Commands
First, let's review available commands for creating, managing, and running images and containers.
docker images: returns all available Docker images. The name, tag, and size will be shown for each one.
If the -q flag is set, the command will only show IDs without detailed information. This option is helpful if the resulting list is passed to the next command using the pipe. For example, a user wants to remove all images. It can get a list of their IDs (as shown in the example below) and pass it to the rmi command.
Example:
shell
1docker images -q2
39e3c1b91a44d49f35e15e12c657fe72c486b916fec2740c5178798028cf281bb8fd2d445ddcc39ab33eacc8251docker build: builds an image with specified parameters and flags.
Example:
shell
1docker build -t <image-name>:<image-tag> .The last argument is required. It's the build context: the folder (or URL) whose files the Dockerfile can use in COPY and ADD. A dot means the current directory. Without it, the command stops with 'docker buildx build' requires 1 argument.
docker pull: downloads an image from a remote source to your local machine.
Example:
shell
1docker pull <image-name>docker run: runs a new container from the selected image. It also allows you to configure additional options and run configurations, like running mode or port mapping.
Example:
shell
1docker run -d -p 8080:80 <image-name>The -d flag allows the user to launch the container in the background (the so-called “detached mode”). If it is successfully launched, the command-line tool returns the ID and then the terminal prompt. The -p flag publishes a container port on the host: -p 8080:80 sends traffic from port 8080 on your machine to port 80 inside the container. The first number is the host port, the second is the port the app listens on in the container.
EXPOSE in a Dockerfile doesn't do this for you. It only documents which port the app uses, so you still need -p (or -P, which publishes all exposed ports to random host ports). More on that in our guide on how to expose a port in a Docker container.
docker ps : It allows you to view a list of containers, as well as detailed information about each of them (ID, name, status, ports).
Example:
shell
1docker ps2CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES3f5d742a79f1b nginx "/docker-entrypoint.…" 11 days ago Up 11 days 0.0.0.0:8080->80/tcp, [::]:8080->80/tcp epic_pasteurBy default, only running containers will be shown. To view the full list, the user needs to add the -a flag. With the -q flag, the command will only show container IDs without detailed information. This option is useful if the resulting list of containers is passed to the next command using the pipeline. For example, a user wants to start all containers. It can get a list of their IDs (as shown in the example below) and pass it to the docker start container command.
Example:
shell
1docker ps -a -q2f5d742a79f1b3c7a6d07bebe74f7d94c57e38a535d04aa077e860d43e40f304c769d00efdda9ddocker start <container-names-or-ids>: It is used to start the existing container(s).
It is possible to start them all at once by getting a list of them with the additional ps command using the pipeline.
Example:
shell
1docker start $(docker ps -a -q)docker stop <container-name-or-id> : It is used to stop running container(s).
It is possible to stop all containers at once by getting a list of them with the additional ps command using the pipeline.
Example:
shell
1docker stop $(docker ps -q)docker rm <container-name> : It is used to remove selected container(s). It only removes stopped containers: stop the container first or use docker rm -f.
It is possible to remove all containers at once by getting a list of them with the additional ps command.
Example:
shell
1docker rm $(docker ps -a -q)docker rmi <image-name> : Remove selected image(s). Docker won't remove an image that a container still uses, even a stopped one, until you remove that container.
It is possible to remove all images at once by using the additional images command to get a list of them.
Example:
shell
1docker rmi $(docker images -q)Careful with the $(...) versions: they act on every container or image on your machine, including ones from other projects. To limit them to containers created from one image, add a filter:
shell
1docker stop $(docker ps -q --filter ancestor=test-image)2docker rm $(docker ps -a -q --filter ancestor=test-image)For more commands, such as docker exec, volumes, and cleanup, see our Docker commands cheat sheet.
Dockerfile
The software development and deployment process often requires building new images repeatedly. This process may be automated using the so-called Dockerfile.
A Dockerfile is a regular text file that contains a set of commands (a script) for building an image.
Dockerfile example. It builds and runs a Next.js app and follows the official with-docker example from the Next.js repository. It's a multi-stage build: one stage installs dependencies, the next one builds the app, and the last one copies only what's needed to run it, so the final image doesn't carry the build tools and source code:
dockerfile
1# Based on the official Next.js example:2# https://github.com/vercel/next.js/tree/canary/examples/with-docker3# Requires output: "standalone" in next.config.ts (or next.config.js).4
5ARG NODE_VERSION=24-slim6
7# Stage 1: install dependencies8FROM node:${NODE_VERSION} AS dependencies9WORKDIR /app10COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* pnpm-workspace.yaml* .npmrc* ./11RUN 1213 \14 if [ -f package-lock.json ]; then \15 npm ci --no-audit --no-fund; \16 elif [ -f yarn.lock ]; then \17 corepack enable yarn && yarn install --frozen-lockfile --production=false; \18 elif [ -f pnpm-lock.yaml ]; then \19 corepack enable pnpm && pnpm install --frozen-lockfile; \20 else \21 echo "No lockfile found." && exit 1; \22 fi23
24# Stage 2: build the app in standalone mode25FROM node:${NODE_VERSION} AS builder26WORKDIR /app27COPY /app/node_modules ./node_modules28COPY . .29ENV NODE_ENV=production30# Uncomment to disable Next.js telemetry during the build:31# ENV NEXT_TELEMETRY_DISABLED=132RUN if [ -f package-lock.json ]; then \33 npm run build; \34 elif [ -f yarn.lock ]; then \35 corepack enable yarn && yarn build; \36 elif [ -f pnpm-lock.yaml ]; then \37 corepack enable pnpm && pnpm build; \38 else \39 echo "No lockfile found." && exit 1; \40 fi41
42# Stage 3: run the app43FROM node:${NODE_VERSION} AS runner44WORKDIR /app45ENV NODE_ENV=production46ENV PORT=300047ENV HOSTNAME="0.0.0.0"48# Uncomment to disable Next.js telemetry at run time:49# ENV NEXT_TELEMETRY_DISABLED=150
51COPY /app/public ./public52RUN mkdir .next && chown node:node .next53COPY /app/.next/standalone ./54COPY /app/.next/static ./.next/static55
56# Run as the non-root user that ships with the node image57USER node58
59# Documents the port the app listens on. It doesn't publish it.60EXPOSE 300061
62CMD ["node", "server.js"]This Dockerfile needs the Next.js standalone output. Add it to next.config.ts (or next.config.js):
typescript
1const nextConfig = {2 output: "standalone",3};4
5export default nextConfig;With it, next build creates a .next/standalone folder with a minimal server.js, and the last stage starts it with node server.js. Without it, the build fails at the COPY of /app/.next/standalone with a not found error.
A few lines in this file are worth knowing about:
ENV NODE_ENV=production: use thekey=valueform. The olderENV key valueform still works, but Docker's build checks flag it with aLegacyKeyValueFormatwarning.ENV HOSTNAME="0.0.0.0": the server listens on all interfaces inside the container. If it listens only on the container's own127.0.0.1, a published port can't reach it.CMD ["node", "server.js"]: the exec form. Node.js runs as the main process and gets the stop signal directly, sodocker stopshuts it down cleanly. With the shell form (CMD node server.js), the app runs under a shell that doesn't pass signals on.EXPOSE 3000: documents the port. It doesn't publish it.USER node: the app runs as the non-root user that comes with the official Node.js image.ARG NODE_VERSION=24-slim: Node.js 24 is an LTS release. Pin an exact version, like24.22.2-slim, if you need repeatable builds. This setup was tested with Docker 29.4 and Next.js 16.
Add a .dockerignore file next to the Dockerfile, so your local node_modules, build output, and .env files don't end up in the build context:
shell
1node_modules2.next3.git4.env*5npm-debug.log*6Dockerfile7.dockerignoreHow to Run Dockerfile
To build an image using a Dockerfile, the following steps must be performed:
- Create your own Dockerfile or download an existing one
- Move the Dockerfile to the project directory in which you want to create the image
- Run the command-line tool and change the directory to the project directory
- Run the
buildcommand with the required flags and parameters
In this case, the build command automatically uses the Dockerfile.
It looks for a file named Dockerfile in the root of the build context. If yours has another name or lives somewhere else, point to it with -f:
shell
1docker build -t test-image -f Dockerfile.dev .Local Machine
Using the commands described above, running containers on a local machine will be very easy.
Download the Dockerfile or create one yourself, then move it to the project directory.
Using the command line, build an image:
shell
1docker build -t test-image .Run a new container using the created image:
shell
1docker run -d -p 9000:3000 --name test-app test-image-d runs the container in the background, --name gives it a name you can use instead of the ID, and -p 9000:3000 maps port 9000 on your machine to port 3000, where the Next.js server listens (that's what EXPOSE 3000 and PORT=3000 in the Dockerfile say). Want to watch the logs in your terminal instead? Leave out -d, and press Ctrl+C to stop the container.
Check the list of containers to make sure that the required one has been created and launched:
shell
1docker psThe STATUS column should say Up, and PORTS should show 0.0.0.0:9000->3000/tcp. Now open http://localhost:9000 in a browser, or check it from the terminal:
shell
1curl -I http://localhost:9000You should get HTTP/1.1 200 OK. If the page doesn't load, read the container logs first:
shell
1docker logs test-appA healthy Next.js container prints Ready and the address it listens on.
Configure the environment if your app needs it. Pass single variables with -e NAME=value or a whole file with --env-file, for example docker run -d -p 9000:3000 --env-file .env --name test-app test-image. Keep secrets out of the image itself: that's why .env* is in the .dockerignore above.
These steps create an image named test-image and a container named test-app. We mapped container port 3000 to port 9000 on the Docker host, which here is your own machine. The same image runs unchanged on a Linux server or on any cloud service that runs containers. In the future, the created container can be stopped and started again with the stop and start commands.
By default, -p 9000:3000 publishes the port on all network interfaces, so other devices on your network can reach it too. To keep it local to your machine, bind it to 127.0.0.1:
shell
1docker run -d -p 127.0.0.1:9000:3000 --name test-app test-imageStop, restart, and remove the container
docker stop stops the container but keeps it, so you can start it again later with the same settings:
shell
1docker stop test-app2docker start test-appWhen you're done, remove the container and, if you don't need it anymore, the image:
shell
1docker stop test-app2docker rm test-app3docker rmi test-imageFor quick tests, add --rm to docker run. Docker then removes the container as soon as it stops, so there's nothing to clean up afterwards.
Common errors and how to fix them
'docker buildx build' requires 1 argument: you left out the build context. Add.at the end ofdocker build.failed to read dockerfile: open Dockerfile: no such file or directory: you're not in the folder with the Dockerfile. Go to that folder withcdor point to the file with-f.Bind for 0.0.0.0:9000 failed: port is already allocated: another container already uses host port 9000. Rundocker psto see which one, stop it, or pick another host port, like-p 9001:3000. If a non-Docker app holds the port, the message is different, but the fix is the same.The container name "/test-app" is already in use: a container with that name already exists, maybe a stopped one. Remove it withdocker rm test-appor choose another name.- The container is up, but the page doesn't load and
curlsaysConnection reset by peer: the second number in-pdoesn't match the port the app listens on. Checkdocker logsand fix the mapping, for example-p 9000:3000instead of-p 9000:80. The same symptom appears when the app listens on127.0.0.1inside the container instead of0.0.0.0. pull access denied for test-imag, repository does not exist: Docker didn't find the image locally and tried to pull it from Docker Hub. Usually it's a typo in the image name.docker imageslists the images you have."/app/.next/standalone": not foundduring the build:output: "standalone"is missing from your Next.js config.- The app can't reach a database or API running on your machine: inside a container,
localhostis the container itself. With Docker Desktop, usehost.docker.internalinstead. See how to connect to the Docker host from a container for Linux and other setups.
Run it with Docker Compose
Once you have more than one container, or simply get tired of retyping flags, describe them in a compose.yaml file next to the Dockerfile:
yaml
1services:2 web:3 build: .4 image: test-image5 ports:6 - "9000:3000"Then build and start everything with one command, check it, and stop and remove it with another:
shell
1docker compose up -d --build2docker compose ps3docker compose downNote the space in docker compose. That's the current Compose, written in Go, and Docker Desktop includes it. The hyphenated docker-compose command is the old Python-based Compose v1.
Wrapping up
Sometimes, you may need to run Docker locally on your machine.
You must create an appropriate image using the build command to do this. To automate and simplify this process, you can use the Dockerfile, which contains a set of commands for creating an image. You can create it yourself if there is no ready-made Dockerfile suitable for the project. Run build from the directory with the Dockerfile and don't forget the . at the end, or point to the Dockerfile with -f.
When the image is successfully created, you should run it in a dedicated container using the run command. Then check it with docker ps and docker logs, and open the published port in your browser.
If you want to reach the app from your machine, publish its port with
-p HOST_PORT:CONTAINER_PORT, where the container port is the one the app listens on. Add127.0.0.1:in front of the host port to keep it private to your machine.
When one machine isn't enough anymore and these containers need to run in production with scaling, rolling updates, and monitoring, the usual next step is Kubernetes. If you'd like help getting there, take a look at our Kubernetes consulting services.
