Compose CLI environment variables

Estimated reading time: 4 minutes

Several environment variables are available for you to configure the Docker Compose command-line behaviour.

Variables starting with DOCKER_ are the same as those used to configure the Docker command-line client. If you’re using docker-machine , then the eval «$(docker-machine env my-docker-vm)» command should set them to their correct values. (In this example, my-docker-vm is the name of a machine you created.)

Note: Some of these variables can also be provided using an environment file.

COMPOSE_PROJECT_NAME

Sets the project name. This value is prepended along with the service name to the container on start up. For example, if your project name is myapp and it includes two services db and web , then Compose starts containers named myapp_db_1 and myapp_web_1 respectively.

Setting this is optional. If you do not set this, the COMPOSE_PROJECT_NAME defaults to the basename of the project directory. See also the -p command-line option.

COMPOSE_FILE

Specify the path to a Compose file. If not provided, Compose looks for a file named docker-compose.yml in the current directory and then each parent directory in succession until a file by that name is found.

This variable supports multiple Compose files separated by a path separator (on Linux and macOS the path separator is : , on Windows it is ; ). For example: COMPOSE_FILE=docker-compose.yml:docker-compose.prod.yml . The path separator can also be customized using COMPOSE_PATH_SEPARATOR .

COMPOSE_PROFILES

Specify one or multiple active profiles to enable. Calling docker-compose up with COMPOSE_PROFILES=frontend will start the services with the profile frontend and services without specified profiles.

You can specify a list of profiles separated with a comma: COMPOSE_PROFILES=frontend,debug will enable the profiles frontend and debug .

COMPOSE_API_VERSION

The Docker API only supports requests from clients which report a specific version. If you receive a client and server don’t have same version error using docker-compose , you can workaround this error by setting this environment variable. Set the version value to match the server version.

Setting this variable is intended as a workaround for situations where you need to run temporarily with a mismatch between the client and server version. For example, if you can upgrade the client but need to wait to upgrade the server.

Running with this variable set and a known mismatch does prevent some Docker features from working properly. The exact features that fail would depend on the Docker client and server versions. For this reason, running with this variable set is only intended as a workaround and it is not officially supported.

If you run into problems running with this set, resolve the mismatch through upgrade and remove this setting to see if your problems resolve before notifying support.

DOCKER_HOST

Sets the URL of the docker daemon. As with the Docker client, defaults to unix:///var/run/docker.sock .

DOCKER_TLS_VERIFY

When set to anything other than an empty string, enables TLS communication with the docker daemon.

DOCKER_CERT_PATH

Configures the path to the ca.pem , cert.pem , and key.pem files used for TLS verification. Defaults to

COMPOSE_HTTP_TIMEOUT

Configures the time (in seconds) a request to the Docker daemon is allowed to hang before Compose considers it failed. Defaults to 60 seconds.

COMPOSE_TLS_VERSION

Configure which TLS version is used for TLS communication with the docker daemon. Defaults to TLSv1 . Supported values are: TLSv1 , TLSv1_1 , TLSv1_2 .

COMPOSE_CONVERT_WINDOWS_PATHS

Enable path conversion from Windows-style to Unix-style in volume definitions. Users of Docker Machine on Windows should always set this. Defaults to 0 . Supported values: true or 1 to enable, false or 0 to disable.

COMPOSE_PATH_SEPARATOR

If set, the value of the COMPOSE_FILE environment variable is separated using this character as path separator.

COMPOSE_FORCE_WINDOWS_HOST

If set, volume declarations using the short syntax are parsed assuming the host path is a Windows path, even if Compose is running on a UNIX-based system. Supported values: true or 1 to enable, false or 0 to disable.

COMPOSE_IGNORE_ORPHANS

If set, Compose doesn’t try to detect orphaned containers for the project. Supported values: true or 1 to enable, false or 0 to disable.

COMPOSE_PARALLEL_LIMIT

