Understand Docker once and for all

Images

An image is a template with the instructions for creating a Docker container. An image is usually based on another image. For example, you can build a Node image from an Ubuntu image to run your application. Most of the time you’ll create your own images, which define how your own applications run.

Containers

A container is a running instance of your image. You can create, stop, move and delete a container through the Docker CLI. You can also create volumes and networks.

Volumes

Containers are meant to be stateless, meaning they don’t hold state. You should be able to create and delete containers at any moment. But some kinds of applications do have state and save files locally. Databases are one example, and you can run them inside a Docker container.

However, when you delete the container you lose everything it saved. To avoid that, you can use Volumes to store your container’s data in a defined location that won’t be lost when the container is deleted.

Network

A network is a virtual network Docker creates so containers can talk to each other. They communicate using the container name as the hostname. Anything outside the network can only reach a container if you expose a port.

For example, if your Node.js application is running on port 3000 and you want to reach it from outside the container, you need to expose the container’s port 3000 with the -p flag.

There are a few types of network:

• bridge (default): containers on this network can talk to each other via internal IP, and to the host if you use -p (port mapping).
• host: uses the host’s network. You lose isolation but get better performance.
• none: the container has no network.
• custom: you can create your own networks and segment access.

Registries

A registry is where your images are stored. The main one is Docker Hub, where you’ll find all sorts of images to download.

There are other places to deploy your own Docker images too, such as the Github Container Registry.

Creating your first image

The simplest possible example is an image for a JavaScript Node application, since it doesn’t need a build step.

Just create one more file, Dockerfile, at the project root, and in it you describe the steps to create your application’s container.

# Using the Node base image
FROM node:22-alpine

# Set the working directory inside the container
WORKDIR /app

# Copy package.json and package-lock.json first to take advantage of the cache
COPY package*.json ./

# Install dependencies
RUN npm install --production

# Copy the rest of the code
COPY . .

# Expose the port (if your app uses one, e.g. 3000)
EXPOSE 3000

# Command to run the application
CMD ["npm", "start"]

Each line is easy to follow, there’s not much mystery to it.

1. Set which image should be the base (here it’s a Node image, which is just a Linux distro with Node 22 preinstalled to speed things up).
2. Set the folder where we’ll install our app
3. Copy the package.json files
4. Install the dependencies
5. Copy the rest of the files
6. Start the application

An important tip: since we’re running npm install inside Docker, we don’t need to copy the node_modules folder. So we can create a .dockerignore file

node_modules
*.log

Then, to run the container, we have the command

docker build . -t seuusuario/seuprojeto

The -t parameter is a way to identify your image

That builds the image, and to run it

docker run -p 3000:3000 seuusuario/seuprojeto

If you have another step, such as a build, just add a new step to the Dockerfile

Creating a Dockerfile for more complex applications

The example above covered the basics needed to understand the main commands.

The example below comes from the Next documentation

# syntax=docker.io/docker/dockerfile:1

FROM node:20-alpine AS base

# Install dependencies only when needed
FROM base AS deps
# Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed.
RUN apk add --no-cache libc6-compat
WORKDIR /app

# Install dependencies based on the preferred package manager
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./
RUN \
  if [ -f yarn.lock ]; then yarn --frozen-lockfile; \
  elif [ -f package-lock.json ]; then npm ci; \
  elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm i --frozen-lockfile; \
  else echo "Lockfile not found." && exit 1; \
  fi


# Rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

# Next.js collects completely anonymous telemetry data about general usage.
# Learn more here: https://nextjs.org/telemetry
# Uncomment the following line in case you want to disable telemetry during the build.
# ENV NEXT_TELEMETRY_DISABLED=1

RUN \
  if [ -f yarn.lock ]; then yarn run build; \
  elif [ -f package-lock.json ]; then npm run build; \
  elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm run build; \
  else echo "Lockfile not found." && exit 1; \
  fi

# Production image, copy all the files and run next
FROM base AS runner
WORKDIR /app

ENV NODE_ENV=production
# Uncomment the following line in case you want to disable telemetry during runtime.
# ENV NEXT_TELEMETRY_DISABLED=1

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public

