Configure Settings Management with a JSON file

Note

Settings Management is available to Docker Business customers only.

This page contains information on how to configure Settings Management with an admin-settings.json file. You can specify and lock configuration parameters to create a standardized Docker Desktop environment across your company or organization.

Settings Management is designed specifically for organizations who don’t give developers root access to their machines.

Prerequisites

You first need to enforce sign-in to ensure that all Docker Desktop developers authenticate with your organization. Since Settings Management requires a Docker Business subscription, enforced sign-in guarantees that only authenticated users have access and that the feature consistently takes effect across all users, even though it may still work without enforced sign-in.

Step one: Create the admin-settings.json file and save it in the correct location

You can either use the --admin-settings installer flag on macOS or Windows to automatically create the admin-settings.json and save it in the correct location, or set it up manually.

To set it up manually:

1. Create a new, empty JSON file and name it admin-settings.json.

2. Save the admin-settings.json file on your developers' machines in the following locations:

   • Mac: /Library/Application\ Support/com.docker.docker/admin-settings.json
   • Windows: C:\ProgramData\DockerDesktop\admin-settings.json
   • Linux: /usr/share/docker-desktop/admin-settings.json

   By placing this file in a protected directory, developers are unable to modify it.

   Important

   It is assumed that you have the ability to push the admin-settings.json settings file to the locations specified through a device management software such as Jamf.

Step two: Configure the settings you want to lock in

Note

Some of the configuration parameters only apply to certain platforms or to specific Docker Desktop versions. This is highlighted in the following table.

The admin-settings.json file requires a nested list of configuration parameters, each of which must contain the locked parameter. You can add or remove configuration parameters as per your requirements.

If locked: true, users aren't able to edit this setting from Docker Desktop or the CLI.

If locked: false, it's similar to setting a factory default in that:

• For new installs, locked: false pre-populates the relevant settings in the Docker Desktop Dashboard, but users are able to modify it.

• If Docker Desktop is already installed and being used, locked: false is ignored. This is because existing users of Docker Desktop may have already updated a setting, which in turn will have been written to the relevant config file, for example the settings-store.json (or settings.json for Docker Desktop versions 4.34 and earlier) or daemon.json. In these instances, the user's preferences are respected and the values aren't altered. These can be controlled by setting locked: true.

The following admin-settings.json code and table provides an example of the required syntax and descriptions for parameters and values:

{
  "configurationFileVersion": 2,
  "exposeDockerAPIOnTCP2375": {
    "locked": true,
    "value": false
  },
  "proxy": {
    "locked": true,
    "mode": "system",
    "http": "",
    "https": "",
    "exclude": [],
    "windowsDockerdPort": 65000,
    "enableKerberosNtlm": false
  },
  "containersProxy": {
    "locked": true,
    "mode": "manual",
    "http": "",
    "https": "",
    "exclude": [],
    "pac":"",
    "transparentPorts": ""
  },
  "enhancedContainerIsolation": {
    "locked": true,
    "value": true,
    "dockerSocketMount": {
      "imageList": {
        "images": [
          "docker.io/localstack/localstack:*",
          "docker.io/testcontainers/ryuk:*"
        ]
      },
      "commandList": {
        "type": "deny",
        "commands": ["push"]
      }
    }
  },
  "linuxVM": {
    "wslEngineEnabled": {
      "locked": false,
      "value": false
    },
    "dockerDaemonOptions": {
      "locked": false,
      "value":"{\"debug\": false}"
    },
    "vpnkitCIDR": {
      "locked": false,
      "value":"192.168.65.0/24"
    }
  },
  "kubernetes": {
     "locked": false,
     "enabled": false,
     "showSystemContainers": false,
     "imagesRepository": ""
  },
  "windowsContainers": {
    "dockerDaemonOptions": {
      "locked": false,
      "value":"{\"debug\": false}"
    }
  },
  "disableUpdate": {
    "locked": false,
    "value": false
  },
  "analyticsEnabled": {
    "locked": false,
    "value": true
  },
  "extensionsEnabled": {
    "locked": true,
    "value": false
  },
  "scout": {
    "locked": false,
    "sbomIndexing": true,
    "useBackgroundIndexing": true
  },
  "allowExperimentalFeatures": {
    "locked": false,
    "value": false
  },
  "allowBetaFeatures": {
    "locked": false,
    "value": false
  },
  "blockDockerLoad": {
    "locked": false,
    "value": true
  },
  "filesharingAllowedDirectories": [
    {
      "path": "$HOME",
      "sharedByDefault": true
    },
    {
      "path":"$TMP",
      "sharedByDefault": false
    }
  ],
  "useVirtualizationFrameworkVirtioFS": {
    "locked": true,
    "value": true
  },
  "useVirtualizationFrameworkRosetta": {
    "locked": true,
    "value": true
  },
  "useGrpcfuse": {
    "locked": true,
    "value": true
  },
  "displayedOnboarding": {
    "locked": true,
    "value": true
  },
  "desktopTerminalEnabled": {
    "locked": false,
    "value": false
  }
}

General

File sharing and emulation

Docker Scout

Proxy

Container proxy

Linux VM

Windows containers

Note

This setting is not available to configure via the Docker Admin Console.

Kubernetes

Features in development

Enhanced Container Isolation

Step three: Re-launch Docker Desktop

Note

Test the changes made through the admin-settings.json file locally to see if the settings work as expected.

For settings to take effect:

• On a new install, developers need to launch Docker Desktop and authenticate to their organization.
• On an existing install, developers need to quit Docker Desktop through the Docker menu, and then re-launch Docker Desktop. If they are already signed in, they don't need to sign in again for the changes to take effect.

  Important

  Selecting Restart from the Docker menu isn't enough as it only restarts some components of Docker Desktop.

So as not to disrupt your developers' workflow, Docker doesn't automatically mandate that developers re-launch and re-authenticate once a change has been made.

In Docker Desktop, developers see the relevant settings grayed out and the message Locked by your administrator.