Containers and Docker
through the F1 lens.

Stage 01 foundations

Why containers exist

The problem

The concept

The evolution went like this: first, one application per physical server, with manual configuration; then virtualization, which divides a server into several VMs; finally, containers, which isolate only the processes and share the kernel of the host operating system. The focus shifts from the machine to the application.

A container is a set of processes isolated at the operating system level. On Linux, two kernel mechanisms make this possible:

• Namespaces control what the process can see. There is one type for each resource: PID (the process list), network (interfaces and routing tables), mount (filesystem), UTS (hostname), IPC (communication between processes, such as queues and shared memory) and user (user and group identification).
• Cgroups (control groups) measure and limit resources, such as CPU, memory and disk input and output operations. A container that tries to consume more than planned is held to what was defined, and this protects the others.

The container shares the host kernel. That is why it usually starts faster and uses fewer resources than a VM. This sharing also means that a container is neither a synonym for a virtual machine nor an absolute security barrier: protection depends on the configuration of the runtime and the host (Stage 09 goes deeper into this).

Docker is the tool that made containers accessible: it standardizes how to package, distribute and run. A packaged application runs the same way on your laptop, on the test server, in production or in the cloud, which eliminates the "it works on my machine" problem.

Key concepts

Worked examples

# Downloads the image, creates a container, runs its process and shows the output.
$ docker run --name primeiro-container hello-world
 
# Also lists containers that have already finished.
$ docker ps --all
 
# Shows the container's complete metadata in JSON.
$ docker inspect primeiro-container
 
# Removes the container that has already ended.
$ docker rm primeiro-container
 
# expected output
Hello from Docker!
...
CONTAINER ID   IMAGE         STATUS                     NAMES
abc123         hello-world   Exited (0) ...             primeiro-container

Essential commands for this stage

Hands-on

1. Run docker run --name fundamentos hello-world.
2. Run docker ps and then docker ps --all.
3. Note that the container appears only in the second command.
4. Inspect its status with docker inspect --format '{{.State.Status}} {{.State.ExitCode}}' fundamentos.
5. The expected output is exited 0. Remove it with docker rm fundamentos.
6. Run docker run --rm alpine ps and note that the only process listed has PID 1: the container does not see the host's processes.
7. Run docker run --rm --hostname demo alpine hostname and then docker run --rm alpine hostname. Note that the name changes from one container to another, and neither of them is the name of your computer.

Stage 02 image + runtime

Image, container and lifecycle

The problem

The concept

An image gathers the filesystem and the metadata needed to start a process. It is immutable and made of reusable layers. A container adds a temporary writable layer on top of the image and runs the configured command. The same image can give rise to several independent containers, and removing a container does not remove the image.

The basic flow is:

1. docker pull downloads an image from a registry, such as Docker Hub.
2. docker run creates and starts a container from the image.
3. docker stop requests that the process stop.
4. docker start restarts the same container.
5. docker rm removes the container.
6. docker rmi removes an image that is not in use.

Tags such as node:lts-alpine or nginx:alpine identify variants. Avoid depending on latest in environments that need reproducibility, since the content associated with the tag can change. An explicit tag (for example, the major version) helps, although a tag can still be moved by the maintainer. When strong immutability is required, a digest (image@sha256:...) identifies the image content precisely.

A public registry lets you discover and download public images, often without authentication. Docker Hub is the best-known example and hosts both free software (Nginx, Node.js) and system bases (Ubuntu, Alpine). A private registry restricts access to internal images and requires authentication with docker login. Companies usually combine the two: common images come from the public registry, and the images that contain proprietary code stay in internal repositories, accessible only to those who are authorized. Private registry options include Amazon Elastic Container Registry (ECR), Azure Container Registry (ACR), Google Artifact Registry (which replaced the old Google Container Registry), and self-hosted solutions such as Harbor and JFrog Artifactory. They integrate with CI/CD pipelines to automate the creation and distribution of images.

Use public images only when they are trusted and verified, and keep in private repositories everything that is sensitive or internal.

Before pushing an image, the local name must receive a tag that includes the registry address, the namespace and the version.

A container is the image, in read-only layers, plus a thin writable layer on top. Everything the container writes goes to that layer.

Several containers from the same image share the read-only layers, and each one has its own writable layer. Removing a container deletes only its layer.

Key concepts

Worked examples

# Explicitly downloads the Alpine variant of the official image.
$ docker pull nginx:alpine
 
# Creates a container in the background.
# The name makes the next commands easier.
# Port 8080 on the host is forwarded to port 80 in the container.
$ docker run --detach --name pagina --publish 8080:80 nginx:alpine
 
# Lists the running containers.
$ docker ps
 
# Queries the server inside the container through the port published on the host.
$ curl http://localhost:8080
 
# Shows the messages produced by the Nginx process.
$ docker logs pagina
 
# Runs a command in a container that is already running.
$ docker exec pagina nginx -v
 
# Stops and removes the container.
$ docker stop pagina
$ docker rm pagina
 
# expected output
CONTAINER ID   IMAGE          PORTS                  NAMES
abc123         nginx:alpine   0.0.0.0:8080->80/tcp   pagina
<!DOCTYPE html>
<title>Welcome to nginx!</title>
nginx version: nginx/...

Essential commands for this stage

Hands-on