# Automatically leverage output traces to reduce image size
# https://nextjs.org/docs/advanced-features/output-file-tracing
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000

ENV PORT=3000

# server.js is created by next build from the standalone output
# https://nextjs.org/docs/pages/api-reference/config/next-config-js/output
ENV HOSTNAME="0.0.0.0"
CMD ["node", "server.js"]

Building the Next image is split into 3 stages: Deps, Builder and Runner.

1. First it sets the base image for the Dockerfile, with the specific Node.js version to use
2. Deps: downloads the project’s dependencies
3. Builder: copies the files downloaded in the previous step and builds the application
4. Runner: copies the files from the previous step and runs the application. Note that it creates a non-root user to make the application more secure

This example uses multi-stage build, which keeps development dependencies out of the final version, makes better use of the cache and shrinks the final image. Docker caches each build stage, so with this Dockerfile you can reuse many layers during the build. For example, if your code doesn’t add any new dependency, it won’t need to download them again to create the container: that stage gets reused.

Main commands

• docker ps: lists all running containers
• docker ps -a: lists all containers, including stopped ones
• docker exec -it {tag|id}: runs a command inside the container
• docker logs {tag|id}: shows a container’s logs, useful for finding errors
• docker stop {tag|id}: stops a container
• docker rm {tag|id}: removes a container you no longer use
• docker build -t <nome>:<tag> .: builds a container image from a Dockerfile and adds a tag
• docker push <repo>:<tag>: pushes the image to a registry
• docker pull <imagem>: downloads an image from Docker Hub
• docker-compose up -d: starts the images of a docker compose file in the background
• docker-compose down: stops the images of a docker compose file
• docker-compose logs -f: shows the logs of all images
• docker-compose ps: lists the services

GPT is your best friend

LLMs are very good at generating Dockerfiles and docker-compose files. When in doubt, it’s worth asking a tool for help, whether to explain a feature or to help you build your own images.

Images take up a lot of space

We tend to ignore image size, but images usually take up a fair amount of space depending on the project. One tip is the command

docker image prune

It deletes every image not in use on your machine, so be careful when you run it.

Another command that frees up a lot of disk space is:

docker system prune

It deletes all unused containers, networks, images and cache.

Which image should you choose?

Images come in several versions. Most of the time the alpine version is the recommended one, especially for Node.js, because it uses a lighter Linux distro. There’s a more detailed explanation in the official documentation

Namespaces

A namespace is a Linux feature whose job is to “lie” to the process, so the process thinks it’s running alone on the machine. Docker uses several namespaces to isolate a container. This matters because every system resource is global. For JS developers, it’s a similar idea to using a var versus a let variable.

Some namespaces Docker creates:

• PID: inside the container it will always have PID 1
• NET: each container has its own network layer, so each container can have its own isolated IP
• MNT: controlled mount points, each container can only access the directories Docker exposes
• UTS: lets the container have its own hostname

Cgroups

This is another Linux feature Docker uses to limit the computing resources of processes. The goal is to cap how many CPU cores, how much memory, disk and network each container can use.

One thing you can try on Linux is creating a cgroup yourself.

1. Create a new cgroup

sudo mkdir /sys/fs/cgroup/meu-grupo

2. Set a memory limit

echo 52428800 | sudo tee /sys/fs/cgroup/meu-grupo/memory.max

3. Add a process to the cgroup

sleep 1000 & echo $!

With the PID from the last command

echo <PID> | sudo tee /sys/fs/cgroup/meu-grupo/cgroup.procs

Done! To test it you can run a stress test and check that the limits actually took effect.

Docker manages all of this for you in a simpler way. A practical example is running the command:

docker run -m 512m --cpus="1" ubuntu

Here we limit memory to 512m and the number of cores to 1.

Linux vs Windows vs MacOS

If you look closely, all of these commands are Linux-only. So Docker only runs truly natively on Linux. For it to work on other systems, the standard approach is to create a Linux virtual machine so the Linux-only commands can run there.