# Compose Is a Project, Not a Folder of Containers

# Compose Is a Project, Not a Folder of Containers

I used to treat Compose as a shorter way to write three `docker run` commands. That model works right up until you run `docker compose down -v` and discover it also deletes the database.

Compose is not a shortcut for a list of containers. It is a project: a named group of services, networks, volumes and labels that Docker creates and removes together. Once I understood that, the commands made sense, including the destructive ones.

## The problem: three containers and no shared model

A small stack usually has the same shape: a web service, an API, a database. With plain Docker, I had to remember:

- which network each container joined
- which ports were published
- which volumes were mounted where
- which environment variables each service needed
- the order I started them in

That is a lot of state to keep in my head for something I want to run every day. It also cannot be reviewed. A teammate cannot read my shell history and see the stack.

Compose moves that state into a file. The file is versionable, reviewable and repeatable. That is the real benefit, not saving typing.

## The mental model: a project with a name

When you run `docker compose up`, Compose creates a project. The project name comes from the directory name by default, or from `-p` / `COMPOSE_PROJECT_NAME`.

Everything in the file belongs to that project:

- **Services** become containers.
- **Networks** become project-scoped networks, usually `<project>_default`.
- **Volumes** become named volumes with the project prefix.
- **Labels** let Compose find the resources it owns.

That is why Compose does not use the default `docker0` bridge. It creates its own network, and service names resolve there automatically. The web container can reach `db` by name because both are on the same project network.

This is the same user-defined-network idea from plain Docker, just automated.

## Walkthrough: a web and database stack

Create a file named `compose.yaml`:

```yaml
services:
  web:
    image: nginx:1.27-alpine
    ports:
      - "8080:80"
    volumes:
      - ./site:/usr/share/nginx/html:ro
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD in .env}
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:
```

Create a local `.env` file:

```bash
# Local only. Never commit this.
DB_PASSWORD=change-me
```

The `${DB_PASSWORD:?set DB_PASSWORD in .env}` syntax fails fast if the variable is missing. That is better than starting a database with an empty password and finding out later.

Start the stack:

```bash
docker compose up -d
```

`-d` runs it in the background. Compose builds images if a service has `build:`, pulls images if it has `image:`, creates the network, creates the volumes and starts the containers.

Check what exists:

```bash
docker compose ps
docker compose ps -a
```

The first shows running services. The second includes stopped ones. This is the Compose version of `docker ps`.

Read the logs:

```bash
docker compose logs -f web
```

Run a command inside a service:

```bash
docker compose exec web sh
```

Run a one-off command in a new container:

```bash
docker compose run --rm web sh
```

The difference matters. `exec` uses a running service container. `run` creates a separate one, usually for a migration or a test. `--rm` removes it when it exits.

Render the final configuration:

```bash
docker compose config
```

This is one of the most useful commands in Compose. It resolves variables, merges overrides and shows what Docker will actually use. When a variable is not interpolating, this is where I look first.

Stop without removing:

```bash
docker compose stop
```

Stop and remove the containers and the project network:

```bash
docker compose down --remove-orphans
```

Remove the volumes too:

```bash
docker compose down --volumes --remove-orphans
```

That last command is how a database disappears. `--volumes` deletes named volumes. It is not a cleanup flag. It is a data-loss flag with a friendly name.

## Build versus image

A service can use an existing image:

```yaml
services:
  web:
    image: nginx:1.27-alpine
```

Or build one:

```yaml
services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
```

Or use both:

```yaml
services:
  api:
    build: .
    image: rg0901/demo-api:1.0
```

The combination is useful: Compose builds the image and tags it with the name you would push. It does not push it. That is still `docker push`.

## What Compose is not

Compose runs on one host. It is not a scheduler and it is not a replacement for Kubernetes. It does not reschedule a failed container on another machine, and it does not manage a cluster.

For a local development stack, a small self-hosted service or a demo, that is fine. For production across multiple hosts, the boundary is different.

That is not a criticism of Compose. It is a scope decision. Compose gives one host a reproducible application definition. A scheduler gives many hosts a placement policy. Mixing the two expectations is how people end up disappointed by a tool that is doing exactly what it says.

Compose also does not make `depends_on` a readiness check. More on that below.

## Overrides are part of the project model

Compose can merge more than one file. The base file describes the stack; an override file changes it for a specific environment:

```bash
docker compose -f compose.yaml -f compose.override.yaml up -d
```

A common pattern is a base file with the services, and an override that adds a bind mount or changes a port for local development. Compose merges the files in order, with later files taking precedence.

That is useful, but it also makes `docker compose config` more important. The file you read may not be the configuration Docker runs. The rendered output is the source of truth.

I keep the base file boring and put local-only changes in an override that stays out of version control. It is the same reason I keep `.env` local: the stack should be reproducible without carrying my machine's paths.

## A safer cleanup habit

`down` and `down -v` are not two versions of the same command. One removes the project. The other removes the data.

My rule is simple: `down` is the default. `down -v` is a deliberate reset.

Before the reset, I check the volumes:

```bash
docker volume ls
docker compose config --volumes
```

`docker compose config --volumes` lists the named volumes the project will use. If the list includes a database volume, `-v` will delete it.

I also check for orphan containers before cleanup:

```bash
docker compose ps -a
docker compose down --remove-orphans
```

Orphans are services that were removed from the file but are still running from an earlier version. They are easy to forget and easy to leave behind. `--remove-orphans` is safe for that case; `--volumes` is the one that needs a pause.

## Gotchas

- `docker compose` **is v2.** `docker-compose` with a hyphen is the old Python tool and is end-of-life. Use the plugin.
- **Compose does not join** `docker0`**.** It creates `<project>_default`, which is why service names resolve.
- `down --volume` **is not the flag.** Use `--volumes` or `-v`.
- `down -v` **deletes named volumes.** Do not use it if the data matters.
- `depends_on` **controls start order, not readiness.** The database container can be "started" before it accepts connections. Use a healthcheck and retry logic.
- `container_name` **blocks scaling.** A fixed name means Compose cannot create multiple replicas of that service.
- **Relative bind-mount paths are relative to the Compose file**, not your shell's current directory.
- **The top-level** `version:` **key is obsolete** in Compose v2. Omit it.
- **Port collisions are common.** Change the host side of the mapping, not the container side.
- `.env` **is for interpolation.** It does not automatically become the container environment. Use `environment` or `env_file`.
- `--remove-orphans` **is not automatic.** Services removed from the file can leave containers behind.

## Recap

- Compose creates a project: services, networks, volumes and labels.
- Service names resolve on the project network, without hardcoded IPs.
- `up -d` builds, pulls, creates and starts the stack.
- `down` removes containers and the network; `down -v` also removes volumes.
- `depends_on` is start order, not readiness.
- `docker compose config` shows what Compose will actually run.

Compose became predictable when I stopped thinking of it as a command wrapper and started thinking of it as a project boundary. The file is the source of truth. The commands operate on the whole project, not just the containers I can see.

## Source notes

- Repository notes: <https://github.com/rg0901/build-log/tree/main/DevOps-Tool/Docker>
- Docker Compose overview: <https://docs.docker.com/compose/>
- Compose file reference: <https://docs.docker.com/reference/compose-file/>
- Compose CLI reference: <https://docs.docker.com/reference/cli/docker/compose/>
- Environment variables in Compose: <https://docs.docker.com/compose/environment-variables/>
