Store configuration data using Docker Configs

Estimated reading time: 20 minutes

About configs

Docker swarm service configs allow you to store non-sensitive information, such as configuration files, outside a service’s image or running containers. This allows you to keep your images as generic as possible, without the need to bind-mount configuration files into the containers or use environment variables.

Configs operate in a similar way to secrets, except that they are not encrypted at rest and are mounted directly into the container’s filesystem without the use of RAM disks. Configs can be added or removed from a service at any time, and services can share a config. You can even use configs in conjunction with environment variables or labels, for maximum flexibility. Config values can be generic strings or binary content (up to 500 kb in size).

Note: Docker configs are only available to swarm services, not to standalone containers. To use this feature, consider adapting your container to run as a service with a scale of 1.

Configs are supported on both Linux and Windows services.

Windows support

Docker includes support for configs on Windows containers, but there are differences in the implementations, which are called out in the examples below. Keep the following notable differences in mind:

Config files with custom targets are not directly bind-mounted into Windows containers, since Windows does not support non-directory file bind-mounts. Instead, configs for a container are all mounted in C:\ProgramData\Docker\internal\configs (an implementation detail which should not be relied upon by applications) within the container. Symbolic links are used to point from there to the desired target of the config within the container. The default target is C:\ProgramData\Docker\configs .

When creating a service which uses Windows containers, the options to specify UID, GID, and mode are not supported for configs. Configs are currently only accessible by administrators and users with system access within the container.

On Windows, create or update a service using —credential-spec with the config:// format. This passes the gMSA credentials file directly to nodes before a container starts. No gMSA credentials are written to disk on worker nodes. For more information, refer to Deploy services to a swarm.

How Docker manages configs

When you add a config to the swarm, Docker sends the config to the swarm manager over a mutual TLS connection. The config is stored in the Raft log, which is encrypted. The entire Raft log is replicated across the other managers, ensuring the same high availability guarantees for configs as for the rest of the swarm management data.

When you grant a newly-created or running service access to a config, the config is mounted as a file in the container. The location of the mount point within the container defaults to / in Linux containers. In Windows containers, configs are all mounted into C:\ProgramData\Docker\configs and symbolic links are created to the desired location, which defaults to C:\ .

You can set the ownership ( uid and gid ) for the config, using either the numerical ID or the name of the user or group. You can also specify the file permissions ( mode ). These settings are ignored for Windows containers.

• If not set, the config is owned by the user running the container command (often root ) and that user’s default group (also often root ).
• If not set, the config has world-readable permissions (mode 0444 ), unless a umask is set within the container, in which case the mode is impacted by that umask value.

You can update a service to grant it access to additional configs or revoke its access to a given config at any time.

A node only has access to configs if the node is a swarm manager or if it is running service tasks which have been granted access to the config. When a container task stops running, the configs shared to it are unmounted from the in-memory filesystem for that container and flushed from the node’s memory.

If a node loses connectivity to the swarm while it is running a task container with access to a config, the task container still has access to its configs, but cannot receive updates until the node reconnects to the swarm.

You can add or inspect an individual config at any time, or list all configs. You cannot remove a config that a running service is using. See Rotate a config for a way to remove a config without disrupting running services.

To update or roll back configs more easily, consider adding a version number or date to the config name. This is made easier by the ability to control the mount point of the config within a given container.

To update a stack, make changes to your Compose file, then re-run docker stack deploy -c . If you use a new config in that file, your services start using them. Keep in mind that configurations are immutable, so you can’t change the file for an existing service. Instead, you create a new config to use a different file

You can run docker stack rm to stop the app and take down the stack. This removes any config that was created by docker stack deploy with the same stack name. This removes all configs, including those not referenced by services and those remaining after a docker service update —config-rm .

Read more about docker config commands

Use these links to read about specific commands, or continue to the example about using configs with a service.

Examples

This section includes graduated examples which illustrate how to use Docker configs.

Note: These examples use a single-Engine swarm and unscaled services for simplicity. The examples use Linux containers, but Windows containers also support configs.

Defining and using configs in compose files

The docker stack command supports defining configs in a Compose file. However, the configs key is not supported for docker compose . See the Compose file reference for details.

Simple example: Get started with configs

This simple example shows how configs work in just a few commands. For a real-world example, continue to Advanced example: Use configs with a Nginx service.

Add a config to Docker. The docker config create command reads standard input because the last argument, which represents the file to read the config from, is set to — .