1. Start nginx:alpine on port 8080 with the name ciclo.
2. Confirm the response with curl -I http://localhost:8080. The first line of the output should be HTTP/1.1 200 OK.
3. Stop the container and repeat the curl. The connection should fail, with a message such as curl: (7) Failed to connect to localhost port 8080.
4. Run docker start ciclo and confirm that the page is back (HTTP/1.1 200 OK again).
5. Confirm that no needed data lives only inside the container. Then remove it with docker rm --force ciclo. This option stops and removes the instance immediately, so it should not be used without checking the target.
6. Run docker images nginx and note that the image is still available even with no container: removing the container does not remove the image.
7. Make sure the file nota.txt exists in the current folder (echo "ola do host" > nota.txt). Create a container with docker run --detach --name caixa alpine sleep 300, copy the file into it with docker cp nota.txt caixa:/tmp/nota.txt, read it with docker exec caixa cat /tmp/nota.txt (the output is ola do host) and remove the container with docker rm --force caixa. Then create another one with the same docker run and run docker exec caixa cat /tmp/nota.txt again. The expected output now is cat: can't open '/tmp/nota.txt': No such file or directory, because the file stayed in the writable layer of the container that was removed. Remove the second container with docker rm --force caixa.

Stage 03 repeatable build

Dockerfile as a reproducible recipe

The problem

The concept

The Dockerfile is a text file that describes, declaratively, the step-by-step to build an image: you say what you want and Docker builds it. The docker build command reads the Dockerfile and a folder of files (the build context, given at the end of the command, normally .) and produces an image.

The essential instructions are:

• FROM: chooses the base image. Example: FROM node:lts-alpine means "start from the Node image on an Alpine base".
• WORKDIR: sets the directory used by the following instructions, to avoid long paths in each command. Example: WORKDIR /app.
• COPY: copies files from the build context into the image. Example: COPY . /app copies everything in the current directory to /app.
• RUN: executes an action during the build (installing dependencies, creating folders) and records the result as a new layer. Example: RUN npm install.
• CMD: sets the default command executed when the container starts. Example: CMD ["node", "index.js"].
• EXPOSE: documents the port used by the application. It does not publish the port on the host.

RUN happens at build time and records a layer in the image. CMD happens at runtime, when a container is started. Mixing these two moments is a common source of error. CMD can be replaced on the docker run command line.

The order of the instructions matters because Docker caches the result of each one. If you change something at the top, everything below is rebuilt; if you change only the CMD, the rest is reused. Stage 04 explores this rule.

The main process and signals. The process defined by CMD is PID 1 of the container. On Linux, PID 1 does not get the default signal handling: a signal such as SIGTERM or SIGINT, which normally ends a program, is ignored if the program has not installed a handler for it, and Node.js without an explicit handler falls into this case. The result is that Ctrl+C in the terminal may not end the container, and docker stop waits for the deadline (10 seconds by default) and then sends SIGKILL. The --init option of docker run (and init: true in Compose) puts a small init process as PID 1, which passes the signals on to your program. That is why the API examples in this guide use --init. To end a container in the foreground, use Ctrl+C in its terminal or, in another terminal, docker stop name. The exit code 137 that results from a forced shutdown by SIGKILL does not, by itself, indicate lack of memory; Stage 11 shows how to tell the two cases apart.

Key concepts

Worked examples

// Imports only the HTTP module included in Node.js.
const http = require("node:http");
 
// Reads the port from the environment and keeps 3000 as the local default.
const port = Number(process.env.PORT || 3000);
 
// Creates a simple JSON response for any request.
const server = http.createServer((_request, response) => {
  response.writeHead(200, { "content-type": "application/json" });
  response.end(JSON.stringify({ status: "ok" }));
});
 
// Listens on all of the container's interfaces.
server.listen(port, "0.0.0.0", () => {
  console.log(`Servidor disponível na porta ${port}`);
});

Essential commands for this stage

Hands-on

1. Create the two files from the example in an empty directory.
2. Build minha-api:1.0 and run the container with --init, as in the example.
3. In another terminal, confirm the response with curl http://localhost:3000 and end the container with docker stop minha-api (or Ctrl+C in its terminal). Confirm with docker ps that port 3000 is free.
4. Change the response value to {"status":"pronto"}.
5. Rebuild with the tag minha-api:1.1.
6. Run docker images minha-api and note that the versions are distinct images.
7. Run docker run --rm minha-api:1.1 node -e "console.log('outro comando')" and note that the CMD was replaced without rebuilding anything.

Stage 04 optimization

Layers, cache, minimal images and multistage build

The problem

The concept

Docker stores the result of each instruction as a layer. If it finds a layer identical to one it has already built, it reuses it (it appears as CACHED in the build). This only happens while the instruction and its input files do not change, and, when a layer is invalidated, all the following ones are too. That is why dependency files should be copied before the rest of the code: first copy the minimum needed to install the dependencies, run the installation and only then copy the rest of the project.

The same logic applies to any package manager (npm, pip, yarn, pnpm, composer); only the file names change. Also use the mode that respects the lockfile (npm ci, --frozen-lockfile) for predictable builds.

A multistage build uses a tool-rich stage to build the artifact and a smaller final stage to run it. You open a FROM for the build, install dependencies and compile, and then open a new, clean FROM, copying only the result with COPY --from=. Build tools, development node_modules and temporary files do not go into the final image.

Common base image variants:

• slim: reduced Debian base, with good compatibility. It is a middle ground between weight and convenience.
• alpine: minimal distribution (a few megabytes) that uses musl instead of glibc and the apk package manager. Things that usually come by default are missing, such as bash and curl; install them with apk add when you need them. It may require adjustments for native dependencies.
• distroless: contains only what is needed to run the application, with no shell, no package manager and no utilities. It is excellent for production from a security standpoint, but demands a very well made build and normally depends on multistage.

Smaller is not always better. For development, or while you do not yet know what you will need, start with a more complete image and "trim it down" after everything works. For production, when you already know exactly what runs, alpine or slim reduce the final size, the transfer time and the attack surface. The base must be compatible, up to date and sufficient to diagnose and run the application.

