Copyedit Dependency Proxy docs

3 files changed, 139 insertions, 99 deletions

diff --git a/doc/administration/dependency_proxy.md b/doc/administration/dependency_proxy.md
index 5522073f597..0a8416d551f 100644
--- a/doc/administration/dependency_proxy.md
+++ b/doc/administration/dependency_proxy.md
@@ -1,14 +1,17 @@
 # GitLab Dependency Proxy administration **[PREMIUM ONLY]**
 
-GitLab Packages allows organizations to utilize GitLab as a dependency proxy 
-for a variety of common package managers.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing) 11.11.
 
-Currently only dependency proxy for container registry is supported.
+NOTE: **Note:**
+This is the administration documentation. If you want to learn how to use the
+dependency proxies, see the [user guide](../user/group/dependency_proxy/index.md).
+
+GitLab can be utilized as a dependency proxy for a variety of common package managers.
 
-## Enabling the Packages feature
+## Enabling the Dependency Proxy feature
 
 NOTE: **Note:**
-Dependency proxy requires Puma web server to be enabled.
+Dependency proxy requires the Puma web server to be enabled.
 Puma support is EXPERIMENTAL at this time.
 
 To enable the Dependency proxy feature:
@@ -17,44 +20,45 @@ To enable the Dependency proxy feature:
 
 1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
 
-    ```ruby
-    gitlab_rails['dependency_proxy_enabled'] = true
-    ```
+   ```ruby
+   gitlab_rails['dependency_proxy_enabled'] = true
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
-1. Enable [Puma web server](https://docs.gitlab.com/omnibus/settings/puma.html). 
+1. Enable the [Puma web server](https://docs.gitlab.com/omnibus/settings/puma.html).
 
 **Installations from source**
 
 1. After the installation is complete, you will have to configure the `dependency_proxy`
    section in `config/gitlab.yml`. Set to `true` to enable it:
 
-      ```yaml
-      dependency_proxy:
-        enabled: true
-      ```
+   ```yaml
+   dependency_proxy:
+     enabled: true
+   ```
+
 1. [Restart GitLab] for the changes to take effect.
-1. Enable Puma web server. Documentation [is not ready yet](https://gitlab.com/gitlab-org/gitlab-ce/issues/61376)
+1. Enable the Puma web server. Documentation [is not ready yet](https://gitlab.com/gitlab-org/gitlab-ce/issues/61376)
 
 ## Changing the storage path
 
-By default, dependency proxy files are stored locally, but you can change the default
+By default, the dependency proxy files are stored locally, but you can change the default
 local location or even use object storage.
 
 ### Changing the local storage path
 
 The dependency proxy files for Omnibus GitLab installations are stored under
 `/var/opt/gitlab/gitlab-rails/shared/dependency_proxy/` and for source
-installations under `shared/dependency_proxy/` (relative to the git homedir).
+installations under `shared/dependency_proxy/` (relative to the git home directory).
 To change the local storage path:
 
 **Omnibus GitLab installations**
 
 1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
 
-    ```ruby
-    gitlab_rails['dependency_proxy_storage_path'] = "/mnt/dependency_proxy"
-    ```
+   ```ruby
+   gitlab_rails['dependency_proxy_storage_path'] = "/mnt/dependency_proxy"
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -62,48 +66,48 @@ To change the local storage path:
 
 1. Edit the `dependency_proxy` section in `config/gitlab.yml`:
 
-      ```yaml
-      dependency_proxy:
-        enabled: true
-        storage_path: shared/dependency_proxy
-      ```
+   ```yaml
+   dependency_proxy:
+     enabled: true
+     storage_path: shared/dependency_proxy
+   ```
 1. [Restart GitLab] for the changes to take effect.
 
 ### Using object storage
 
 Instead of relying on the local storage, you can use an object storage to
-upload dependency_proxy:
+upload the blobs of the dependency proxy:
 
 **Omnibus GitLab installations**
 
 1. Edit `/etc/gitlab/gitlab.rb` and add the following lines (uncomment where
    necessary):
 
