docker-compose

List all running containers

$ docker compose ps

$ docker compose up [[-d|--detach]]

$ docker compose up --build

$ docker compose [[-p|--project-name]] [project_name] [[-f|--file]] [path/to/file] up

$ docker compose stop

$ docker compose down --rmi all [[-v|--volumes]]

$ docker compose logs [[-f|--follow]]

$ docker compose logs [[-f|--follow]] [container_name]

docker-compose [OPTIONS] [COMMAND] [ARGS...]

-f, --file FILE
    Specify an alternate Compose file (default: docker-compose.yml).

-p, --project-name NAME
    Specify an alternate project name (default: directory name).

--verbose
    Show more output.

--version
    Show version information and exit.

--help
    Show help message and exit.

up [OPTIONS] [SERVICE...]
    Create and start containers. Commonly used options include -d (detached mode) and --build (build images before starting).

down [OPTIONS]
    Stop and remove containers, networks, images, and volumes created by up. Options like --volumes can remove named volumes.

build [OPTIONS] [SERVICE...]
    Build or rebuild images for services. Option --no-cache can be used to disable cache during build.

ps [OPTIONS]
    List containers for the current project. Use -a to show all (stopped, running, etc.) containers.

logs [OPTIONS] [SERVICE...]
    View output from services' containers. Options like -f (follow) and --tail N (show last N lines) are common.

exec [OPTIONS] SERVICE COMMAND [ARGS...]
    Execute a command in a running container. Often used with -it for interactive sessions.

run [OPTIONS] SERVICE [COMMAND] [ARGS...]
    Run a one-off command on a service. Similar to exec but creates a new container; --rm removes it on exit.

start [SERVICE...]
    Start existing stopped services.

stop [SERVICE...]
    Stop running services without removing them.

restart [SERVICE...]
    Restart services.

config [OPTIONS]
    Validate and view the Compose file configuration.

docker-compose is a powerful tool designed to simplify the definition and management of multi-container Docker applications. It leverages a YAML file, typically named docker-compose.yml, to configure an application's services, networks, and volumes. With a single command, developers can build, start, stop, and manage all the services specified in the configuration.

This utility streamlines the development, testing, and staging workflows by allowing an entire application stack to be treated as a single unit. It orchestrates the lifecycle of multiple containers, including building images, creating custom networks, attaching volumes, and ensuring services start in the correct order. docker-compose is particularly beneficial for complex applications comprising several interdependent microservices, such as a web application with separate database, caching, and message queue components.

It promotes consistency across different environments (development, CI, production) since the same docker-compose.yml file can be used. Although primarily focused on development and testing environments, its ease of use and declarative configuration make it an indispensable tool for many Docker users.

docker-compose is primarily intended for local development and testing environments, or for CI/CD pipelines. It is not designed as a production-grade orchestrator for large-scale, highly available, or distributed applications. For such scenarios, solutions like Kubernetes or Docker Swarm are more appropriate.

Managing sensitive information (e.g., API keys, database credentials) directly in the docker-compose.yml file is not recommended; consider using environment variables or Docker secrets for better security practices.

The heart of docker-compose is the docker-compose.yml file. This YAML file defines services, networks, and volumes for your application. It supports different versions, with '3.x' being the latest recommended version, offering features like defining build contexts, environment variables, dependencies, and health checks for services.

It's crucial to distinguish between docker-compose (the standalone Python-based CLI) and docker compose (the Go-based plugin integrated into the main Docker CLI). While they serve the same purpose and largely use the same Compose file format, docker compose is the newer, actively maintained, and recommended version for modern Docker installations. The original docker-compose might be deprecated in future Docker versions, but it is still widely used in existing projects.

docker-compose originated from a project called Fig, which was acquired by Docker Inc. in 2014 and subsequently rebranded. It was initially implemented in Python and provided a convenient way to define and run multi-container applications using a YAML configuration. Its development focused on simplifying the setup of development environments and streamlining CI/CD workflows.

More recently, Docker introduced a new, Go-based implementation of Compose, integrated directly into the Docker CLI as a plugin (invoked as docker compose, without the hyphen). While the original docker-compose (hyphenated) command still functions, the unhyphenated version is the recommended and actively developed successor.

docker(1), kubectl(1), man(1)