Megha Sharma's Blog
Docker compose Commands

Docker compose Commands

Megha Sharma's photo
Megha Sharma
·

13 min read

Docker Compose is a tool used for defining and running multi-container Docker applications. It uses YAML files to configure the services, networks, and volumes for your application’s containers. Here are some commonly used Docker Compose commands:

👉 docker-compose up: This command creates and starts all the containers defined in your docker-compose.yml file. If the containers don't exist, they are created.

$ docker-compose up

If you want the containers to run in detached mode (in the background), you can use the -d flag:

$ docker-compose up -d

👉 docker-compose down: This command stops and removes all the containers defined in your docker-compose.yml file.

$ docker-compose down

👉 docker-compose ps: This command shows the status of containers managed by Docker Compose.

$ docker compose ps

NAME            IMAGE     COMMAND           SERVICE    CREATED         STATUS          PORTS
example-foo-1   alpine    "/entrypoint.…"   foo        4 seconds ago   Up 2 seconds    0.0.0.0:8080->80/tcp

By default, only running containers are shown. --all flag can be used to include stopped containers.

$ docker compose ps --all

NAME            IMAGE     COMMAND           SERVICE    CREATED         STATUS          PORTS
example-foo-1   alpine    "/entrypoint.…"   foo        4 seconds ago   Up 2 seconds    0.0.0.0:8080->80/tcp
example-bar-1   alpine    "/entrypoint.…"   bar        4 seconds ago   exited (0)

👉 docker-compose logs: This command displays the logs from all the containers managed by Docker Compose.

$ docker-compose logs

👉 docker-compose build: This command builds the Docker images defined in your docker-compose.yml file.

$ docker-compose build

👉 docker-compose exec: This command allows you to run a command inside a running container managed by Docker Compose.

$ docker-compose exec <service_name> <command>

Example:

$ docker-compose exec webserver bash

👉 docker-compose restart: This command restarts all the containers defined in your docker-compose.yml file.

$ docker-compose restart

👉 docker-compose stop: This command stops all the containers managed by Docker Compose without removing them.

$ docker-compose stop

👉 docker compose config: The docker-compose config command is used to validate and view the configuration of your Docker Compose file (docker-compose.yml). It checks the syntax of the YAML file and resolves any variables or references, displaying the final configuration that Docker Compose will use when running your services.

$ docker-compose config

This command will process the Docker Compose file and display the resolved configuration, including any environment variables that were substituted and the final settings for each service, network, and volume defined in the file.

If there are any syntax errors or issues with the Docker Compose file, docker-compose config will report them, helping you identify and fix configuration problems before attempting to run your services with docker-compose up.

Keep in mind that docker-compose config does not actually run the services; it only checks and displays the configuration. Use docker-compose up to start your services based on the validated configuration.

👉 docker compose cp: The docker-compose cp command is used to copy files or directories between a container managed by Docker Compose and your local filesystem. It is similar to the docker cp command but is specifically designed for containers defined in a Docker Compose setup.

$ docker-compose cp [options] SERVICE:SRC_PATH DEST_PATH

$ docker-compose cp [options] SRC_PATH SERVICE:DEST_PATH

  • [options]: Optional additional options you can specify, such as -v for verbose output.

  • SERVICE: The name of the service (container) in your Docker Compose setup.

  • SRC_PATH: The path of the file or directory inside the container that you want to copy from or to.

  • DEST_PATH: The destination path on your local filesystem or inside the container where the file or directory should be copied to or from.

For example, to copy a file named example.txt from a service named webserver in your Docker Compose setup to your local filesystem, you would use a command like this:

$ docker-compose cp webserver:/path/to/example.txt /local/destination/

Conversely, if you want to copy a file named localfile.txt from your local filesystem to a service named flaskapp in your Docker Compose setup, you would use a command like this:

$ docker-compose cp /path/to/localfile.txt flaskapp:/app/

Just replace /path/to/example.txt and /path/to/localfile.txt with the actual paths to the files you want to copy, and /local/destination/ and /app/ with the destination paths as needed.

👉 docker compose create: The docker-compose create command is used to create the containers defined in a Docker Compose file without starting them. This can be useful if you want to prepare the containers but delay their startup until later.

$ docker-compose create

Some common options you might use with docker-compose create include:

  • -v, --volume: Create anonymous volumes for all defined volumes.

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

  • --no-deps: Don't start linked services.