-    ```ruby
-    gitlab_rails['dependency_proxy_enabled'] = true
-    gitlab_rails['dependency_proxy_storage_path'] = "/var/opt/gitlab/gitlab-rails/shared/dependency_proxy"
-    gitlab_rails['dependency_proxy_object_store_enabled'] = true
-    gitlab_rails['dependency_proxy_object_store_remote_directory'] = "dependency_proxy" # The bucket name.
-    gitlab_rails['dependency_proxy_object_store_direct_upload'] = false         # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false).
-    gitlab_rails['dependency_proxy_object_store_background_upload'] = true      # Temporary option to limit automatic upload (Default: true).
-    gitlab_rails['dependency_proxy_object_store_proxy_download'] = false        # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
-    gitlab_rails['dependency_proxy_object_store_connection'] = {
-      ##
-      ## If the provider is AWS S3, uncomment the following
-      ##
-      #'provider' => 'AWS',
-      #'region' => 'eu-west-1',
-      #'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
-      #'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY',
-      ##
-      ## If the provider is other than AWS (an S3-compatible one), uncomment the following
-      ##
-      #'host' => 's3.amazonaws.com',
-      #'aws_signature_version' => 4             # For creation of signed URLs. Set to 2 if provider does not support v4.
-      #'endpoint' => 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
-      #'path_style' => false                    # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.
-    }
-    ```
+   ```ruby
+   gitlab_rails['dependency_proxy_enabled'] = true
+   gitlab_rails['dependency_proxy_storage_path'] = "/var/opt/gitlab/gitlab-rails/shared/dependency_proxy"
+   gitlab_rails['dependency_proxy_object_store_enabled'] = true
+   gitlab_rails['dependency_proxy_object_store_remote_directory'] = "dependency_proxy" # The bucket name.
+   gitlab_rails['dependency_proxy_object_store_direct_upload'] = false         # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false).
+   gitlab_rails['dependency_proxy_object_store_background_upload'] = true      # Temporary option to limit automatic upload (Default: true).
+   gitlab_rails['dependency_proxy_object_store_proxy_download'] = false        # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
+   gitlab_rails['dependency_proxy_object_store_connection'] = {
+     ##
+     ## If the provider is AWS S3, uncomment the following
+     ##
+     #'provider' => 'AWS',
+     #'region' => 'eu-west-1',
+     #'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
+     #'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY',
+     ##
+     ## If the provider is other than AWS (an S3-compatible one), uncomment the following
+     ##
+     #'host' => 's3.amazonaws.com',
+     #'aws_signature_version' => 4             # For creation of signed URLs. Set to 2 if provider does not support v4.
+     #'endpoint' => 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
+     #'path_style' => false                    # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.
+   }
+   ```
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
@@ -111,35 +115,35 @@ upload dependency_proxy:
 
 1. Edit the `dependency_proxy` section in `config/gitlab.yml` (uncomment where necessary):
 
-    ```yaml
-      dependency_proxy:
-        enabled: true
-        ##
-        ## The location where build dependency_proxy are stored (default: shared/dependency_proxy).
-        ##
-        #storage_path: shared/dependency_proxy
-        object_store:
-          enabled: false
-          remote_directory: dependency_proxy # The bucket name.
-          #direct_upload: false      # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false).
-          #background_upload: true   # Temporary option to limit automatic upload (Default: true).
-          #proxy_download: false     # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
-          connection:
-            ##
-            ## If the provider is AWS S3, uncomment the following
-            ##
-            #provider: AWS
-            #region: us-east-1
-            #aws_access_key_id: AWS_ACCESS_KEY_ID
-            #aws_secret_access_key: AWS_SECRET_ACCESS_KEY
-            ##
-            ## If the provider is other than AWS (an S3-compatible one), uncomment the following
-            ##
-            #host: 's3.amazonaws.com'             # default: s3.amazonaws.com.
-            #aws_signature_version: 4             # For creation of signed URLs. Set to 2 if provider does not support v4.
-            #endpoint: 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
-            #path_style: false                    # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.
-    ```
+   ```yaml
+   dependency_proxy:
+     enabled: true
+     ##
+     ## The location where build dependency_proxy are stored (default: shared/dependency_proxy).
+     ##
+     #storage_path: shared/dependency_proxy
+     object_store:
+       enabled: false
+       remote_directory: dependency_proxy # The bucket name.
+       #direct_upload: false      # Use Object Storage directly for uploads instead of background uploads if enabled (Default: false).
+       #background_upload: true   # Temporary option to limit automatic upload (Default: true).
+       #proxy_download: false     # Passthrough all downloads via GitLab instead of using Redirects to Object Storage.
+       connection:
+         ##
+         ## If the provider is AWS S3, uncomment the following
+         ##
+         #provider: AWS
+         #region: us-east-1
+         #aws_access_key_id: AWS_ACCESS_KEY_ID
+         #aws_secret_access_key: AWS_SECRET_ACCESS_KEY
+         ##
+         ## If the provider is other than AWS (an S3-compatible one), uncomment the following
+         ##
+         #host: 's3.amazonaws.com'             # default: s3.amazonaws.com.
+         #aws_signature_version: 4             # For creation of signed URLs. Set to 2 if provider does not support v4.
+         #endpoint: 'https://s3.amazonaws.com' # Useful for S3-compliant services such as DigitalOcean Spaces.
+         #path_style: false                    # If true, use 'host/bucket_name/object' instead of 'bucket_name.host/object'.
+   ```
 
 1. [Restart GitLab] for the changes to take effect.
 
diff --git a/doc/user/group/dependency_proxy/img/group_dependency_proxy.png b/doc/user/group/dependency_proxy/img/group_dependency_proxy.png
index c4429f29634..035aff0b6c4 100644
--- a/doc/user/group/dependency_proxy/img/group_dependency_proxy.png
+++ b/doc/user/group/dependency_proxy/img/group_dependency_proxy.png
diff --git a/doc/user/group/dependency_proxy/index.md b/doc/user/group/dependency_proxy/index.md
index 649b48361fc..6fc2fa7e3af 100644
--- a/doc/user/group/dependency_proxy/index.md
+++ b/doc/user/group/dependency_proxy/index.md
@@ -1,34 +1,70 @@
-# Dependency Proxy
+# Dependency Proxy **[PREMIUM]**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7934) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.11.
 
-To access the dependency proxy, navigate to a group's sidebar and select **Overview > Dependency Proxy**.
+NOTE: **Note:**
+This is the user guide. In order to use the dependency proxy, an administrator
+must first [configure it](../../../administration/dependency_proxy.md).
+
+For many organizations, it is desirable to have a local proxy for frequently used
+upstream images/packages. In the case of CI/CD, the proxy is responsible for
+receiving a request and returning the upstream image from a registry, acting
+as a pull-through cache.
+
+The dependency proxy is available in the group level. To access it, navigate to
+a group's **Overview > Dependency Proxy**.
 
 ![Dependency Proxy group page](img/group_dependency_proxy.png)
 
-Currently, only dependency proxy for containers is supported. See 
-[direction page](https://about.gitlab.com/direction/package/dependency_proxy/#top-vision-items)
-for further plans.
+## Supported dependency proxies
+
+NOTE: **Note:**
+For a list of the upcoming additions to the proxies, visit the
+[direction page](https://about.gitlab.com/direction/package/dependency_proxy/#top-vision-items).
+
+The following dependency proxies are supported.
+
+| Dependency proxy | GitLab version |
+| ---------------- | -------------- |
+| Docker           | 11.11+         |
+
+## Using the Docker dependency proxy
+
+With the Docker dependency proxy, you can use GitLab as a source for a Docker image.
+To get a Docker image into the dependency proxy:
+
+1. Find the proxy URL on your group's page under **Overview > Dependency Proxy**,
+   for example `gitlab.com/groupname/dependency_proxy/containers`.
+1. Trigger GitLab to pull the Docker image you want (e.g., `alpine:latest`) and
+   store it in the proxy storage by using one of the following ways:
+
+   - Manually pulling the Docker image:
+
+     ```bash
+     docker pull gitlab.com/groupname/dependency_proxy/containers/alpine:latest
+     ```
 
-## Dependency proxy for containers
+   - From a `Dockerfile`:
 
-In order to be used, the feature [must be configured](../../../administration/dependency_proxy.md) by administrator
+     ```bash
+     FROM gitlab.com/groupname/dependency_proxy/containers/alpine:latest
+     ```
 
-### How it works
+   - In [`.gitlab-ci.yml`](../../../ci/yaml/README.md#image):
 
-You use your GitLab URL as a source for a docker image. 
-You can find the URL on a group page displayed above.
+     ```bash
+     image: gitlab.com/groupname/dependency_proxy/containers/alpine:latest
+     ```
 
-```
-docker pull gitlab.example.com/MY_GROUP/dependency_proxy/containers/alpine:latest
-```
+GitLab will then pull the Docker image from Docker Hub and will cache the blobs
+on the GitLab server. The next time you pull the same image, it will get the latest
+information about the image from Docker Hub but will serve the existing blobs
+from GitLab.
 
-GitLab will pull a docker image from Docker Hub. Then it will cache blobs on the 
-GitLab server. Next time you pull the same image, it will get the latest information about
-the image from Docker Hub but will serve existing blobs from the GitLab server.
+## Limitations
 
-### Limitations
+The following limitations apply:
 
-* Only public groups are supported (authentication is not supported yet).
-* Only Docker Hub is supported now.
-* The feature requires Docker Hub being available.
+- Only public groups are supported (authentication is not supported yet).
+- Only Docker Hub is supported.
+- This feature requires Docker Hub being available.