Configure Settings Management

Note

Settings Management is available to Docker Business customers only.

This page contains information for admins on how to configure Settings Management to specify and lock configuration parameters to create a standardized Docker Desktop environment across the organization.

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

Prerequisites

• Download and install Docker Desktop 4.13.0 or later.
• As an administrator, you need to enforce sign-in. This is because this feature requires a Docker Business subscription and therefore your Docker Desktop users must authenticate to your organization for this configuration to take effect. Enforcing sign-in ensures that your Docker Desktop developers always authenticate to your organization, even though they can authenticate without it and the feature will take effect. Enforcing sign-in guarantees the feature always takes effect.

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 the above protected directories, end users 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 above 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 Windows. This is highlighted in the table below.

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 UI, 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 we don't alter these values. These can be controlled by the admin 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
  }
}

Step three: Re-launch Docker Desktop

Note

Administrators should 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 relaunch 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.

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

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