Sets a limit for the number of operations Compose can execute in parallel. The default value is 64 , and may not be set lower than 2 .

COMPOSE_INTERACTIVE_NO_CLI

If set, Compose doesn’t attempt to use the Docker CLI for interactive run and exec operations. This option is not available on Windows where the CLI is required for the aforementioned operations. Supported: true or 1 to enable, false or 0 to disable.

COMPOSE_DOCKER_CLI_BUILD

Configure whether to use the Compose python client for building images or the native docker cli. By default, Compose uses the docker CLI to perform builds, which allows you to use BuildKit to perform builds.

Set COMPOSE_DOCKER_CLI_BUILD=0 to disable native builds, and to use the built-in python client.

Environment variables in Compose

Estimated reading time: 5 minutes

There are multiple parts of Compose that deal with environment variables in one sense or another. This page should help you find the information you need.

Substitute environment variables in Compose files

It’s possible to use environment variables in your shell to populate values inside a Compose file:

If you have multiple environment variables, you can substitute them by adding them to a default environment variable file named .env or by providing a path to your environment variables file using the —env-file command line option.

The “.env” file

You can set default values for any environment variables referenced in the Compose file, or used to configure Compose, in an environment file named .env . The .env file path is as follows:

• Starting with +v1.28 , .env. file is placed at the base of the project directory
• For previous versions, it is placed in the current working directory where the Docker Compose command is executed unless a —project-directory is defined which overrides the path for the .env file. This inconsistency is addressed in +v1.28 by limiting the filepath to the project directory.

When you run docker-compose up , the web service defined above uses the image webapp:v1.5 . You can verify this with the config command, which prints your resolved application config to the terminal:

Values in the shell take precedence over those specified in the .env file.

If you set TAG to a different value in your shell, the substitution in image uses that instead:

You can override the environment file path using a command line argument —env-file .

Using the “—env-file” option

By passing the file as an argument, you can store it anywhere and name it appropriately, for example, .env.ci , .env.dev , .env.prod . Passing the file path is done using the —env-file option:

This file path is relative to the current working directory where the Docker Compose command is executed.

The .env file is loaded by default:

Passing the —env-file argument overrides the default file path:

When an invalid file path is being passed as —env-file argument, Compose returns an error:

For more information, see the Variable substitution section in the Compose file reference.

Set environment variables in containers

You can set environment variables in a service’s containers with the ‘environment’ key, just like with docker run -e VARIABLE=VALUE . :

Pass environment variables to containers

You can pass environment variables from your shell straight through to a service’s containers with the ‘environment’ key by not giving them a value, just like with docker run -e VARIABLE . :

The value of the DEBUG variable in the container is taken from the value for the same variable in the shell in which Compose is run.

The “env_file” configuration option

You can pass multiple environment variables from an external file through to a service’s containers with the ‘env_file’ option, just like with docker run —env-file=FILE . :

Set environment variables with ‘docker-compose run’

Similar to docker run -e , you can set environment variables on a one-off container with docker-compose run -e :

You can also pass a variable from the shell by not giving it a value:

The value of the DEBUG variable in the container is taken from the value for the same variable in the shell in which Compose is run.

When you set the same environment variable in multiple files, here’s the priority used by Compose to choose which value to use:

1. Compose file
2. Shell environment variables
3. Environment file
4. Dockerfile
5. Variable is not defined

In the example below, we set the same environment variable on an Environment file, and the Compose file:

When you run the container, the environment variable defined in the Compose file takes precedence.

Having any ARG or ENV setting in a Dockerfile evaluates only if there is no Docker Compose entry for environment or env_file .

Specifics for NodeJS containers

If you have a package.json entry for script:start like NODE_ENV=test node server.js , then this overrules any setting in your docker-compose.yml file.

Configure Compose using environment variables

Several environment variables are available for you to configure the Docker Compose command-line behavior. They begin with COMPOSE_ or DOCKER_ , and are documented in CLI Environment Variables.