Here are a few examples of how you might use docker-compose create:

Create containers for specific services (service1 and service2) defined in a custom Compose file (custom-compose.yml):

$ docker-compose -f custom-compose.yml create service1 service2

Create containers without starting linked services:

$ docker-compose create --no-deps

Create containers and create anonymous volumes for defined volumes:

$ docker-compose create -v

After running docker-compose create, you can later start the created containers using docker-compose start or start and attach to them simultaneously using docker-compose up.

👉 docker compose events: The docker-compose events command is used to stream real-time events from services managed by Docker Compose. These events provide insights into what is happening with your containers, such as when they start, stop, or encounter errors.

$ docker-compose events

Stream events for a specific service (webserver) defined in a custom Compose file (custom-compose.yml):

$ docker-compose -f custom-compose.yml events webserver

Stream events in JSON format for all services:

$ docker-compose events --json

With the --json flag, a json object is printed one per line with the format:

{
    "time": "2015-11-20T18:01:03.615550",
    "type": "container",
    "action": "create",
    "id": "213cf7...5fc39a",
    "service": "web",
    "attributes": {
      "name": "application_web_1",
      "image": "alpine:edge"
    }
}

👉 docker compose images: The docker-compose images command is used to list the images used by services in your Docker Compose setup. It's similar to the docker images command, but it specifically shows the images referenced by the services defined in your Docker Compose file.

$ docker-compose images

List images used by a specific service (webserver) defined in a custom Compose file (custom-compose.yml):

$ docker-compose -f custom-compose.yml images webserver

List all images, including intermediate images, for all services:

$ docker-compose images -a

👉 docker-compose kill: The docker-compose kill command is used to forcefully stop all containers managed by Docker Compose. It sends a SIGKILL signal to the containers, which immediately terminates them without giving them a chance to shut down gracefully.

$ docker-compose kill

Forcefully stop all containers with a timeout of 5 seconds:

$ docker-compose kill -t 5

Forcefully stop a with a custom signal (SIGTERM):

$ docker-compose kill -s SIGTERM

Forcefully stop a specific service (webserver) defined in a custom Compose file (custom-compose.yml):

$ docker-compose -f custom-compose.yml kill webserver

👉 docker compose ls: The docker-compose ls command is used to list the services defined in your Docker Compose file along with their status. It provides a quick overview of the services managed by Docker Compose and their current state (e.g., running, stopped).

$ docker-compose ls

List services quietly (display only service names):

$ docker-compose ls -q

👉 docker compose port: The docker-compose port command is used to display the public port for a specific service's container. It helps you identify the host port mapped to a container port for a service managed by Docker Compose.

For example, to get the host port mapping for port 80 of the webserver service:

$ docker-compose port webserver 80

This command will output the host port to which port 80 of the webserver container is mapped. The output will typically be in the format HOST_PORT.

If you don’t specify a specific service, the docker-compose port command will show the host port mapping for the specified port on all services.

For example, to list the host port mapping for port 5000 on all services:

$ docker-compose port 5000

👉 docker compose pull: The docker-compose pull command is used to pull (download) the latest versions of the Docker images specified in your Docker Compose file. This command ensures that you have the most up-to-date versions of the images used by your services.

$ docker-compose pull

Examples:

Consider the following compose.yaml:

services:
  db:
    image: postgres
  web:
    build: .
    command: bundle exec rails s -p 3000 -b '0.0.0.0'
    volumes:
      - .:/myapp
    ports:
      - "3000:3000"
    depends_on:
      - db

If you run docker compose pull ServiceName in the same directory as the compose.yaml file that defines the service, Docker pulls the associated image.

For example, to call the postgres image configured as the db service in our example, you would run docker compose pull db.

$ docker compose pull db
[+] Running 1/15
 ⠸ db Pulling                                                             12.4s
   ⠿ 45b42c59be33 Already exists                                           0.0s
   ⠹ 40adec129f1a Downloading  3.374MB/4.178MB                             9.3s
   ⠹ b4c431d00c78 Download complete                                        9.3s
   ⠹ 2696974e2815 Download complete                                        9.3s
   ⠹ 564b77596399 Downloading  5.622MB/7.965MB                             9.3s
   ⠹ 5044045cf6f2 Downloading  216.7kB/391.1kB                             9.3s
   ⠹ d736e67e6ac3 Waiting                                                  9.3s
   ⠹ 390c1c9a5ae4 Waiting                                                  9.3s
   ⠹ c0e62f172284 Waiting                                                  9.3s
   ⠹ ebcdc659c5bf Waiting                                                  9.3s
   ⠹ 29be22cb3acc Waiting                                                  9.3s
   ⠹ f63c47038e66 Waiting                                                  9.3s
   ⠹ 77a0c198cde5 Waiting                                                  9.3s
   ⠹ c8752d5b785c Waiting

docker compose pull tries to pull image for services with a build section. If pull fails, it lets you know this service image must be built. You can skip this by setting --ignore-buildable flag.

👉 docker compose push: The docker-compose push command is used to push (upload) the built Docker images for your services to a container registry. This command is helpful when you want to make your Docker images available for deployment on other systems or share them with others.

$ docker-compose push

ushes images for services to their respective registry/repository.

👉 docker compose restart: Restarts all stopped and running services, or the specified services only.

If you make changes to your compose.yml configuration, these changes are not reflected after running this command. For example, changes to environment variables (which are added after a container is built, but before the container's command is executed) are not updated after restarting.

$ docker-compose restart

Restart a specific service (webserver) defined in your Docker Compose file:

$ docker-compose restart webserver

👉docker compose rm: Removes stopped service containers.

Running the command with no options also removes one-off containers created by docker compose run:

$ docker compose rm

Going to remove djangoquickstart_web_run_1
Are you sure? [yN] y
Removing djangoquickstart_web_run_1 ... done

Some common options you might use with docker-compose rm include:

  • -f, --force: Force removal of containers and networks (including running containers).

  • -s, --stop: Stop services before removing associated containers (default behavior).

  • -v, --volumes: Remove named volumes declared in the volumes section of the Compose file.

  • -a, --all: Remove all containers, networks, and volumes managed by Docker Compose (including running containers).

Keep in mind that docker-compose rm only removes stopped containers, networks, and volumes. Running containers are not affected unless you use the -f, --force option, which forces removal of all containers, including running ones. Use this command with caution to avoid unintended data loss or disruptions.

👉 docker compose version: The docker-compose version command is used to display the version of Docker Compose that is installed on your system.

$ docker-compose version

When you run this command in your terminal, it will output information similar to the following:

docker-compose version 1.29.0, build 0773732a
docker-py version: 5.0.0
CPython version: 3.9.5
OpenSSL version: OpenSSL 1.1.1k  22 April 2024

The output includes details such as:

  • The version of Docker Compose (docker-compose version)

  • The build ID or commit hash of the Docker Compose version (build)

  • The version of the docker-py Python library used by Docker Compose (docker-py version)

  • The version of Python (CPython version)

  • The version of OpenSSL (OpenSSL version) used by Docker Compose

👉 Use -f to specify the name and path of one or more Compose files:

Use the -f flag to specify the location of a Compose configuration file.

Specifying multiple Compose files:

You can supply multiple -f configuration files. When you supply multiple files, Compose combines them into a single configuration. Compose builds the configuration in the order you supply the files. Subsequent files override and add to their predecessors.

For example, consider this command line:

$ docker compose -f docker-compose.yml -f docker-compose.admin.yml run backup_db

The docker-compose.yml file might specify a webapp service.

services:
  webapp:
    image: examples/web
    ports:
      - "8000:8000"
    volumes:
      - "/data"

If the docker-compose.admin.yml also specifies this same service, any matching fields override the previous file. New values, add to the webapp service configuration.

services:
  webapp:
    build: .
    environment:
      - DEBUG=1

When you use multiple Compose files, all paths in the files are relative to the first configuration file specified with -f. You can use the --project-directory option to override this base path.

Use a -f with - (dash) as the filename to read the configuration from stdin. When stdin is used all paths in the configuration are relative to the current working directory.

The -f flag is optional. If you don’t provide this flag on the command line, Compose traverses the working directory and its parent directories looking for a compose.yaml or docker-compose.yaml file.

Specifying a path to a single Compose file:

You can use the -f flag to specify a path to a Compose file that is not located in the current directory, either from the command line or by setting up a COMPOSE_FILE environment variable in your shell or in an environment file.

For an example of using the -f option at the command line, suppose you are running the Compose Rails sample, and have a compose.yaml file in a directory called sandbox/rails. You can use a command like docker compose pull to get the postgres image for the db service from anywhere by using the -f flag as follows:

$ docker compose -f ~/sandbox/rails/compose.yaml pull db

👉 Use -p to specify a project name:

Each configuration has a project name. Compose sets the project name using the following mechanisms, in order of precedence:

  • The -p command line flag

  • The COMPOSE_PROJECT_NAME environment variable

  • The top level name: variable from the config file (or the last name: from a series of config files specified using -f)

  • The basename of the project directory containing the config file (or containing the first config file specified using -f)

  • The basename of the current directory if no config file is specified Project names must contain only lowercase letters, decimal digits, dashes, and underscores, and must begin with a lowercase letter or decimal digit. If the basename of the project directory or current directory violates this constraint, you must use one of the other mechanisms.

$ docker compose -p my_project ps -a
NAME                 SERVICE    STATUS     PORTS
my_project_demo_1    demo       running

$ docker compose -p my_project logs
demo_1  | PING localhost (127.0.0.1): 56 data bytes
demo_1  | 64 bytes from 127.0.0.1: seq=0 ttl=64 time=0.095 ms

👉 Use profiles to enable optional services:

Use --profile to specify one or more active profiles Calling docker compose --profile frontend up starts the services with the profile frontend and services without any specified profiles. You can also enable multiple profiles, e.g. with docker compose --profile frontend --profile debug up the profiles frontend and debug is enabled.

Profiles can also be set by COMPOSE_PROFILES environment variable.

👉 Configuring parallelism:

Use --parallel to specify the maximum level of parallelism for concurrent engine calls. Calling docker compose --parallel 1 pull pulls the pullable images defined in the Compose file one at a time. This can also be used to control build concurrency.

Parallelism can also be set by the COMPOSE_PARALLEL_LIMIT environment variable.

👉 Set up environment variables:

You can set environment variables for various docker compose options, including the -f, -p and --profiles flags.

Setting the COMPOSE_FILE environment variable is equivalent to passing the -f flag, COMPOSE_PROJECT_NAME environment variable does the same as the -p flag, COMPOSE_PROFILES environment variable is equivalent to the --profiles flag and COMPOSE_PARALLEL_LIMIT does the same as the --parallel flag.

If flags are explicitly set on the command line, the associated environment variable is ignored.

Setting the COMPOSE_IGNORE_ORPHANS environment variable to true stops docker compose from detecting orphaned containers for the project.

👉 Use Dry Run mode to test your command:

Use --dry-run flag to test a command without changing your application stack state. Dry Run mode shows you all the steps Compose applies when executing a command, for example:

$ docker compose --dry-run up --build -d

[+] Pulling 1/1
 â  DRY-RUN MODE -  db Pulled
[+] Running 10/8
 â  DRY-RUN MODE -    build service backend                                                                                                                                                                                                 0.0s
 â  DRY-RUN MODE -  ==> ==> writing image dryRun-754a08ddf8bcb1cf22f310f09206dd783d42f7dd                                                                                                                                                   0.0s
 â  DRY-RUN MODE -  ==> ==> naming to nginx-golang-mysql-backend                                                                                                                                                                            0.0s
 â  DRY-RUN MODE -  Network nginx-golang-mysql_default                                    Created                                                                                                                                           0.0s
 â  DRY-RUN MODE -  Container nginx-golang-mysql-db-1                                     Created                                                                                                                                           0.0s
 â  DRY-RUN MODE -  Container nginx-golang-mysql-backend-1                                Created                                                                                                                                           0.0s
 â  DRY-RUN MODE -  Container nginx-golang-mysql-proxy-1                                  Created                                                                                                                                           0.0s
 â  DRY-RUN MODE -  Container nginx-golang-mysql-db-1                                     Healthy                                                                                                                                           0.5s
 â  DRY-RUN MODE -  Container nginx-golang-mysql-backend-1                                Started                                                                                                                                           0.0s
 â  DRY-RUN MODE -  Container nginx-golang-mysql-proxy-1                                  Started                                     Started

Did you find this article valuable?

Support Megha Sharma's Blog by becoming a sponsor. Any amount is appreciated!

DockerDocker composecontainersMicroservicesOpen SourceDevopsDeveloperDevops articlesdevelopmentDevOps Journey#DevopscommunityCloudCloud ComputingKubernetestechnology