Configuration Management

Docker Engine behavior can be customized through daemon configuration, client configuration, and environment variables. This guide covers all configuration options and best practices.

Daemon Configuration

The Docker daemon (dockerd) is configured using a JSON configuration file and/or command-line flags.

Configuration File Location

Platform	Default Path
Linux	`/etc/docker/daemon.json`
Windows	`C:\ProgramData\docker\config\daemon.json`
macOS (Docker Desktop)	`~/.docker/daemon.json` or via Docker Desktop UI

Complete Configuration Example

json

{
  "debug": false,
  "tls": true,
  "tlscacert": "/etc/docker/certs/ca.pem",
  "tlscert": "/etc/docker/certs/server-cert.pem",
  "tlskey": "/etc/docker/certs/server-key.pem",
  "hosts": ["unix:///var/run/docker.sock", "tcp://0.0.0.0:2376"],
  "storage-driver": "overlay2",
  "storage-opts": ["overlay2.size=20G"],
  "data-root": "/var/lib/docker",
  "exec-root": "/var/run/docker",
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "5",
    "labels": "production_status",
    "env": "os,customer"
  },
  "default-address-pools": [
    {
      "base": "172.17.0.0/16",
      "size": 24
    }
  ],
  "dns": ["8.8.8.8", "8.8.4.4"],
  "dns-search": ["example.com"],
  "max-concurrent-downloads": 10,
  "max-concurrent-uploads": 5,
  "default-runtime": "runc",
  "runtimes": {
    "custom": {
      "path": "/usr/local/bin/custom-runtime"
    }
  },
  "default-ulimits": {
    "nofile": {
      "Name": "nofile",
      "Hard": 65536,
      "Soft": 32768
    }
  },
  "live-restore": true,
  "userland-proxy": false,
  "no-new-privileges": true,
  "registry-mirrors": ["https://mirror.example.com"],
  "insecure-registries": [],
  "features": {
    "buildkit": true
  }
}

Configuration Options Reference

Storage Configuration

Option	Description	Default
`storage-driver`	Storage driver to use	`overlay2`
`storage-opts`	Storage driver options	`[]`
`data-root`	Root directory for Docker data	`/var/lib/docker`

json

{
  "storage-driver": "overlay2",
  "storage-opts": ["overlay2.size=20G"],
  "data-root": "/mnt/docker-data"
}

bash

# Move Docker data to a new location
sudo systemctl stop docker
sudo mv /var/lib/docker /mnt/docker-data
# Update data-root in daemon.json
sudo systemctl start docker

Logging Configuration

Option	Description	Default
`log-driver`	Default logging driver	`json-file`
`log-opts`	Logging driver options	`{}`

Available Log Drivers:

Driver	Description
`json-file`	Default JSON file logging
`local`	Custom log format, minimal disk usage
`syslog`	Write to syslog facility
`journald`	Write to systemd journal
`fluentd`	Forward to Fluentd
`awslogs`	Send to Amazon CloudWatch
`gcplogs`	Send to Google Cloud Logging
`splunk`	Send to Splunk
`none`	Disable logging

json

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "5",
    "compress": "true"
  }
}

bash

# Override log driver for a specific container
docker run -d --log-driver syslog --log-opt syslog-address=tcp://192.168.1.100:514 nginx

# View current log driver
docker info --format '{{.LoggingDriver}}'

Network Configuration

json

{
  "dns": ["8.8.8.8", "8.8.4.4"],
  "dns-search": ["example.com"],
  "dns-opts": ["ndots:5"],
  "bip": "172.17.0.1/16",
  "fixed-cidr": "172.17.0.0/24",
  "default-address-pools": [
    {
      "base": "10.10.0.0/16",
      "size": 24
    }
  ],
  "mtu": 1500,
  "iptables": true,
  "ip-forward": true,
  "ip-masq": true,
  "userland-proxy": false,
  "ipv6": false
}

Option	Description	Default
`dns`	DNS servers for containers	Host DNS
`bip`	Bridge IP address	`172.17.0.1/16`
`fixed-cidr`	Subnet for container IPs	Matches `bip`
`default-address-pools`	Pool for custom networks	Docker default
`mtu`	Maximum transmission unit	1500
`iptables`	Enable iptables rules	true
`userland-proxy`	Use userland proxy for port forwarding	true

Security Configuration

json

{
  "tls": true,
  "tlscacert": "/etc/docker/certs/ca.pem",
  "tlscert": "/etc/docker/certs/server-cert.pem",
  "tlskey": "/etc/docker/certs/server-key.pem",
  "no-new-privileges": true,
  "seccomp-profile": "/etc/docker/seccomp/default.json",
  "userns-remap": "default",
  "live-restore": true
}

Registry Configuration

json

{
  "registry-mirrors": [
    "https://mirror.example.com",
    "https://mirror2.example.com"
  ],
  "insecure-registries": [
    "registry.internal.example.com:5000"
  ],
  "allow-nondistributable-artifacts": [
    "registry.internal.example.com:5000"
  ]
}

Resource Defaults

json

