How to Run a Docker Container on Your Local Machine

Published Updated

12 min read

This article is a quick, hands-on guide to running Docker locally. It walks through essential CLI commands for managing images and containers (build, pull, run, ps, start/stop, rm/rmi) and shows how to automate image creation with a Dockerfile. You’ll build an image, run a container with port mapping, verify it’s running, and learn tips for environment setup - everything you need to spin up and manage local containers efficiently.


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-image

Then 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 -q
2
39e3c1b91a44d
49f35e15e12c6
57fe72c486b91
6fec2740c5178
798028cf281bb
8fd2d445ddcc3
9ab33eacc8251

docker 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 ps
2CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
3f5d742a79f1b nginx "/docker-entrypoint.…" 11 days ago Up 11 days 0.0.0.0:8080->80/tcp, [::]:8080->80/tcp epic_pasteur

By 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 -q
2f5d742a79f1b
3c7a6d07bebe7
4f7d94c57e38a
535d04aa077e8
60d43e40f304c
769d00efdda9d

docker 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-docker
3# Requires output: "standalone" in next.config.ts (or next.config.js).
4
5ARG NODE_VERSION=24-slim
6
7# Stage 1: install dependencies
8FROM node:${NODE_VERSION} AS dependencies
9WORKDIR /app
10COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* pnpm-workspace.yaml* .npmrc* ./
11RUN --mount=type=cache,target=/root/.npm \
12 --mount=type=cache,target=/usr/local/share/.cache/yarn \
13 --mount=type=cache,target=/root/.local/share/pnpm/store \
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 fi
23
24# Stage 2: build the app in standalone mode
25FROM node:${NODE_VERSION} AS builder
26WORKDIR /app
27COPY --from=dependencies /app/node_modules ./node_modules
28COPY . .
29ENV NODE_ENV=production
30# Uncomment to disable Next.js telemetry during the build:
31# ENV NEXT_TELEMETRY_DISABLED=1
32RUN 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 fi
41
42# Stage 3: run the app
43FROM node:${NODE_VERSION} AS runner
44WORKDIR /app
45ENV NODE_ENV=production
46ENV PORT=3000
47ENV HOSTNAME="0.0.0.0"
48# Uncomment to disable Next.js telemetry at run time:
49# ENV NEXT_TELEMETRY_DISABLED=1
50
51COPY --from=builder --chown=node:node /app/public ./public
52RUN mkdir .next && chown node:node .next
53COPY --from=builder --chown=node:node /app/.next/standalone ./
54COPY --from=builder --chown=node:node /app/.next/static ./.next/static
55
56# Run as the non-root user that ships with the node image
57USER node
58
59# Documents the port the app listens on. It doesn't publish it.
60EXPOSE 3000
61
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 the key=value form. The older ENV key value form still works, but Docker's build checks flag it with a LegacyKeyValueFormat warning.
  • ENV HOSTNAME="0.0.0.0": the server listens on all interfaces inside the container. If it listens only on the container's own 127.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, so docker stop shuts 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, like 24.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_modules
2.next
3.git
4.env*
5npm-debug.log*
6Dockerfile
7.dockerignore

How to Run Dockerfile

To build an image using a Dockerfile, the following steps must be performed:

  1. Create your own Dockerfile or download an existing one
  2. Move the Dockerfile to the project directory in which you want to create the image
  3. Run the command-line tool and change the directory to the project directory
  4. Run the build command 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 ps

The 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:9000

You should get HTTP/1.1 200 OK. If the page doesn't load, read the container logs first:

shell

1docker logs test-app

A 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-image

Stop, 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-app
2docker start test-app

When you're done, remove the container and, if you don't need it anymore, the image:

shell

1docker stop test-app
2docker rm test-app
3docker rmi test-image

For 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 of docker 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 with cd or 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. Run docker ps to 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 with docker rm test-app or choose another name.
  • The container is up, but the page doesn't load and curl says Connection reset by peer: the second number in -p doesn't match the port the app listens on. Check docker logs and fix the mapping, for example -p 9000:3000 instead of -p 9000:80. The same symptom appears when the app listens on 127.0.0.1 inside the container instead of 0.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 images lists the images you have.
  • "/app/.next/standalone": not found during 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, localhost is the container itself. With Docker Desktop, use host.docker.internal instead. 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-image
5 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 --build
2docker compose ps
3docker compose down

Note 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. Add 127.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.

Alex Kondratiev

Alex Kondratiev

Founder and CEO of ITsyndicate. DevOps engineer with 15+ years in cloud infrastructure, Infrastructure as Code, Kubernetes and automation, focused on secure, scalable and resilient systems.

More about Alex

Stay online.
Stay in command.