diff --git a/_includes/configure-registry-json.md b/_includes/configure-registry-json.md new file mode 100644 index 0000000000..43f21fc86d --- /dev/null +++ b/_includes/configure-registry-json.md @@ -0,0 +1,64 @@ + + +## Create a registry.json file + +After you’ve successfully installed Docker Desktop, create a `registry.json` +file. Before you create a `registry.json` file, ensure that the developer is a +member of at least one organization in Docker Hub. If the `registry.json` file +matches at least one organization the developer is a member of, they can sign +into Docker Desktop, and then access all their organizations. + +### Windows + +On Windows, you must create a file at +`C:\ProgramData\DockerDesktop\registry.json` with file permissions that ensure +that the developer using Docker Desktop cannot remove or edit the file (that is, +only the system administrator can write to the file). The file must be of type +`JSON` and contain the name of the organization in the `allowedOrgs` key. + +To create your `registry.json` file on Windows: + +1. Open Windows PowerShell and select Run as Administrator. +2. Type the following command `cd /ProgramData/DockerDesktop/` +3. Type `notepad registry.json` and enter the name of the Docker Hub + organization that the developer belongs to in the `allowedOrgs` key and click + **Save**. For example: + + ```json + { + "allowedOrgs": ["myorg"] + } + ``` + +### Mac + +On macOS, you must create a file at `/Library/Application Support/com.docker.docker/registry.json` with file permissions that ensure that +the developer using Docker Desktop cannot remove or edit the file (that is, only +the system administrator can write to the file). The file must be of type `JSON` +and contain the name of the Docker Hub organization names in the `allowedOrgs` +key. + +To create your `registry.json` file on macOS: + +1. Navigate to VS Code or any text editor of your choice. +2. Enter the name of the Docker Hub organization that the developer belongs to in the `allowedOrgs` key and save it in your Documents. For example: + + ```json + { + "allowedOrgs": ["myorg"] + } + ``` + +3. Open a new terminal and type the following command: + + ```console + sudo mkdir -p /Library/Application\ Support/com.docker.docker + ``` + + If prompted, type your password associated with your local computer. + +4. Type the following command: + + ```console + sudo cp Documents/registry.json /Library/Application\ Support/com.docker.docker/registry.json + ``` diff --git a/desktop/index.md b/desktop/index.md index f881f0ee1c..ede5a95826 100644 --- a/desktop/index.md +++ b/desktop/index.md @@ -55,16 +55,20 @@ For information about Docker Desktop licensing, see [Docker Desktop License Agre ## Sign in to Docker Desktop -After you’ve successfully installed and started Docker Desktop, we recommend that you authenticate using the **Sign in/Create ID** option from the Docker menu. +After you’ve successfully installed and started Docker Desktop, we recommend +that you authenticate using the **Sign in/Create ID** option from the Docker +menu. Authenticated users get a higher pull rate limit compared to anonymous users. For example, if you are authenticated, you get 200 pulls per 6 hour period, compared to 100 pulls per 6 hour period per IP address for anonymous users. For more information, see [Download rate limit](../docker-hub/download-rate-limit.md). -Authenticating through Docker Desktop also allows administrators to configure Docker Desktop and set up guardrails using the [Image Access Management](../docker-hub/image-access-management.md) feature to allow team members to: - -* Only have access to Trusted Content on Docker Hub -* Pull only from the specified categories of images - -To authenticate using Docker Desktop, click the **Sign in/Create ID** option on the Docker menu and follow the on-screen instructions. +In large enterprises where admin access is restricted, administrators can create +a `registry.json` file and deploy it to the developers' machines using a device +management software as part of the Docker Desktop installation process. Enforcing developers to authenticate through Docker Desktop also allows +administrators to set up guardrails using features such as +[Image Access Management](../docker-hub/image-access-management.md) which allows team +members to only have access to Trusted Content on Docker Hub, and pull only from +the specified categories of images. For more information, see +[Configure registry.json to enforce sign in](../docker-hub/configure-sign-in.md). ## Configure Docker Desktop diff --git a/docker-hub/configure-sign-in.md b/docker-hub/configure-sign-in.md index abfe9d1458..78df116588 100644 --- a/docker-hub/configure-sign-in.md +++ b/docker-hub/configure-sign-in.md @@ -21,65 +21,7 @@ Deploying a `registry.json` file and forcing users to authenticate offers the fo 2. Authenticated users get a higher pull rate limit compared to anonymous users. For example, if you are authenticated, you get 200 pulls per 6 hour period, compared to 100 pulls per 6 hour period per IP address for anonymous users. For more information, see [Download rate limit](download-rate-limit.md). 3. Blocks users from accessing Docker Desktop until they are added to a specific organization. -## Create a registry.json file - -Before you create a `registry.json` file, ensure that the user is a member of at least one organization in Docker Hub. If the `registry.json` file matches at least one organization the user is a member of, they can sign into Docker Desktop, and then access all their organizations. - -### Windows - -On Windows, you must create a file at -`C:\ProgramData\DockerDesktop\registry.json` with file permissions that ensure -that the developer using Docker Desktop cannot remove or edit the file (that is, -only the system administrator can write to the file). The file must be of type -`JSON` and contain the name of the organization in the `allowedOrgs` key. - -To create your `registry.json` file on Windows: - -1. Open Windows Powershell and select Run as Administrator. -2. Type the following command `cd /ProgramData/DockerDesktop/` -3. Type `notepad registry.json` and enter the name of the Docker Hub - organization that the user belongs to in the `allowedOrgs` key and click - **Save**. For example: - - ```json - { - "allowedOrgs": ["myorg"] - } - ``` - -### Mac - -On macOS, you must create a file at `/Library/Application Support/com.docker.docker/registry.json` with file permissions that ensure that -the developer using Docker Desktop cannot remove or edit the file (that is, only -the system administrator can write to the file). The file must be of type `JSON` -and contain the name of the Docker Hub organization names in the `allowedOrgs` -key. - -To create your `registry.json` file on macOS: - -1. Navigate to VS Code or any text editor of your choice. -2. Enter the name of the Docker Hub organization that the user belongs to in the - `allowedOrgs` key and save it in your Documents. For example: - - ```json - { - "allowedOrgs": ["myorg"] - } - ``` - -3. Open a new terminal and type the following command: - - ```console - sudo mkdir -p /Library/Application\ Support/com.docker.docker - ``` - - If prompted, type your password associated with your local computer. - -4. Type the following command: - - ```console - sudo cp Documents/registry.json /Library/Application\ Support/com.docker.docker/registry.json - ``` +{% include configure-registry-json.md %} ## Verify the changes diff --git a/docker-hub/image-access-management.md b/docker-hub/image-access-management.md index 4fce1ebad6..18c5149367 100644 --- a/docker-hub/image-access-management.md +++ b/docker-hub/image-access-management.md @@ -38,7 +38,7 @@ To configure Image Access Management permissions, perform the following steps: 4. Select the category restrictions for your images by clicking **Allowed**. 5. Once the restrictions are applied, your members can view the Org permissions page in a read-only format. -### Enforce authentication +## Enforce authentication To ensure that each org member uses images in a safe and secure environment, you can perform the following steps below to enforce sign-in under your @@ -58,62 +58,9 @@ Download Docker Desktop 4.0 or a later release. > restrictions as Mac and Windows users while logged in. However, there is > currently no way to enforce Linux users to log in. -#### Create a registry json file +{% include configure-registry-json.md %} -After you've successfully installed Docker Desktop, create a `registry.json` file on Windows or Mac. - -**On Windows** - -Create a file `C:\ProgramData\DockerDesktop\registry.json` with file permissions that ensure that the developer using Docker Desktop cannot remove or edit the file (i.e., only the system administrator can write to the file). The file must be JSON and contain one or more organization names in the `allowedOrgs` key. - -To create your `registry.json` file on Windows: - -1. Open Windows Powershell and select Run as Administrator. -2. Type the following command: `cd /ProgramData/DockerDesktop/` -3. In Notepad, type `registry.json` and enter one or more organization names in the `allowedOrgs` key and click Save. - - For example: - - ```json - { - "allowedOrgs": ["mycompany"] - } - ``` - -4. Navigate to Powershell and type ```start .``` - -Congratulations! You have just created the registry.json file. - -**On macOS**: - -Create a file `/Library/Application Support/com.docker.docker/registry.json` with file permissions that ensure that the developer using Docker Desktop cannot remove or edit the file (i.e., only the system administrator can write to the file). The file must be JSON and contain one or more organization names in the `allowedOrgs` key. The user must sign in and be a member of at least one of the organizations before using Docker Desktop. - -To create your `registry.json` file on macOS: - -1. Navigate to VS Code or any text editor of your choice. -2. Enter one or more organization names in the `allowedOrgs` key and save it in your Documents. - - For example: - - ```json - { - "allowedOrgs": ["mycompany"] - } - ``` - - 3. Open a new terminal and type the following command: - - `sudo mkdir -p /Library/Application\ Support/com.docker.docker` - - Note: if prompted, type your password associated with your local computer. - -4. Type the following command: - - `sudo cp Documents/registry.json /Library/Application\ Support/com.docker.docker/registry.json` - -Congratulations! You have just created the `registry.json` file. - -### Verify the restrictions +## Verify the restrictions To confirm that the restrictions are successful, have each org member pull an image onto their local computer after signing into Docker Desktop. If they are unable to sign in, they will receive an error message. diff --git a/docker-hub/registry-access-management.md b/docker-hub/registry-access-management.md index d601833786..4a7180635e 100644 --- a/docker-hub/registry-access-management.md +++ b/docker-hub/registry-access-management.md @@ -32,7 +32,7 @@ To configure Registry Access Management permissions, perform the following steps ![Registry Access Management](images/registry-access-management.png){:width="700px"} -### Enforce authentication +## Enforce authentication To ensure that each org member uses Registry Access Management on their local machine, you can perform the steps below to enforce sign-in under your organization. To do this: @@ -44,56 +44,9 @@ Download Docker Desktop 4.5 or a later release. - [Download and install for Windows](/desktop/windows/install/) - [Download and install for Mac](/desktop/mac/install/) -#### Create a registry json file +{% include configure-registry-json.md %} -Before you create a `registry.json` file, ensure that the developer is a member of at least one organization in Docker Hub. If the registry.json file matches at least one organization the developer is a member of, they can sign into Docker Desktop and access all of their organizations. - -**On Windows** - -On Windows, you must create a file `C:\ProgramData\DockerDesktop\registry.json` with file permissions that ensure that the developer using Docker Desktop cannot remove or edit the file (that is, only the system administrator can write to the file). The file must be `JSON` and contain one or more organization names in the `allowedOrgs` key. - -To create your `registry.json` file on Windows: - -1. Open Windows PowerShell and select **Run as Administrator**. -2. Type the following command: `cd /ProgramData/DockerDesktop/` -3. Type `notepad registry.json` and enter the Docker Hub organization that the developer belongs to in `allowedOrgs` key and click **Save**. - - For example: - - ```json - { - "allowedOrgs": ["myorg"] - } - ``` - -**On macOS**: - -On macOS, you must create a file at `/Library/Application Support/com.docker.docker/registry.json` with file permissions that ensure that the developer using Docker Desktop cannot remove or edit the file (that is, only the system administrator can write to the file). The file must be of type JSON and contain the name of the Docker Hub organization in the `allowedOrgs` key (using one organization name instead of multiple organizations). - -To create your `registry.json` file on macOS: - -1. Navigate to Visual Studio Code or any text editor of your choice. -2. Enter one or more organization names in the `allowedOrgs` key and save it in your Documents. - - For example: - - ```json - { - "allowedOrgs": ["myorg"] - } - ``` - - 3. Open a new terminal and type the following command: - - `sudo mkdir -p /Library/Application\ Support/com.docker.docker` - - Note: if prompted, type your password associated with your local computer. - -4. Type the following command: - - `sudo cp Documents/registry.json /Library/Application\ Support/com.docker.docker/registry.json` - -### Verify the restrictions +## Verify the restrictions After you’ve created the registry.json file and deployed it onto the developers’ machines, you can verify whether the changes have taken effect by asking the developers to start Docker Desktop.