Подсистема Docker в Windows Docker Engine on Windows

Подсистема и клиент Docker не входят в состав Windows, потому их нужно устанавливать и настраивать отдельно. The Docker Engine and client aren’t included with Windows and need to be installed and configured individually. Кроме того, подсистема Docker может принимать множество пользовательских конфигураций. Furthermore, the Docker Engine can accept many custom configurations. Например, можно настроить то, как управляющая программа принимает входящие запросы, сетевые параметры по умолчанию и параметры ведения журнала и отладки. Some examples include configuring how the daemon accepts incoming requests, default networking options, and debug/log settings. В ОС Windows эти конфигурации можно указать в файле конфигурации или с помощью диспетчера служб Windows. On Windows, these configurations can be specified in a configuration file or by using Windows Service control manager. В этом документе объясняется установка и настройка подсистемы Docker; также представлены примеры некоторых часто используемых конфигураций. This document details how to install and configure the Docker Engine, and also provides some examples of commonly used configurations.

Установка Docker Install Docker

Для работы с контейнерами Windows требуется Docker. You need Docker in order to work with Windows Containers. Docker состоит из подсистемы Docker (dockerd.exe) и клиента Docker (docker.exe). Docker consists of the Docker Engine (dockerd.exe), and the Docker client (docker.exe). Самый простой способ установить все необходимые компоненты изложен в кратком руководстве, которое поможет настроить и запустить первый контейнер. The easiest way to get everything installed is in the quickstart guide, which will help you get everything set up and run your first container.

Сведения об установке с помощью сценария см. в разделе Использование сценария для установки Docker EE. For scripted installations, see Use a script to install Docker EE.

Прежде чем использовать Docker, необходимо установить образы контейнеров. Before you can use Docker, you’ll need to install the container images. Дополнительные сведения см. в документации по образам контейнеров. For more information, see docs for our container base images.

Настройка Docker с помощью файла конфигурации Configure Docker with a configuration file

Предпочтительным способом настройки подсистемы Docker в Windows является использование файла конфигурации. The preferred method for configuring the Docker Engine on Windows is using a configuration file. Путь к файлу конфигурации — C:\ProgramData\Docker\config\daemon.json. The configuration file can be found at ‘C:\ProgramData\Docker\config\daemon.json’. Если этот файл еще не существует, его можно создать. You can create this file if it doesn’t already exist.

Не все доступные параметры конфигурации Docker применяются к Docker в Windows. Not every available Docker configuration option applies to Docker on Windows. В примере ниже показаны параметры конфигурации, которые применяются. The following example shows the configuration options that do apply. Дополнительные сведения о конфигурации подсистемы Docker см. в статье Docker daemon configuration file (Файл конфигурации управляющей программы Docker). For more information about Docker Engine configuration, see Docker daemon configuration file.

Достаточно только внести необходимые изменения в файл конфигурации. You only need to add the desired configuration changes to the configuration file. Например, в этом случае подсистема Docker настраивается на прием входящих подключений через порт 2375. For example, the following sample configures the Docker Engine to accept incoming connections on port 2375. В других параметрах конфигурации будут использоваться значения по умолчанию. All other configuration options will use default values.

Аналогично в примере ниже настраивается хранение образов и контейнеров по альтернативному пути в управляющей программе Docker. Likewise, the following sample configures the Docker daemon to keep images and containers in an alternate path. Если оно не указано, по умолчанию используется значение c:\programdata\docker . If not specified, the default is c:\programdata\docker .

В примере ниже управляющая программа Docker настраивается на прием только защищенных подключений через порт 2376. The following sample configures the Docker daemon to only accept secured connections over port 2376.

Настройка Docker в службе Docker Configure Docker on the Docker service

Подсистему Docker можно также настроить, изменив службу Docker командой sc config . The Docker Engine can also be configured by modifying the Docker service with sc config . При использовании этого способа флаги подсистемы Docker задаются непосредственно в службе Docker. Using this method, Docker Engine flags are set directly on the Docker service. Выполните указанную ниже команду в командной строке (cmd.exe, не PowerShell). Run the following command in a command prompt (cmd.exe not PowerShell):

