Decoding Docker Config Across Client, Swarm, and Container Contexts

In Docker documentation, config is a contextual term, not the name of one universal mechanism. Its meaning depends on the command syntax, the component that owns the configuration, and its relationship to a container.

This article maps three documented contexts:

1. docker --config selects a directory containing Docker CLI client files.
2. docker config manages configuration objects for Docker Swarm services.
3. Application configuration inside a container may be stored in files that the application creates or modifies in the container’s writable filesystem.

These mechanisms have different owners and command boundaries. They are not interchangeable, even when the result involves a file.

The quick identification rule

Start with the syntax:

• docker --config DIRECTORY ... concerns the Docker CLI client.
• docker config ... concerns Docker Swarm config objects.
• A file created or modified by a running application belongs to the container filesystem context, although its purpose depends on the application.

Placement matters. In docker --config, config is an option on the base docker command. In docker config, it names a command group.

A file’s location alone may not settle the question. A Swarm config is mounted as a file inside a service container, while applications can also work with files in a container’s writable layer. In that case, trace the file’s origin and owner.

The three meanings at a glance

1. docker --config selects CLI client files

The Docker CLI reference defines DOCKER_CONFIG as the location of client configuration files. By default, the CLI configuration file is ~/.docker/config.json. The base command’s --config option selects a different configuration directory for the command being run (Docker CLI reference).

Docker provides this example:

docker --config ~/testconfigs/ ps

Parse it as:

docker [client option] [command]
       --config         ps

Here, --config tells the client which configuration directory to use while it runs docker ps. It does not invoke the Swarm config command group.

Clues that documentation means CLI configuration include:

• --config appears before the Docker subcommand.
• The text refers to Docker CLI or client behavior.
• It mentions ~/.docker, config.json, or DOCKER_CONFIG.
• The value passed to --config is a directory.

The relevant owner is the Docker client, rather than a Swarm service or an application running in a container.

2. docker config manages Swarm objects

Without the leading dashes, docker config is a different command surface. It manages Docker Swarm config objects.

Docker describes these objects as a way to store non-sensitive configuration data outside a service’s image or running containers. The documented operations are (Docker Swarm configs):

docker config create
docker config inspect
docker config ls
docker config rm

Docker configs are available to Swarm services, not standalone containers (Docker Swarm configs).

For example:

docker config create my-config -
docker service create --name redis --config my-config redis:alpine

The first command creates a Swarm config object. The second creates a service and grants that service access to the object. Docker then mounts the config as a file inside the service container. For Linux containers, the documented default target is /<config-name>; Docker documents different paths and limitations for Windows containers (Docker Swarm configs).

Parse the first command as:

docker [object command] [operation]
       config           create

Look for these clues:

• config follows docker without --.
• The surrounding text discusses Swarm or services.
• Operations include create, inspect, ls, or rm.
• A service is granted access to the config.
• Docker mounts the config as a file in a service container.

Although the object becomes visible as a file, it remains part of the Swarm config mechanism. It is not the Docker client’s config.json.

3. An application can use files inside its container

Docker’s overview says that Docker allocates a read-write filesystem to a container as its final layer. This allows a running container to create or modify files (Docker overview).

An application may treat some such files as its configuration. That classification comes from the application, however—not from the Docker overview. The overview does not establish an application-specific configuration path, format, ownership model, persistence policy, or lifecycle.

Clues for this context include:

• The application is the subject, rather than the Docker CLI or Swarm.
• The text discusses reading, creating, or modifying a path inside the container.
• No Swarm operation such as docker config create is involved.
• Paths and file formats are defined by the application’s documentation.

Therefore, the word configuration does not by itself identify a Docker Swarm config.

Why a file path is not enough

A Swarm config and an application-managed file can both appear as files inside a container. To distinguish them, ask:

1. Was the content created as an object through docker config create?
2. Was a Swarm service granted access to it?
3. Did Docker mount it into that service’s container?

If so, it is a Swarm config exposed as a file. By contrast, a file created or modified in the container’s writable layer belongs to the container filesystem context. Its role as configuration depends on the application.

The visible result may be “a file inside the container” in both cases. The origin, owner, and command boundary identify the mechanism.

Reading checklist

When Docker documentation uses config, ask:

1. Is it --config?
   On the base docker command, this selects the CLI client configuration directory.

2. Is it docker config?
   This command group manages Swarm config objects.

3. Who owns it?
   Separate the Docker client, Docker Swarm, and the application.

4. How did the file reach the container?
   A Swarm config is granted to a service and mounted as a file. An application can also work with files in the container’s writable layer.

5. What does the cited page establish?
   Do not infer application conventions or additional lifecycle behavior merely from the shared word config.

Sources and further reading

• https://docs.docker.com/reference/cli/docker
• https://docs.docker.com/engine/swarm/configs
• https://docs.docker.com/get-started/docker-overview