Create a redis service and grant it access to the config. By default, the container can access the config at /my-config , but you can customize the file name on the container using the target option.

Verify that the task is running without issues using docker service ps . If everything is working, the output looks similar to this:

Get the ID of the redis service task container using docker ps , so that you can use docker container exec to connect to the container and read the contents of the config data file, which defaults to being readable by all and has the same name as the name of the config. The first command below illustrates how to find the container ID, and the second and third commands use shell completion to do this automatically.

Try removing the config. The removal fails because the redis service is running and has access to the config.

Remove access to the config from the running redis service by updating the service.

Repeat steps 3 and 4 again, verifying that the service no longer has access to the config. The container ID is different, because the service update command redeploys the service.

Stop and remove the service, and remove the config from Docker.

Simple example: Use configs in a Windows service

This is a very simple example which shows how to use configs with a Microsoft IIS service running on Docker for Windows running Windows containers on Microsoft Windows 10. It is a naive example that stores the webpage in a config.

This example assumes that you have PowerShell installed.

Save the following into a new file index.html .

If you have not already done so, initialize or join the swarm.

Save the index.html file as a swarm config named homepage .

Create an IIS service and grant it access to the homepage config.

Access the IIS service at http://localhost:8000/ . It should serve the HTML content from the first step.

Remove the service and the config.

Example: Use a templated config

To create a configuration in which the content will be generated using a template engine, use the —template-driver parameter and specify the engine name as its argument. The template will be rendered when container is created.

Save the following into a new file index.html.tmpl .

Save the index.html.tmpl file as a swarm config named homepage . Provide parameter —template-driver and specify golang as template engine.

Create a service that runs Nginx and has access to the environment variable HELLO and to the config.

Verify that the service is operational: you can reach the Nginx server, and that the correct output is being served.

Advanced example: Use configs with a Nginx service

This example is divided into two parts. The first part is all about generating the site certificate and does not directly involve Docker configs at all, but it sets up the second part, where you store and use the site certificate as a series of secrets and the Nginx configuration as a config. The example shows how to set options on the config, such as the target location within the container and the file permissions ( mode ).

Generate the site certificate

Generate a root CA and TLS certificate and key for your site. For production sites, you may want to use a service such as Let’s Encrypt to generate the TLS certificate and key, but this example uses command-line tools. This step is a little complicated, but is only a set-up step so that you have something to store as a Docker secret. If you want to skip these sub-steps, you can use Let’s Encrypt to generate the site key and certificate, name the files site.key and site.crt , and skip to Configure the Nginx container.

Generate a root key.

Generate a CSR using the root key.

Configure the root CA. Edit a new file called root-ca.cnf and paste the following contents into it. This constrains the root CA to only sign leaf certificates and not intermediate CAs.

Sign the certificate.

Generate the site key.

Generate the site certificate and sign it with the site key.

Configure the site certificate. Edit a new file called site.cnf and paste the following contents into it. This constrains the site certificate so that it can only be used to authenticate a server and can’t be used to sign certificates.

Sign the site certificate.

The site.csr and site.cnf files are not needed by the Nginx service, but you need them if you want to generate a new site certificate. Protect the root-ca.key file.

Configure the Nginx container

Produce a very basic Nginx configuration that serves static files over HTTPS. The TLS certificate and key are stored as Docker secrets so that they can be rotated easily.

In the current directory, create a new file called site.conf with the following contents:

Create two secrets, representing the key and the certificate. You can store any file as a secret as long as it is smaller than 500 KB. This allows you to decouple the key and certificate from the services that use them. In these examples, the secret name and the file name are the same.

Save the site.conf file in a Docker config. The first parameter is the name of the config, and the second parameter is the file to read it from.

List the configs:

Create a service that runs Nginx and has access to the two secrets and the config. Set the mode to 0440 so that the file is only readable by its owner and that owner’s group, not the world.

Within the running containers, the following three files now exist:

• /run/secrets/site.key
• /run/secrets/site.crt
• /etc/nginx/conf.d/site.conf

Verify that the Nginx service is running.

Verify that the service is operational: you can reach the Nginx server, and that the correct TLS certificate is being used.

Unless you are going to continue to the next example, clean up after running this example by removing the nginx service and the stored secrets and config.

You have now configured a Nginx service with its configuration decoupled from its image. You could run multiple sites with exactly the same image but separate configurations, without the need to build a custom image at all.

Example: Rotate a config

To rotate a config, you first save a new config with a different name than the one that is currently in use. You then redeploy the service, removing the old config and adding the new config at the same mount point within the container. This example builds upon the previous one by rotating the site.conf configuration file.

Edit the site.conf file locally. Add index.php to the index line, and save the file.

Create a new Docker config using the new site.conf , called site-v2.conf .

Update the nginx service to use the new config instead of the old one.

Verify that the nginx service is fully re-deployed, using docker service ps nginx . When it is, you can remove the old site.conf config.

To clean up, you can remove the nginx service, as well as the secrets and configs.

You have now updated your nginx service’s configuration without the need to rebuild its image.

Docker Desktop for Windows user manual

Estimated reading time: 16 minutes

Welcome to Docker Desktop! The Docker Desktop for Windows user manual provides information on how to configure and manage your Docker Desktop settings.

For information about Docker Desktop download, system requirements, and installation instructions, see Install Docker Desktop.

Settings

The Docker Desktop menu allows you to configure your Docker settings such as installation, updates, version channels, Docker Hub login, and more.

This section explains the configuration options accessible from the Settings dialog.

Open the Docker Desktop menu by clicking the Docker icon in the Notifications area (or System tray):

Select Settings to open the Settings dialog:

General

On the General tab of the Settings dialog, you can configure when to start and update Docker.

Automatically check for updates: By default, Docker Desktop is configured to check for newer versions automatically. If you have installed Docker Desktop as part of an organization, you may not be able to update Docker Desktop yourself. In that case, upgrade your existing organization to a Team plan and clear this checkbox to disable the automatic check for updates.

Start Docker when you log in: Select this option to automatically start Docker Desktop when you log into your Windows machine.

Expose daemon on tcp://localhost:2375 without TLS: Click this option to enable legacy clients to connect to the Docker daemon. You must use this option with caution as exposing the daemon without TLS can result in remote code execution attacks.

Use the WSL 2 based engine: WSL 2 provides better performance than the legacy Hyper-V backend. For more information, see Docker Desktop WSL 2 backend.

Send usage statistics: By default, Docker Desktop sends diagnostics, crash reports, and usage data. This information helps Docker improve and troubleshoot the application. Clear the check box to opt out. Docker may periodically prompt you for more information.

Show weekly tips: Displays useful advice and suggestions about using Docker.

Open Docker Desktop dashboard at startup: Automatically opens the dashboard when starting Docker Desktop.

Resources

The Resources tab allows you to configure CPU, memory, disk, proxies, network, and other resources. Different settings are available for configuration depending on whether you are using Linux containers in WSL 2 mode, Linux containers in Hyper-V mode, or Windows containers.

Advanced

The Advanced tab is only available in Hyper-V mode, because in WSL 2 mode and Windows container mode these resources are managed by Windows. In WSL 2 mode, you can configure limits on the memory, CPU, and swap size allocated to the WSL 2 utility VM.

Use the Advanced tab to limit resources available to Docker.

CPUs: By default, Docker Desktop is set to use half the number of processors available on the host machine. To increase processing power, set this to a higher number; to decrease, lower the number.

Memory: By default, Docker Desktop is set to use 2 GB runtime memory, allocated from the total available memory on your machine. To increase the RAM, set this to a higher number. To decrease it, lower the number.

Swap: Configure swap file size as needed. The default is 1 GB.

Disk image size: Specify the size of the disk image.

Disk image location: Specify the location of the Linux volume where containers and images are stored.

You can also move the disk image to a different location. If you attempt to move a disk image to a location that already has one, you get a prompt asking if you want to use the existing image or replace it.

File sharing

The File sharing tab is only available in Hyper-V mode, because in WSL 2 mode and Windows container mode all files are automatically shared by Windows.

Use File sharing to allow local directories on Windows to be shared with Linux containers. This is especially useful for editing source code in an IDE on the host while running and testing the code in a container. Note that configuring file sharing is not necessary for Windows containers, only Linux containers. If a directory is not shared with a Linux container you may get file not found or cannot start service errors at runtime. See Volume mounting requires shared folders for Linux containers.

File share settings are:

Add a Directory: Click + and navigate to the directory you want to add.

Apply & Restart makes the directory available to containers using Docker’s bind mount ( -v ) feature.

Tips on shared folders, permissions, and volume mounts

Share only the directories that you need with the container. File sharing introduces overhead as any changes to the files on the host need to be notified to the Linux VM. Sharing too many files can lead to high CPU load and slow filesystem performance.

Shared folders are designed to allow application code to be edited on the host while being executed in containers. For non-code items such as cache directories or databases, the performance will be much better if they are stored in the Linux VM, using a data volume (named volume) or data container.

Docker Desktop sets permissions to read/write/execute for users, groups and others 0777 or a+rwx. This is not configurable. See Permissions errors on data directories for shared volumes.

Windows presents a case-insensitive view of the filesystem to applications while Linux is case-sensitive. On Linux it is possible to create 2 separate files: test and Test , while on Windows these filenames would actually refer to the same underlying file. This can lead to problems where an app works correctly on a developer Windows machine (where the file contents are shared) but fails when run in Linux in production (where the file contents are distinct). To avoid this, Docker Desktop insists that all shared files are accessed as their original case. Therefore if a file is created called test , it must be opened as test . Attempts to open Test will fail with “No such file or directory”. Similarly once a file called test is created, attempts to create a second file called Test will fail.

Shared folders on demand

You can share a folder “on demand” the first time a particular folder is used by a container.

If you run a Docker command from a shell with a volume mount (as shown in the example below) or kick off a Compose file that includes volume mounts, you get a popup asking if you want to share the specified folder.

You can select to Share it, in which case it is added your Docker Desktop Shared Folders list and available to containers. Alternatively, you can opt not to share it by selecting Cancel.

Proxies

Docker Desktop lets you configure HTTP/HTTPS Proxy Settings and automatically propagates these to Docker. For example, if you set your proxy settings to http://proxy.example.com , Docker uses this proxy when pulling containers.

Your proxy settings, however, will not be propagated into the containers you start. If you wish to set the proxy settings for your containers, you need to define environment variables for them, just like you would do on Linux, for example:

For more information on setting environment variables for running containers, see Set environment variables.

Network

The Network tab is not available in Windows container mode because networking is managed by Windows.

You can configure Docker Desktop networking to work on a virtual private network (VPN). Specify a network address translation (NAT) prefix and subnet mask to enable Internet connectivity.

DNS Server: You can configure the DNS server to use dynamic or static IP addressing.

Some users reported problems connecting to Docker Hub on Docker Desktop. This would manifest as an error when trying to run docker commands that pull images from Docker Hub that are not already downloaded, such as a first time run of docker run hello-world . If you encounter this, reset the DNS server to use the Google DNS fixed address: 8.8.8.8 . For more information, see Networking issues in Troubleshooting.

Updating these settings requires a reconfiguration and reboot of the Linux VM.

WSL Integration

In WSL 2 mode, you can configure which WSL 2 distributions will have the Docker WSL integration.

By default, the integration will be enabled on your default WSL distribution. To change your default WSL distro, run wsl —set-default . (For example, to set Ubuntu as your default WSL distro, run wsl —set-default ubuntu ).

You can also select any additional distributions you would like to enable the WSL 2 integration on.

For more details on configuring Docker Desktop to use WSL 2, see Docker Desktop WSL 2 backend.

Docker Engine

The Docker Engine page allows you to configure the Docker daemon to determine how your containers run.

Type a JSON configuration file in the box to configure the daemon settings. For a full list of options, see the Docker Engine dockerd commandline reference.

Click Apply & Restart to save your settings and restart Docker Desktop.

Command Line

On the Command Line page, you can specify whether or not to enable experimental features.

You can toggle the experimental features on and off in Docker Desktop. If you toggle the experimental features off, Docker Desktop uses the current generally available release of Docker Engine.

Experimental features

Experimental features provide early access to future product functionality. These features are intended for testing and feedback only as they may change between releases without warning or can be removed entirely from a future release. Experimental features must not be used in production environments. Docker does not offer support for experimental features.

For a list of current experimental features in the Docker CLI, see Docker CLI Experimental features.

Run docker version to verify whether you have enabled experimental features. Experimental mode is listed under Server data. If Experimental is true , then Docker is running in experimental mode, as shown here:

Kubernetes

The Kubernetes tab is not available in Windows container mode.

Docker Desktop includes a standalone Kubernetes server that runs on your Windows machince, so that you can test deploying your Docker workloads on Kubernetes. To enable Kubernetes support and install a standalone instance of Kubernetes running as a Docker container, select Enable Kubernetes.

For more information about using the Kubernetes integration with Docker Desktop, see Deploy on Kubernetes.

Reset

The Restart Docker Desktop and Reset to factory defaults options are now available on the Troubleshoot menu. For information, see Logs and Troubleshooting.