Не нужно выполнять эту команду в том случае, если файл daemon.json уже содержит запись «hosts»: [«tcp://0.0.0.0:2375»] . You don’t need to run this command if your daemon.json file already contains the «hosts»: [«tcp://0.0.0.0:2375»] entry.

Распространенные конфигурации Common configuration

В следующих примерах файла конфигурации представлены распространенные конфигурации Docker. The following configuration file examples show common Docker configurations. Их можно объединить в один файл конфигурации. These can be combined into a single configuration file.

Создание сети по умолчанию Default network creation

Чтобы настроить подсистему Docker таким образом, чтобы не была создана сеть NAT по умолчанию, используйте следующую конфигурацию. To configure the Docker Engine so that it doesn’t create a default NAT network, use the following configuration.

Дополнительные сведения см. в статье Управление сетями Docker. For more information, see Manage Docker Networks.

Задание группы безопасности для Docker Set Docker security group

После входа в систему на узле Docker и запуска команд Docker эти команды выполняются через именованный канал. When you’ve signed in to the Docker host and are locally running Docker commands, these commands are run through a named pipe. По умолчанию только члены группы «Администраторы» могут получить доступ к подсистеме Docker через именованный канал. By default, only members of the Administrators group can access the Docker Engine through the named pipe. Чтобы указать группу безопасности, имеющую такой доступ, используйте флаг group . To specify a security group that has this access, use the group flag.

Конфигурация прокси-сервера Proxy configuration

Чтобы задать данные о прокси-сервере для docker search и docker pull , создайте переменную среды Windows с именем HTTP_PROXY или HTTPS_PROXY и значением, содержащим данные о прокси-сервере. To set proxy information for docker search and docker pull , create a Windows environment variable with the name HTTP_PROXY or HTTPS_PROXY , and a value of the proxy information. Это можно сделать в PowerShell, используя команду следующего вида: This can be completed with PowerShell using a command similar to this:

После задания переменной перезапустите службу Docker. Once the variable has been set, restart the Docker service.

Дополнительные сведения см. в разделе Windows Configuration File (Файл конфигурации Windows) на сайте Docker.com. For more information, see Windows Configuration File on Docker.com.

Удаление Docker How to uninstall Docker

В этом разделе описывается, как удалить Docker и выполнить полную очистку компонентов системы Docker в Windows 10 или Windows Server 2016. This section will tell you how to uninstall Docker and perform a full cleanup of Docker system components from your Windows 10 or Windows Server 2016 system.

Все команды в этих инструкциях необходимо выполнять из сеанса PowerShell с повышенными привилегиями. You must run all commands in these instructions from an elevated PowerShell session.

Подготовка системы к удалению Docker Prepare your system for Docker’s removal

Перед удалением Docker убедитесь, что в системе не запущены контейнеры. Before you uninstall Docker, make sure no containers are running on your system.

Выполните следующие командлеты, чтобы найти работающие контейнеры: Run the following cmdlets to check for running containers:

Кроме того, перед удалением Docker рекомендуется удалить все контейнеры, образы контейнеров, сети и тома из системы. It’s also good practice to remove all containers, container images, networks, and volumes from your system before removing Docker. Это можно сделать, выполнив следующий командлет: You can do this by running the following cmdlet:

Удаление Docker Uninstall Docker

Затем необходимо начать собственно удаление Docker. Next, you’ll need to actually uninstall Docker.

Удаление Docker в Windows 10 To uninstall Docker on Windows 10

• На компьютере с Windows 10 перейдите в раздел Параметры >Приложения. Go to Settings >Apps on your Windows 10 machine
• В разделе Приложения и компоненты найдите пункт Docker для Windows Under Apps & Features, find Docker for Windows
• Последовательно выберите Docker для Windows >Удалить. Go to Docker for Windows >Uninstall

Удаление Docker в Windows Server 2016 To uninstall Docker on Windows Server 2016:

В сеансе PowerShell с повышенными привилегиями используйте командлеты Uninstall-Package и Uninstall-Module, чтобы удалить модуль Docker и соответствующий ему поставщик Управление пакетами из системы, как показано в следующем примере: From an elevated PowerShell session, use the Uninstall-Package and Uninstall-Module cmdlets to remove the Docker module and its corresponding Package Management Provider from your system, as shown in the following example:

Вы можете найти поставщик пакетов, который использовался для установки Docker с помощью команды PS C:\> Get-PackageProvider -Name *Docker* You can find the Package Provider that you used to install Docker with PS C:\> Get-PackageProvider -Name *Docker*

Очистка данных и системных компонентов Docker Clean up Docker data and system components

После удаления Docker необходимо удалить сети Docker по умолчанию, чтобы их конфигурация не оставалась в системе после того, как Docker будет удален. After you uninstall Docker, you’ll need to remove Docker’s default networks so their configuration won’t remain on your system after Docker is gone. Это можно сделать, выполнив следующий командлет: You can do this by running the following cmdlet:

Удалите сети по умолчанию Docker в Windows Server 2016. To remove Docker’s default networks on Windows Server 2016.

Выполните следующий командлет, чтобы удалить программные данные Docker из системы: Run the following cmdlet to remove Docker’s program data from your system:

Можно также удалить необязательные компоненты Windows, связанные с Docker и контейнерами в Windows. You may also want to remove the Windows optional features associated with Docker/containers on Windows.

К ним относится компонент «Контейнеры», который автоматически включается в любом экземпляре Windows 10 или Windows Server 2016 при установке Docker. This includes the «Containers» feature, which is automatically enabled on any Windows 10 or Windows Server 2016 when Docker is installed. Это также может быть компонент «Hyper-V», который автоматически включается в Windows 10 при установке Docker, однако в Windows Server 2016 он включается вручную. It may also include the «Hyper-V» feature, which is automatically enabled on Windows 10 when Docker is installed, but must be explicitly enabled on Windows Server 2016.

Компонент Hyper-V является общим компонентом виртуализации, который обеспечивает гораздо большую функциональность, чем при использовании одних только контейнеров. The Hyper-V feature is a general virtualization feature that enables much more than just containers. Прежде чем отключить Hyper-V, убедитесь, что в системе нет других виртуальных компонентов, которые зависят от Hyper-V. Before disabling the Hyper-V feature, make sure there are no other virtualized components on your system that require Hyper-V.

Удаление компонентов Windows 10 To remove Windows features on Windows 10:

• Выберите последовательно Панель управления >Программы >Программы и компоненты >Включение или отключение компонентов Windows. Go to Control Panel >Programs >Programs and Features >Turn Windows features on or off.
• Найдите имя компонента, который требуется отключить — в данном случае это Контейнеры и (необязательно) Hyper-V. Find the name of the feature or features you want to disable—in this case, Containers and (optionally) Hyper-V.
• Снимите флажок рядом с именем компонента, который нужно отключить. Uncheck the box next to the name of the feature you want to disable.
• Нажмите кнопку ОК. Select «OK»

Удаление компонентов Windows Server 2016 To remove Windows features on Windows Server 2016:

В сеансе PowerShell с повышенными привилегиями выполните следующие командлеты, чтобы отключить компоненты Контейнеры и (необязательно) Hyper-V. From an elevated PowerShell session, run the following cmdlets to disable the Containers and (optionally) Hyper-V features from your system:

Перезагрузка системы Reboot your system

Чтобы завершить удаление компонентов и очистить систему, выполните следующий командлет из сеанса PowerShell с повышенными привилегиями для перезагрузки системы: To finish uninstallation and cleanup, run the following cmdlet from an elevated PowerShell session to reboot your system: