From 60c89b306f06cefcf5036d3e43ca48858adecfc1 Mon Sep 17 00:00:00 2001
From: Sebastiaan van Stijn <github@gone.nl>
Date: Wed, 27 Jul 2022 22:10:21 +0200
Subject: [PATCH] fix instructions for registry.json

The previous instructions fixed situations where the directory
and file didn't exist, but had some issues remaining;

The `>>` _appends_ the content to the file; this would work if the file didn't
exist (before `touch`'ing it) but if there happened to be a file already, it
would append the content to the existing file, resulting in invalid JSON.

e.g. running it twice (which may be accidentally);

```bash
sudo echo '{"allowedOrgs":["myorg"]}' >> "/Library/Application Support/com.docker.docker/registry.json"
sudo echo '{"allowedOrgs":["myorg"]}' >> "/Library/Application Support/com.docker.docker/registry.json"
```

Would result in;

```bash
sudo cat "/Library/Application Support/com.docker.docker/registry.json"
{"allowedOrgs":["myorg"]}
{"allowedOrgs":["myorg"]}
```

(which is invalid JSON)

The `sudo echo` also had some issues; the `sudo` only applied to the `echo`, and
not to the piped output (see https://unix.stackexchange.com/questions/1416/redirecting-stdout-to-a-file-you-dont-have-write-permission-on);

```bash
$ sudo touch "/Library/Application Support/com.docker.docker/registry.json"
$ sudo echo '{"allowedOrgs":["myorg"]}' > "/Library/Application Support/com.docker.docker/registry.json"
bash: /Library/Application Support/com.docker.docker/registry.json: Permission denied
```

Instead, using `tee` to run as privileged process, similar to the approach taken
in https://github.com/docker/docker.github.io/blame/c33d39a7ba80ad86e3d6f1bd38f21e530d58819e/engine/install/debian.md#L106

With that, the `touch` wouldn't be needed (the `mkdir` still would though);

```suggestion
$ sudo mkdir -p "/Library/Application Support/com.docker.docker"
$ echo '{"allowedOrgs":["myorg"]}' | sudo tee "/Library/Application Support/com.docker.docker/registry.json"
```

The new instructions will always overwrite the content with the new content,
replacing what's already there (that may need a small warning / note though) to
prevent the invalid JSON if someone runs the command multiple times, or if they
have to update the existing config with a new one.

Finally, some verification steps were added to verify content and permissions.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
---
 _includes/configure-registry-json.md | 32 ++++++++++++++++++++++------
 1 file changed, 25 insertions(+), 7 deletions(-)

diff --git a/_includes/configure-registry-json.md b/_includes/configure-registry-json.md
index 20b5bf1c3f..0ef2727ccd 100644
--- a/_includes/configure-registry-json.md
+++ b/_includes/configure-registry-json.md
@@ -72,7 +72,7 @@ On Mac, you can use the following methods to create a `registry.json` file.
 
 To automatically create a registry.json file when installing Docker Desktop, download `Docker.dmg` and run the following commands in a terminal from the directory containing `Docker.dmg`. Replace `myorg` with your organization's name.
 
-```bash
+```console
 $ sudo hdiutil attach Docker.dmg 
 $ sudo /Volumes/Docker/Docker.app/Contents/MacOS/install --allowed-org=myorg
 $ sudo hdiutil detach /Volumes/Docker
@@ -80,14 +80,32 @@ $ sudo hdiutil detach /Volumes/Docker
 
 ####  Create registry.json manually on Mac
 
-To manually create a `registry.json` file, run the following commands in a terminal and replace `myorg` with your organization's name.
+To manually create a `registry.json` file, run the following commands in a terminal
+and replace `myorg` with your organization's name.
 
-```bash
+```console
 $ sudo mkdir -p "/Library/Application Support/com.docker.docker"
-$ sudo touch "/Library/Application Support/com.docker.docker/registry.json"
-$ sudo echo '{"allowedOrgs":["myorg"]}' >> "/Library/Application Support/com.docker.docker/registry.json"
+$ echo '{"allowedOrgs":["myorg"]}' | sudo tee "/Library/Application Support/com.docker.docker/registry.json"
 ```
 
-This creates the `registry.json` file at `/Library/Application Support/com.docker.docker/registry.json` and includes the organization information the user belongs to. Make sure this file can't be edited by the user, only by the administrator.
+This creates (or updates, if the file already exists) the `registry.json` file
+at `/Library/Application Support/com.docker.docker/registry.json` and includes
+the organization information the user belongs to. Make sure the file has the
+expected content and can't be edited by the user, only by the administrator.
 
-</div></div>
\ No newline at end of file
+Verify that the content of the file contains the correct information;
+
+```console
+$ sudo cat "/Library/Application Support/com.docker.docker/registry.json"
+{"allowedOrgs":["myorg"]}
+```
+
+Verify that the file has the expected permissions (`-rw-r--r--`) and ownership
+(`root` and `admin`):
+
+```console
+$ sudo ls -l "/Library/Application Support/com.docker.docker/registry.json"
+-rw-r--r--  1 root  admin  26 Jul 27 22:01 /Library/Application Support/com.docker.docker/registry.json
+```
+
+</div></div>