The multistage example below copies only /app/dist to the runtime. This only works when dist is self-sufficient or when the application uses only native Node modules. If the artifact imports packages from node_modules, the final stage also needs to receive the production dependencies, for example with its own npm ci --omit=dev installation. Multistage is no license to leave needed dependencies behind.

With no change to the files, each instruction reuses the layer already built.

The copied files changed: COPY loses the cache, and so does every instruction after it. That is why what changes least comes first.

Key concepts

Worked examples

# WRONG: copying the whole project before installing.
# Any change to any file invalidates the COPY, and npm ci runs again.
FROM node:lts-alpine
WORKDIR /app
COPY . .
RUN npm ci

Essential commands for this stage

Hands-on

1. Create a folder with the server.js from Stage 03, the package.json, the package-lock.json, the build.js and the multistage Dockerfile from this stage.
2. Confirm that the package-lock.json is exactly the one provided above. It lets npm ci run inside the build without requiring Node or npm on the host.
3. Run docker build --tag minha-app:otimizada . twice.
4. On the second run, note CACHED on the steps that did not change.
5. Change only the response message in server.js and rebuild.
6. Confirm that the npm ci step stayed cached and test with docker run --rm --init --publish 3000:3000 minha-app:otimizada, followed by curl http://localhost:3000 in another terminal. To end it, use Ctrl+C in the container's terminal or docker stop with the ID shown by docker ps, in another terminal. Since the container was created without --name, Docker picks a random name; look it up in docker ps.
7. Swap the order of the instructions to the "WRONG" format (a COPY . . before npm ci), change server.js again and rebuild. Note that this time npm ci runs again. Undo the swap.
8. Run the three commands from "feeling the difference between bases" and note what is absent on Alpine.

Stage 05 volumes + mounts

Persistence with volumes, bind mounts and tmpfs

The problem

The concept

The container's writable layer is disposable by definition. Data that needs to survive the swap of the container must live somewhere else, connected to it. Docker offers three main mechanisms:

Named volume. It is the recommended form for production. Docker creates and registers the volume in its internal metadata and stores it, by default, on the host at a path such as /var/lib/docker/volumes/<name>/_data; what the container sees is that directory mounted at the path you defined (for example, /var/lib/mysql). Strengths: management through Docker commands, simpler backup and migration, isolation from the rest of the host. The physical path is an internal detail of the Engine and may vary by system and runtime, so prefer Docker commands over manipulating /var/lib/docker directly.

Bind mount. It points directly to a specific path on the host, which the container sees exactly as it is, with all files and permissions. It is great in development, because you edit the code on the host and the container sees the change in real time. On the other hand, there is no isolation (the container can alter the host's filesystem) and portability is limited, because it depends on the folder structure of that computer.

tmpfs. It stores data in the host's memory. When the container stops or restarts, everything is lost. It is suitable for temporary or sensitive data that, in general, should not be written to disk (under memory pressure, the system may move tmpfs pages to the swap area, so do not treat it as an absolute guarantee that nothing reaches the disk). tmpfs is a mount type, and not a persistent volume driver.

Volume drivers. The local driver is the default and uses the host's filesystem; it serves most cases well and is the recommended starting point. When several hosts need to access the same storage, the volume can use NFS through the local driver itself or a third-party plugin compatible with the provider (for example, integrations with EBS, Azure Disk or Ceph). In cloud environments with an orchestrator, specialized drivers or CSI plugins in Kubernetes are the common options. That choice depends on network, availability, permissions, backup and the consistency the application requires; only go down that road if there is a real need for sharing, remote persistence or specific performance requirements.

Key concepts

Worked examples

# Creates a volume managed by Docker.
$ docker volume create dados-demo
 
# Writes a file inside the volume and removes the container when it ends.
$ docker run --rm \
  --volume dados-demo:/dados \
  alpine sh -c 'echo persistiu > /dados/mensagem.txt'
 
# A new container reads the same volume.
$ docker run --rm \
  --volume dados-demo:/dados:ro \
  alpine cat /dados/mensagem.txt
 
# Shows the volume's metadata.
$ docker volume inspect dados-demo
 
# expected output
persistiu

Essential commands for this stage

Hands-on

1. Run the commands from the first example (volume dados-demo).
2. Confirm that the first container no longer exists with docker ps --all.
3. Read the file using a second container.
4. Prove that tmpfs does not survive a restart: run the tmpfs example (docker run --detach --init --name tmp-demo --tmpfs /dados alpine sleep 300, write with docker exec tmp-demo sh -c 'echo x > /dados/a', run docker restart tmp-demo and list with docker exec tmp-demo ls -A /dados). The listing should come out empty. Remove the container with docker rm --force tmp-demo.
5. Run the bind mount example and confirm that the edit made on the host shows up in the response without restarting the container.
6. Confirm that the volume contains only lab data. Then run docker volume rm dados-demo. The removal is permanent and offers no trash bin or automatic recovery.

Stage 06 connectivity

Networks, internal DNS and port publishing

The problem

The concept

Each container gets its own network namespace and its own IP inside a Docker network. When you create a custom network with docker network create, Docker enables an internal DNS on it: each connected container can be found by the name defined in --name. The API connects to the database using the hostname banco, with no fixed IP; a Node.js application would talk to a MongoDB just by pointing the URI to mongodb://mongo:27017, as long as the container is named mongo and both are on the same network.

Custom networks are also isolated by default: only containers connected to the same network see each other. This lets you isolate databases, separate environments (dev and prod) and reduce the attack surface. Containers can be connected to and disconnected from networks at any time, which gives fine control over who talks to whom. The same network logic is used by Docker Compose (Stage 07) and by orchestrators such as Kubernetes.

The network modes are:

• bridge: isolated network on the same host, with an IP per container. User-created bridge networks offer automatic name resolution. It is the everyday mode, suited to local development and simple single-host environments.
• host: the container shares the host's network stack, with no NAT and no IP of its own. It gives more performance and direct access to the host's network (useful for monitoring and local proxies), but eliminates network isolation and can cause port conflicts.
• none: disables the container's network connectivity. Useful for tests and workloads that should not communicate with anything.
• overlay: connects containers on different hosts, used with Docker Swarm. Other advanced networks (such as macvlan) exist for specific orchestration scenarios and are outside this guide.

The default bridge network (the one the container gets when you specify nothing) and a user-created bridge are not equivalent. DNS by container name is an advantage of the custom network. On the default bridge, do not depend on this automatic discovery.

Discovery by name is different from external access. EXPOSE 3000 documents a port in the image. --publish 8080:3000 creates the forwarding from port 8080 on the host to port 3000 in the container. For services that only other containers access (such as the database), publish nothing.

DNS does not transmit data or authenticate participants: it only resolves names to addresses. Isolation, encryption and authorization require their own mechanisms.

Key concepts

Worked examples

# Creates a bridge with internal DNS.
$ docker network create rede-demo
 
# Starts a server called web on that network.
$ docker run --detach --name web --network rede-demo nginx:alpine
 
# A temporary container resolves the hostname web and makes a request.
$ docker run --rm --network rede-demo curlimages/curl \
  --silent --head http://web
 
# Shows which containers are connected.
$ docker network inspect rede-demo
 
# Cleans up the exercise resources.
$ docker rm --force web
$ docker network rm rede-demo
 
# expected output
HTTP/1.1 200 OK
Server: nginx/...

Essential commands for this stage

Hands-on

1. Run the first example (rede-demo) without the two cleanup commands at the end (docker rm --force web and docker network rm rede-demo), because the next steps still need the web container and the network. Confirm the status HTTP/1.1 200 OK.
2. Run docker run --rm curlimages/curl --head http://web, without --network rede-demo.
3. Note the resolution failure, since the new container is outside the network. The expected output is curl: (6) Could not resolve host: web.
4. Create a client with docker run --detach --name cliente alpine sleep 300.
5. Connect it with docker network connect rede-demo cliente.
6. Prove discovery by name with docker exec cliente wget -qO- http://web. The output should contain Nginx's welcome HTML (<title>Welcome to nginx!</title>).
7. Inspect the connections with docker network inspect rede-demo and locate web and cliente in the list of containers.
8. Disconnect the client with docker network disconnect rede-demo cliente, repeat the wget and note that resolution fails again, with wget: bad address 'web'.
9. Check the names and remove the lab containers with docker rm --force cliente web; then remove the network with docker network rm rede-demo. --force ends the containers without the normal shutdown and is only appropriate here because both are disposable.
10. Run the example "the default bridge does not resolve names" and compare the error (wget: bad address 'alvo') with the success in step 6.

Stage 07 multi-container

Docker Compose for multi-container applications

The problem

The concept

Docker Compose describes a whole application in a single YAML file (by default compose.yaml; the older name docker-compose.yml is still accepted). With one command you start, observe and tear down all the containers, networks and volumes. Compose automatically creates a network for the project, and the services find each other by service name (db, web), with the same DNS logic as Stage 06. The project name is, by default, the name of the folder, and the containers get names such as projeto-web-1.

The main elements of the file are:

• services: the containers that make up the application.
• build or image: how to obtain the image for each service.
• ports: ports published on the host.
• volumes: persistence or file sharing.
• networks: communication boundaries.
• environment and env_file: non-secret configuration.
• secrets: files mounted for sensitive data (Stage 10).
• init: init: true runs an init as the service's PID 1, equivalent to --init of docker run (Stage 03).

Instead of image:, a service can use a build: block to be built locally before starting. Three fields give control over this: context (the folder used as the base of the build), dockerfile (which file to use, useful for Dockerfile.dev and Dockerfile.prod) and args (build parameters declared with ARG in the Dockerfile). This avoids piling up nearly identical Dockerfiles and lets anyone clone the repository and run docker compose up with builds adapted to the team's workflow.

Compose does not solve everything on its own. It interprets the definition and coordinates Docker resources, but the application still needs to handle startup, transient failures and dependencies correctly. depends_on guarantees creation order, not that the database is ready; readiness is handled with healthchecks in Stages 08 and 12.

Key concepts

Worked examples

services:
  web:
    # Builds using the Dockerfile in the current directory.
    build:
      context: .
      dockerfile: Dockerfile
    # Runs an init as PID 1, so that Node receives SIGTERM and the down is quick.
    init: true
    # Publishes only the service that receives external traffic.
    ports:
      - "3000:3000"
    # The hostname db will be resolved by the Compose network's DNS.
    environment:
      DB_HOST: db
    # Expresses the creation dependency, not the database's readiness.
    depends_on:
      - db
 
  db:
    # Pins the major version of the official image.
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: exemplo-local
    # Persists the data outside the container lifecycle.
    volumes:
      - dados_db:/var/lib/postgresql/data
 
 # Declares the named volume used by the database.
volumes:
  dados_db:

Essential commands for this stage

Hands-on

1. Save the example as compose.yaml next to the Dockerfile and the server.js from Stage 03.
2. Run docker compose config before starting. This command shows the consolidated configuration and detects YAML errors.
3. Run docker compose up --detach --build.
4. Check docker compose ps and docker compose logs db.
5. From inside the web service, confirm discovery of the database by name with docker compose exec web nslookup db. The output should show the name db and an internal IP address.
6. Finish with docker compose down. Do not use --volumes if you want to preserve the data. Then run docker volume ls and note that the database volume is still there, named <folder>_dados_db.

Stage 08 operations

Environments, restart, scaling and CI

The problem

The concept

Multiple Compose files. Compose combines files in the order given by -f, and later ones override earlier ones, as long as the services keep the same name. A production file can replace only the image, ports or variables needed, without duplicating the base YAML:

docker compose \
  -f compose.yaml \
  -f compose.prod.yaml \
  config

Use config to check the result before starting. By default, docker compose up (without -f) automatically loads compose.yaml and, if it exists, compose.override.yaml (in the old names, docker-compose.yml and docker-compose.override.yml). This makes the override the natural place for development adjustments. When using -f explicitly, only the listed files are loaded.

Restart policies:

• no (default): does not restart automatically.
• on-failure: restarts when the process ends with a non-zero code; accepts a limit on attempts (on-failure:3).
• always: tries to keep the container active, whatever the reason for the stop.
• unless-stopped: similar to always, but respects a manual stop.

Do not put always on everything: understand the role of each service. A database usually does fine with unless-stopped; an API that depends on the database can use on-failure with a limit, to avoid infinite loops when the error is in the configuration; a queue consumer that must always be active can use always. A restart policy does not solve startup order nor guarantee that a dependency is ready. For readiness, combine healthcheck and conditional dependencies (depends_on with condition: service_healthy) when your Compose version supports it, and keep retries in the application itself.

Scaling. docker compose up --scale worker=3 creates replicas of a service. Each replica is an independent instance, and a fixed port mapping such as 8080:3000 prevents several replicas on the same host, because port 8080 can only be occupied once. Replicas behind a single port require a load balancer in front of them.

CI (continuous integration). The same definition that runs on the developer's machine can be used in a pipeline: start the dependencies (for example, a Node.js application and a Postgres database), run the integration tests and remove everything. This brings consistency between the local environment and the build pipeline, avoids depending on external services or mocks for everything and brings the test environment closer to production. Compose works on practically any CI provider (GitHub Actions, GitLab CI, Bitbucket, Jenkins).

Key concepts

Worked examples

services:
  web:
    # Uses a public image so that the example runs without an external project.
    image: nginx:alpine
    # Restarts only on process failure, up to three times.
    restart: on-failure:3
    labels:
      ambiente: desenvolvimento
    healthcheck:
      # wget already exists in this variant of the image.
      test: ["CMD", "wget", "--quiet", "--spider", "http://localhost"]
      interval: 5s
      timeout: 2s
      retries: 5

Essential commands for this stage

Hands-on

1. Create an empty folder and save in it the two YAML files from the "base and production" example. No Dockerfile or additional code is needed.
2. Compare docker compose -f compose.yaml config with docker compose -f compose.yaml -f compose.prod.yaml config.
3. Note the image tag and the value of the ambiente label in the consolidated result: in the first command nginx:alpine and desenvolvimento appear; in the second, nginx:stable-alpine and producao.
4. Run docker compose -f compose.yaml -f compose.prod.yaml up --detach --wait.
5. Confirm healthy with docker compose -f compose.yaml -f compose.prod.yaml ps. The status column should end in (healthy).
6. Validate Nginx with docker compose -f compose.yaml -f compose.prod.yaml exec web nginx -t. The output should end in test is successful. End with docker compose -f compose.yaml -f compose.prod.yaml down.
7. In another folder, run the restart and scaling example. Confirm three worker replicas in docker compose ps and the reinicios=3 of falhador. End with docker compose down.
8. Still in that folder, add ports: ["8080:80"] to the worker service and run docker compose up --detach --scale worker=2. Note the port conflict: one of the replicas does not start and Docker reports Bind for 0.0.0.0:8080 failed: port is already allocated. Finish with docker compose down to free the folder and the port.

Stage 09 least privilege

Layered security

The problem

The concept

Since the container shares the kernel with the host, trusting the default isolation is not enough: a container escape can give access to the system. The defense comes from combining several layers, each one reducing what an exploit could do:

• Namespaces isolate the view of resources (Stage 01).
• Capabilities split the traditional privileges of root into smaller permissions. By default, the container's root already has fewer powers than the host's root. You remove dangerous capabilities (such as NET_ADMIN and SYS_ADMIN) with --cap-drop and grant a specific one with --cap-add only if the service proves it needs it. The rule is least privilege.
• Seccomp works as a filter of system calls (syscalls). Linux has hundreds of them, and seccomp lets you block several, based on an allow list. Docker already ships a default profile that blocks dangerous calls, and it is possible to supply your own, more restrictive profile with --security-opt seccomp=profile.json.
• AppArmor or SELinux, when enabled on the host, add mandatory access control.
• Non-root user reduces the impact of an exploit. By default, the container runs as root; create an unprivileged user in the image and use USER.
• Minimal permissions avoid chmod 777 as a generic solution: understand who should own what and grant the minimum necessary.
• Read-only filesystem (--read-only), with tmpfs only where the application needs to write, prevents an attacker from altering the running image.
• Small, up-to-date image reduces the tools and vulnerabilities available.
• Secrets in their own files keep sensitive values out of the Dockerfile and the environment (Stage 10).

The root user inside a container is not automatically identical to the host's root, since namespaces and capabilities impose limits. Even so, running as UID 0 without need increases risk, especially with dangerous mounts, extra capabilities or runtime flaws.

When creating the user in the image, use adduser (or useradd, depending on the base distribution) and set the owner of the copied files with --chown. When using volumes or bind mounts, the host user may differ from the container user, which causes permission problems; the common solution is to run the container with the same UID and GID as the host (--user "$(id -u):$(id -g)").

Namespaces are not unbreakable walls and USER node does not solve security on its own. The defense comes from the combination of controls, and the real implementation belongs to the kernel, the runtime, the image and the run options. Do not mount /var/run/docker.sock in ordinary applications: whoever controls that socket can control the Docker Engine and, in practice, compromise the host.

Key concepts

Worked examples

# Template for a Node.js application on Alpine.
FROM node:lts-alpine
 
# Creates an unprivileged user; -D skips the password (Alpine command).
# On Debian bases the equivalent is: RUN useradd -m appuser
RUN adduser -D appuser
 
WORKDIR /app
 
# Copies the files already owned by the application user.
COPY --chown=appuser:appuser . .
 
# Installs dependencies per the lockfile, still with build privilege.
RUN npm ci --omit=dev
 
# The following instructions and the main process run without privileges.
USER appuser
 
CMD ["npm", "start"]

Essential commands for this stage

Hands-on

1. Run docker run --rm node:lts-alpine id and note the image's default user (uid=0(root)).
2. Run docker run --rm --user node node:lts-alpine id and confirm uid=1000(node).
3. Prove --read-only as root: run docker run --rm alpine sh -c 'touch /liberado && echo "escrita permitida"' and then docker run --rm --read-only alpine touch /bloqueado. The output of the second should be touch: /bloqueado: Read-only file system.
4. Run the full command from the runtime example with --read-only and --tmpfs /tmp, and confirm the two expected messages: raiz bloqueada and tmpfs gravável.
5. Remove --tmpfs /tmp from the combined command and repeat. Writing to /tmp also fails, because it goes back to being part of the read-only root. The expected output is raiz bloqueada, followed by sh: can't create /tmp/teste: Read-only file system and cat: can't open '/tmp/teste': No such file or directory.
6. Run the two commands from the capabilities example and compare the result.
7. Build and run usuario-demo and confirm that id shows appuser, and not root.
8. Run the UID and GID example and confirm that the owners of the two files are different and that editing root's file from the host is denied (Permission denied).

Stage 10 supply chain

Build context, secrets and image analysis

The problem

The concept

The build context is everything in the folder given to docker build (or in the path you pass). By default, Docker tries to send everything, including .git, node_modules, large files and secrets. The `.dockerignore` works like a .gitignore for the build: it lists what should not be sent to the context. The result is a faster build, a smaller and safer image, and fewer cache invalidations. Keep the .dockerignore at the root of the project, near the Dockerfile, and run docker build as close as possible to the Dockerfile. If the build seems too heavy, check what is in the context: it is common to send gigabytes without noticing.

Consider the project:

meu-app/
├── node_modules/
├── .env
├── .git/
├── build/
├── src/
├── Dockerfile
└── compose.yaml

A suitable .dockerignore:

# Local dependencies will be installed inside the image.
node_modules
 
# Local configuration and possible secrets do not enter the context.
.env
.env.*
 
# History, metadata and temporary files are unnecessary.
.git
*.log
coverage
dist
build

This avoids sending thousands of node_modules files, prevents the .env from ending up inside the image, avoids copying the history of the .git folder and prevents artifacts from earlier builds from getting in by mistake. Each stack has different needs, so review any .dockerignore suggested by tools or code assistants for your own reality.

Environment variables and secrets. env_file is handy for local configuration, but does not turn values into secrets. They can appear in the container's configuration and inspection (docker inspect). .env files with credentials must not be versioned. The Compose secrets: directive mounts the value as a file inside the container, at /run/secrets/<name>, which avoids leaving it in the process environment. In local development, env_file remains handy; when the application gets staging or production, move the critical data to secrets.

Build parameters. ARG declares a value available during the build, and build.args supplies that value through Compose. They are for non-confidential data, such as version, distribution channel or feature selection. Do not use ARG for a password or token: build values can appear in the history, in metadata and in pipeline records.

Image analysis tools. Once you are past writing a lean Dockerfile, it is worth inspecting the image for real:

• Dive shows the content and weight of each layer: what each RUN, COPY and ADD added, what is weighing it down and what can go.
• Snyk checks for known vulnerabilities in the image and in dependencies, using a continuously maintained vulnerability database. It works from the command line and integrates with CI pipelines.

One complements the other: Dive helps understand the size, and Snyk takes care of security.

Key concepts

Worked examples

# Uses a concrete base before declaring the stage's argument.
FROM node:lts-alpine
 
# Declares a non-confidential parameter with a default value.
ARG APP_VERSION=dev
 
# Records the version as metadata that can be queried in the image.
LABEL org.opencontainers.image.version=$APP_VERSION

Essential commands for this stage

Hands-on

1. Go into the Stage 04 folder and create the weight on purpose: mkdir -p node_modules && head -c 50000000 /dev/urandom > node_modules/pesado.bin.
2. Run docker build --progress plain --tag minha-app:analise . only once and note the context size (about 50 MB).
3. Create the example's .dockerignore in the same folder, repeat the build and compare the size sent (a few kB) and the cache reuse.
4. Use docker history minha-app:analise to identify instructions that added more data. Remove the artificial weight with rm -rf node_modules.
5. Reproduce the example "a secret that survives in the history": confirm in docker history the COPY line with 21B (or a slightly larger, rounded value, if Docker uses the containerd image store) and the RUN rm one with 0B, and run the docker save script to see senha-de-laboratorio appear in plain text.
6. Reproduce the ARG example with image: versao-demo and confirm that docker inspect prints 1.4.0.
7. If Dive or Snyk is installed, analyze the same tag and record one point for improvement.

Stage 11 diagnostics

Troubleshooting with an investigation order

The problem

The concept

Use a predictable sequence, from the cheapest evidence to the most specific:

1. State: docker ps --all shows whether the container is running, ended or restarting.
2. Logs: docker logs shows the process's stdout and stderr.
3. Configuration: docker inspect reveals command, mounts, network, ports and state.
4. Events: docker events shows creation, start, stop, kill and removal in real time.
5. Process and resources: docker top and docker stats show processes and consumption.
6. Internal test: docker exec runs a check inside a container that is still active.

docker inspect returns detailed JSON and is the source of answers to questions such as: which original command is being run (Config.Cmd), which volumes are mounted and where (Mounts), which ports are exposed and mapped (NetworkSettings.Ports), what the image is (Image) and whether the container is stopped by an error or restarting (State). To find out whether the container died from lack of memory, check State.OOMKilled. The --format option extracts exactly the desired field, and the full output can be combined with tools such as jq or used in shell scripts.

The exit code tells part of the story: 0 indicates normal termination; any other value comes from the program itself or from Docker. Known values include 125 (Docker failed to run the docker run), 126 (the command exists but could not be invoked), 127 (the command was not found) and 137 (the process received SIGKILL). 137 has more than one origin: it can be lack of memory (in which case OOMKilled appears as true), but it also appears when a docker stop times out without the process answering SIGTERM and Docker sends SIGKILL (in which case OOMKilled remains false; this is the effect of PID 1 without a signal handler described in Stage 03). Always confirm with OOMKilled before concluding that memory ran out.

docker events is lightweight and native, and follows state changes of containers, images, volumes and networks, with timestamps. It is especially useful in real-time troubleshooting, when testing automation scripts or during deploys. It can be filtered by type (--filter type=container) or by container (--filter container=name) and the output can feed scripts or a logging system.

docker restart without evidence switches the system off and on without reading what it said: it may bring the service back for a few minutes, but it also wipes the operational context and does not identify the cause. The order above protects the diagnosis from guesswork: inspection comes before any restart.

Key concepts

Worked examples

# The shell records an error message and ends with code 42.
$ docker run --name falha alpine \
  sh -c 'echo "configuração ausente" >&2; exit 42'
 
# Confirms the exit code without reading all the JSON.
$ docker inspect --format \
  'status={{.State.Status}} exit={{.State.ExitCode}} oom={{.State.OOMKilled}}' \
  falha
 
# Retrieves the message emitted by the process.
$ docker logs falha
 
# expected output
configuração ausente
status=exited exit=42 oom=false
configuração ausente

Essential commands for this stage

Hands-on

1. Cause the failure by running only the first command of the example (the docker run --name falha ...), without the docker rm: the removal is left for step 5. The message configuração ausente already appears in the terminal during this command.
2. Before looking at the logs, formulate a hypothesis using only state and exit code: run the example's docker inspect --format and read status=exited exit=42 oom=false.
3. Check the hypothesis with docker logs falha. The same message appears a second time, now coming from Docker's record.
4. Use docker inspect --format '{{json .Config.Cmd}}' falha to see the original command.
5. Remove the container only after recording the cause: docker rm falha.
6. Run docker run --rm alpine comando-inexistente, read the error and check the code with echo $?. The expected output is 127.
7. With docker events --filter type=container open in one terminal, run docker run --rm --name evento alpine true in another and identify each event (create, attach, start, die, destroy).

Stage 12 observability

Logs, healthcheck and operational readiness

The problem

The concept

A healthcheck periodically runs a check and classifies the container as starting, healthy or unhealthy. The process state indicates presence; the healthcheck verifies the ability to serve. It does not fix the application on its own: the policy of the runtime or the orchestrator decides how to react. A good healthcheck also works as an alert for instability.

A healthy result has limited reach. It proves only the condition examined by the test at that moment. A shallow endpoint can pass the test while an important function is broken; a test that is too heavy can create load and false alarms. The healthcheck must represent the right function at a controlled cost.

The main parameters are test (the command), interval (how often), timeout (how long to wait for one attempt), retries (how many consecutive failures mark unhealthy) and start_period (an initial period in which failures do not count, so the application has time to come up). It can be declared in the Dockerfile (HEALTHCHECK instruction), in Compose (healthcheck:) or in docker run (--health-cmd and related options).

Logs. Applications should write logs to stdout and stderr, which is what docker logs reads. But relying only on docker logs stops being enough with multiple instances: logs are fragmented across containers and, if the container is destroyed, they are generally lost. The solution is to centralize and structure. Structured logs are records in a standardized format (usually JSON), with consistent fields such as timestamp, level, message and service, which makes searching and correlating events easier. In larger environments:

• Promtail is an agent that runs alongside the containers, reads the local logs and sends them to Loki. (It is Loki's historical agent, and Grafana has started pointing to another collector; check Grafana's documentation for which collection agent it recommends.)
• Loki stores and queries logs efficiently, with a model similar to Prometheus, only for logs.
• Fluentd can collect, transform and route events, and is useful in more complex scenarios, where logs need to be enriched before being sent.
• Grafana queries and visualizes the data, builds dashboards and correlates logs with metrics.

To get started, it is worth putting together a simple Compose setup that includes the collector, Loki and Grafana. Combining structured logs with alerts on critical events raises the application's observability.

Key concepts

Worked examples

services:
  api:
    image: minha-api:1.0
    healthcheck:
      # Runs a request with a tool present in the image.
      test: ["CMD", "curl", "--fail", "http://localhost:3000/health"]
      # Checks every 30 seconds.
      interval: 30s
      # Interrupts an attempt that goes over 10 seconds.
      timeout: 10s
      # Marks unhealthy after three consecutive failures.
      retries: 3
      # Gives the application time to start before counting failures.
      start_period: 20s

Essential commands for this stage

Hands-on

1. Run the sensor example and watch the sequence starting, unhealthy and healthy.
2. Build the minha-api:saude image, start the container and follow the STATUS in docker ps until (healthy) appears.
3. Run docker logs --tail 5 --timestamps api-saude and note the time of each line. Then remove the container with docker rm --force api-saude. The exercises of losing the real dependency of an API and watching the healthcheck react are in Stage 13, after you have the complete stack to test.

Stage 13 defensive stack

Capstone, a small defensive stack

The problem

The concept

This final project combines only mechanisms already presented: Dockerfile, multistage build, non-root user, custom network, volume, tmpfs, secret in a file, healthcheck, dependency on health, reduced privileges, logs and Compose. No isolated mechanism delivers a reliable application; the result comes from the discipline of the whole.

The API uses only native Node modules. It tests whether it can open a TCP connection to PostgreSQL. This proves DNS discovery and connectivity without adding a database library to the exercise.

Compose also applies simple CPU and memory limits. They contain the maximum consumption of the lab, but do not guarantee performance nor reserve exclusive capacity. Labels add metadata for inventory, automation and observability; they describe the services without altering their behavior.

The api service uses init: true: as Stage 03 explained, Node as PID 1 ignores SIGTERM without a signal handler, and the init passes the signal on, so that docker compose down and docker compose stop finish in seconds instead of waiting for the 10-second deadline.

The database healthcheck uses pg_isready -h 127.0.0.1, with the TCP address explicit. On first startup, the PostgreSQL image brings up a temporary server that listens only on a Unix socket while it prepares the database. Without the -h, pg_isready queries that socket and may answer "ready" before the final server accepts TCP connections, which is the path the API uses. With the explicit address, the test only passes when the database is actually serving over TCP.

Production checklist. Before putting any container into production, a last review is worthwhile. The capstone covers each item below, and the file shows where:

1. Optimized image: avoid generic, heavy images (such as node:latest); prefer slim/alpine variants or a multistage, so that only the essentials go to production. Covered by the Dockerfile.
2. Sensitive variables kept safe: passwords and tokens via secrets:, and not via env_file or directly in Compose. Covered by the secrets block.
3. Resource limits: CPU and memory defined so as not to overload the host. Covered by cpus and mem_limit.
4. Healthcheck configured: serves as an alert and gives the orchestrator the restart criterion. Covered by the two healthcheck blocks.
5. Structured log: the application writes JSON to stdout, ready for an observability stack (Stage 12). Covered by server.js.
6. Unprivileged user: USER node in the Dockerfile. Covered.
7. Isolated network: a specific network between services, instead of the default bridge. Covered by the interna network.
8. Persistence guaranteed: volume so that no important data is lost on a restart. Covered by dados_db.
9. Labels and metadata: make automation and integration with monitoring tools easier. Covered by the labels.
10. Final local test: simulate the production environment locally, combining the files (docker compose -f compose.yaml -f compose.prod.yaml up) before deploying for real. See the last step of the "Hands-on" section.

The limits can also be written in the Compose deploy.resources.limits format, which the bibliography uses:

services:
  api:
    deploy:
      resources:
        limits:
          # Half a CPU and 512 MB of memory.
          cpus: "0.50"
          memory: 512M

Both formats are accepted by Compose v2; this guide uses cpus and mem_limit. Check the result with docker compose config.

Key concepts

Worked examples

capstone/
├── app/
│   └── server.js
├── secrets/
│   └── db_password.txt
├── .dockerignore
├── Dockerfile
└── compose.yaml

Essential commands for this stage

Hands-on

1. Create the structure and the files exactly as shown.
2. Write a lab password with mkdir -p secrets && printf 'troque-esta-senha' > secrets/db_password.txt && chmod 644 secrets/db_password.txt. The chmod 644 matters because Postgres reads the file as the postgres user inside the container; with a restrictive umask on the host, the file would be born readable only by you and the read could fail.
3. Validate the YAML with docker compose config --quiet.
4. Bring up the stack with docker compose up --detach --build --wait.
5. Run curl http://localhost:3000/health.
6. The expected output is {"service":"api","database":"reachable"}.
7. Run docker compose ps and confirm that both services are healthy.
8. Run docker compose logs api and locate the request's JSON log.
9. Confirm the user with docker compose exec api id. The output should identify the user node, not root.
10. Run docker compose down, bring it up again and confirm that the volume capstone_dados_db (the prefix is the name of your folder) still exists with docker volume ls. Also notice that the down finishes in a few seconds, thanks to init: true.
11. If you want to preserve the database, end only with docker compose down. Use docker compose down --volumes only when you decide to discard the lab: that command removes the volume capstone_dados_db and permanently deletes its contents, with no trash bin or automatic recovery. Back up first if there is any data you need.
12. To close item 10 of the production checklist, write a minimal compose.prod.yaml (for example, changing restart or adding a label ambiente: producao), validate with docker compose -f compose.yaml -f compose.prod.yaml config and bring it up with -f on both files before considering the environment ready.
13. Extra, losing the database and coming back: with the stack up (docker compose up --detach --build --wait), confirm the initial state with docker compose ps. API and database should appear as healthy.
14. Extra: stop the API's real dependency with docker compose stop db.
15. Extra: follow docker compose ps until the API appears as unhealthy. The endpoint returns 503 because the TCP test to the database fails, and curl -i http://localhost:3000/health shows HTTP/1.1 503 with {"service":"api","database":"unreachable"}.
16. Extra: look up the attempts with docker inspect --format '{{json .State.Health}}' $(docker compose ps -q api) and correlate with docker compose logs api, where the error-level lines appear.
17. Extra: recover the database with docker compose start db and wait for both services to return to healthy in docker compose ps.

Stage 14 · review

Self-assessment checklist

Next steps: with all the items checked, redo the labs without consulting the guide and then put the pieces together. Cause failures in the capstone (stop the database, change the password, remove the volume) and explain each response of the system before looking at the logs. Then add a third service (for example, a cache) and take the same stack to a CI flow with docker compose up --wait.