Docker Container Configuration with JSON

If you searched for docker config json, you are probably looking for one of three different things: Docker's CLI config file, a JSON payload for the Docker Engine API, or a JSON file that your application reads inside the container. Those are related, but they are not interchangeable, and Docker does not have a built-in docker run --config container.json feature for general container settings.

The practical rule is simple: use ~/.docker/config.json to configure the Docker client, use the Docker Engine API when you want to create a container from a JSON body, and mount a JSON file when the application inside the container needs structured config at runtime.

Quick answer: which JSON file do you actually need?

• Docker CLI settings: edit ~/.docker/config.json.
• Create a container from JSON: send a JSON body to the Docker Engine POST /containers/create endpoint.
• Pass app settings into a container: mount a JSON file and let your app read it.
• Inspect an existing container: use docker inspect, which returns JSON.

1. The Docker CLI config file: ~/.docker/config.json

Docker's official CLI reference still uses ~/.docker/config.json as the default client configuration file. This file controls how the docker command behaves on your machine. It is not a container definition file, and it does not tell Docker how to run an individual container.

Typical uses include credential helpers, default output formatting, custom HTTP headers, and registry auth. Docker also supports switching to another config directory with DOCKER_CONFIG or the docker --config flag.

{
  "credsStore": "osxkeychain",
  "psFormat": "table {{.ID}}\t{{.Image}}\t{{.Status}}\t{{.Names}}",
  "imagesFormat": "table {{.Repository}}\t{{.Tag}}\t{{.Size}}",
  "HttpHeaders": {
    "X-Environment": "dev"
  }
}

If your question is "where is the Docker config JSON file?", this is usually the file people mean. If your question is "how do I create a container from JSON?", this is not the file you want.

2. Creating a Docker container from JSON

For actual container creation, JSON belongs to the Docker Engine API. The current Docker Engine API reference documents POST /containers/create with a JSON body that combines core container fields such as Image and Env with nested sections such as HostConfig and NetworkingConfig.

This is the JSON equivalent of many docker run flags. If you are building a platform, wrapper script, control plane, or admin tool, this is the canonical approach.

curl --unix-socket /var/run/docker.sock \
  -H "Content-Type: application/json" \
  -X POST "http://localhost/v1.53/containers/create?name=my-nginx" \
  -d '{
    "Image": "nginx:1.27-alpine",
    "Env": [
      "NGINX_ENTRYPOINT_QUIET_LOGS=1"
    ],
    "ExposedPorts": {
      "80/tcp": {}
    },
    "HostConfig": {
      "PortBindings": {
        "80/tcp": [
          {
            "HostPort": "8080"
          }
        ]
      },
      "Binds": [
        "./site:/usr/share/nginx/html:ro"
      ],
      "RestartPolicy": {
        "Name": "unless-stopped"
      }
    }
  }'

docker start my-nginx

A few common mappings are worth memorizing:

• -e KEY=value becomes Env.
• -p 8080:80 becomes both ExposedPorts and HostConfig.PortBindings.
• -v host:container:ro becomes HostConfig.Binds.
• --restart unless-stopped becomes HostConfig.RestartPolicy.Name.
• The container name is commonly passed in the request URL as the name query parameter.

3. Can docker run read a generic config.json file?

Not directly. The Docker CLI does not have a general feature where you hand it a JSON document and it turns that into a container definition. If you need that workflow, choose one of these patterns:

• Generate a docker run command from your own JSON schema in a script.
• Translate your JSON into a Compose file such as compose.yaml.
• Skip the CLI and call the Engine API with a JSON body.

{
  "image": "nginx:1.27-alpine",
  "name": "site",
  "ports": ["8080:80"],
  "mounts": ["./site:/usr/share/nginx/html:ro"],
  "env": {
    "NGINX_ENTRYPOINT_QUIET_LOGS": "1"
  }
}

import fs from "node:fs";

const cfg = JSON.parse(fs.readFileSync("container.json", "utf8"));
const args = ["run", "-d"];

if (cfg.name) args.push("--name", cfg.name);
for (const port of cfg.ports ?? []) args.push("-p", port);
for (const mount of cfg.mounts ?? []) args.push("-v", mount);
for (const [key, value] of Object.entries(cfg.env ?? {})) {
  args.push("-e", `${key}=${value}`);
}

args.push(cfg.image);
console.log(`docker ${args.join(" ")}`);

This pattern is useful when a control panel or deployment tool stores container settings as JSON internally but still executes the Docker CLI underneath.

4. Mounting a JSON config file inside the container

Sometimes the JSON file is not for Docker at all. It is for the application running inside the container. In that case, keep the container configuration separate and mount the JSON file at runtime.

{
  "database": {
    "host": "db.internal",
    "port": 5432
  },
  "featureFlags": {
    "newDashboard": true
  },
  "logging": {
    "level": "info"
  }
}

docker run -d \
  --name my-app \
  --mount type=bind,src="$PWD/app-config.json",dst=/app/config/app-config.json,readonly \
  my-application-image

Use this approach when the app expects a JSON settings file. Do not confuse it with Docker's own client config file or the Engine API payload used to create the container.

5. Use docker inspect when you need real container JSON

If you already have a container and want to see the effective configuration in JSON form, docker inspect is the fastest path. It returns a JSON array containing image details, environment variables, mounts, networks, restart policy, and much more.

docker inspect my-nginx | jq '.[0].HostConfig.PortBindings'

This is especially helpful when you want to verify what Docker actually applied or when you are reverse engineering a known-good container into an API payload or Compose definition.

Common mistakes and security notes

• Do not commit ~/.docker/config.json to version control. It may contain registry auth or proxy information.
• Do not store secrets in plain JSON unless you control access tightly. Prefer secret managers or Docker secret mechanisms where they fit your deployment model.
• Do not expose the Docker socket casually. If you can post JSON to the Engine API, you can usually create privileged containers and control the host.
• Do not mix up similarly named features. Docker CLI config.json, Swarm docker config, and app-level JSON config files solve different problems.

Bottom line

When people say "Docker JSON config", the missing step is deciding what is being configured. Use ~/.docker/config.json for the Docker client, the Engine API for container creation from JSON, and mounted JSON files for application settings inside the container. Once you separate those cases, the Docker docs and JSON structure become much easier to work with.