Troubleshoot

Visit our Logs and Troubleshooting guide for more details.

Log on to our Docker Desktop for Windows forum to get help from the community, review current user topics, or join a discussion.

Log on to Docker Desktop for Windows issues on GitHub to report bugs or problems and review community reported issues.

For information about providing feedback on the documentation or update it yourself, see Contribute to documentation.

Switch between Windows and Linux containers

From the Docker Desktop menu, you can toggle which daemon (Linux or Windows) the Docker CLI talks to. Select Switch to Windows containers to use Windows containers, or select Switch to Linux containers to use Linux containers (the default).

For more information on Windows containers, refer to the following documentation:

Microsoft documentation on Windows containers.

Build and Run Your First Windows Server Container (Blog Post) gives a quick tour of how to build and run native Docker Windows containers on Windows 10 and Windows Server 2016 evaluation releases.

Getting Started with Windows Containers (Lab) shows you how to use the MusicStore application with Windows containers. The MusicStore is a standard .NET application and, forked here to use containers, is a good example of a multi-container application.

To understand how to connect to Windows containers from the local host, see Limitations of Windows containers for localhost and published ports

Settings dialog changes with Windows containers

When you switch to Windows containers, the Settings dialog only shows those tabs that are active and apply to your Windows containers:

If you set proxies or daemon configuration in Windows containers mode, these apply only on Windows containers. If you switch back to Linux containers, proxies and daemon configurations return to what you had set for Linux containers. Your Windows container settings are retained and become available again when you switch back.

Dashboard

The Docker Desktop Dashboard enables you to interact with containers and applications and manage the lifecycle of your applications directly from your machine. The Dashboard UI shows all running, stopped, and started containers with their state. It provides an intuitive interface to perform common actions to inspect and manage containers and Docker Compose applications. For more information, see Docker Desktop Dashboard.

Docker Hub

Select Sign in /Create Docker ID from the Docker Desktop menu to access your Docker Hub account. Once logged in, you can access your Docker Hub repositories directly from the Docker Desktop menu.

For more information, refer to the following Docker Hub topics:

Two-factor authentication

Docker Desktop enables you to sign into Docker Hub using two-factor authentication. Two-factor authentication provides an extra layer of security when accessing your Docker Hub account.

You must enable two-factor authentication in Docker Hub before signing into your Docker Hub account through Docker Desktop. For instructions, see Enable two-factor authentication for Docker Hub.

After you have enabled two-factor authentication:

Go to the Docker Desktop menu and then select Sign in / Create Docker ID.

Enter your Docker ID and password and click Sign in.

After you have successfully signed in, Docker Desktop prompts you to enter the authentication code. Enter the six-digit code from your phone and then click Verify.

After you have successfully authenticated, you can access your organizations and repositories directly from the Docker Desktop menu.

Adding TLS certificates

You can add trusted Certificate Authorities (CAs) to your Docker daemon to verify registry server certificates, and client certificates, to authenticate to registries.

How do I add custom CA certificates?

Docker Desktop supports all trusted Certificate Authorities (CAs) (root or intermediate). Docker recognizes certs stored under Trust Root Certification Authorities or Intermediate Certification Authorities.

Docker Desktop creates a certificate bundle of all user-trusted CAs based on the Windows certificate store, and appends it to Moby trusted certificates. Therefore, if an enterprise SSL certificate is trusted by the user on the host, it is trusted by Docker Desktop.

To learn more about how to install a CA root certificate for the registry, see Verify repository client with certificates in the Docker Engine topics.

How do I add client certificates?

You can add your client certificates in

/client.key . You do not need to push your certificates with git commands.

When the Docker Desktop application starts, it copies the

/.docker/certs.d folder on your Windows system to the /etc/docker/certs.d directory on Moby (the Docker Desktop virtual machine running on Hyper-V).

You need to restart Docker Desktop after making any changes to the keychain or to the

/.docker/certs.d directory in order for the changes to take effect.

The registry cannot be listed as an insecure registry (see Docker Daemon). Docker Desktop ignores certificates listed under insecure registries, and does not send client certificates. Commands like docker run that attempt to pull from the registry produce error messages on the command line, as well as on the registry.

To learn more about how to set the client TLS certificate for verification, see Verify repository client with certificates in the Docker Engine topics.

Where to go next

Try out the walkthrough at Get Started.

Dig in deeper with Docker Labs example walkthroughs and source code.