{
  "default-ulimits": {
    "nofile": {
      "Name": "nofile",
      "Hard": 65536,
      "Soft": 32768
    },
    "nproc": {
      "Name": "nproc",
      "Hard": 4096,
      "Soft": 2048
    }
  },
  "default-shm-size": "64M",
  "cgroup-parent": "docker",
  "init": true
}

Client Configuration

Docker CLI Configuration

The Docker CLI stores configuration in ~/.docker/config.json:

json

{
  "auths": {
    "https://index.docker.io/v1/": {
      "auth": "base64-encoded-credentials"
    },
    "registry.example.com": {
      "auth": "base64-encoded-credentials"
    }
  },
  "credHelpers": {
    "gcr.io": "gcloud",
    "*.dkr.ecr.*.amazonaws.com": "ecr-login"
  },
  "credsStore": "desktop",
  "currentContext": "default",
  "plugins": {},
  "aliases": {
    "builder": "buildx"
  }
}

Docker Contexts

Contexts allow you to switch between different Docker environments:

bash

# List contexts
docker context ls

# Create a new context
docker context create production \
  --docker "host=tcp://prod-server:2376,ca=~/certs/ca.pem,cert=~/certs/cert.pem,key=~/certs/key.pem"

# Switch to a context
docker context use production

# Run a command with a specific context
docker --context production ps

# Remove a context
docker context rm production

Environment Variables

Variable	Description
`DOCKER_HOST`	Daemon socket URL
`DOCKER_TLS_VERIFY`	Enable TLS verification
`DOCKER_CERT_PATH`	Path to TLS certificates
`DOCKER_CONFIG`	Location of client config
`DOCKER_CONTENT_TRUST`	Enable image signing
`DOCKER_BUILDKIT`	Enable BuildKit
`COMPOSE_FILE`	Compose file path
`COMPOSE_PROJECT_NAME`	Compose project name

bash

# Example environment setup
export DOCKER_HOST=tcp://192.168.1.10:2376
export DOCKER_TLS_VERIFY=1
export DOCKER_CERT_PATH=~/.docker/certs
export DOCKER_BUILDKIT=1

Applying Configuration Changes

bash

# After editing /etc/docker/daemon.json:

# Option 1: Restart Docker (causes container downtime)
sudo systemctl restart docker

# Option 2: Reload configuration (no downtime, limited options)
sudo systemctl reload docker
# or
sudo kill -SIGHUP $(pidof dockerd)

# Verify configuration
docker info

Reloadable vs Non-Reloadable Options

Reloadable (no restart)	Non-Reloadable (restart required)
`debug`	`storage-driver`
`labels`	`data-root`
`max-concurrent-downloads`	`tls` / `tlscacert` / `tlscert` / `tlskey`
`max-concurrent-uploads`	`hosts`
`log-driver` / `log-opts`	`bip`
`shutdown-timeout`	`userns-remap`
`live-restore`	`iptables`

Docker Desktop Configuration

Docker Desktop provides a GUI for configuration:

Resource Settings

Setting	Description	Recommended
CPUs	CPU cores allocated	4+ for development
Memory	RAM allocated	8 GB+ for development
Swap	Swap space	2 GB
Disk image size	Max disk space	60 GB+
File sharing	Shared directories	Project directories

WSL 2 Configuration (Windows)

Create %USERPROFILE%\.wslconfig:

ini

[wsl2]
memory=8GB
processors=4
swap=2GB
localhostForwarding=true
nestedVirtualization=true

[experimental]
sparseVhd=true

Configuration Validation

bash

# Validate daemon.json syntax
python3 -c "import json; json.load(open('/etc/docker/daemon.json'))"

# Test Docker configuration
dockerd --validate

# Check current configuration
docker info

# Check specific settings
docker info --format '{{.Driver}}'
docker info --format '{{.LoggingDriver}}'
docker info --format '{{.CgroupDriver}}'

Next Steps

Docker Engine Architecture — Understand Docker internals
CLI Commands Reference — Master Docker commands
API Reference — Programmatic Docker access
Security Best Practices — Secure your Docker configuration
Docker Networking Guide — Network configuration deep dive

Configuration Management ​

Daemon Configuration ​

Configuration File Location ​

Complete Configuration Example ​

Configuration Options Reference ​

Storage Configuration ​

Logging Configuration ​

Network Configuration ​

Security Configuration ​

Registry Configuration ​

Resource Defaults ​

Client Configuration ​

Docker CLI Configuration ​

Docker Contexts ​

Environment Variables ​

Applying Configuration Changes ​

Reloadable vs Non-Reloadable Options ​

Docker Desktop Configuration ​

Resource Settings ​

WSL 2 Configuration (Windows) ​

Configuration Validation ​

Next Steps ​

Configuration Management

Daemon Configuration

Configuration File Location

Complete Configuration Example

Configuration Options Reference

Storage Configuration

Logging Configuration

Network Configuration

Security Configuration

Registry Configuration

Resource Defaults

Client Configuration

Docker CLI Configuration

Docker Contexts

Environment Variables

Applying Configuration Changes

Reloadable vs Non-Reloadable Options

Docker Desktop Configuration

Resource Settings

WSL 2 Configuration (Windows)

Configuration Validation

Next Steps