Improve gravatar service administration docs

Add doc about disabling gravatar service.
Add doc about changing the customized gravatar settings to the default.
Follow the formatting for Omnibus/source installations.

Signed-off-by: Takuya Noguchi <takninnovationresearch@gmail.com>
Changelog: other

doc/administration/libravatar.md

@@ -11,63 +11,94 @@ GitLab by default supports the [Gravatar](https://gravatar.com) avatar service.
 
 Libravatar is another service that delivers your avatar (profile picture) to
 other websites. The Libravatar API is
-[heavily based on gravatar](https://wiki.libravatar.org/api/), so you can
+[heavily based on Gravatar](https://wiki.libravatar.org/api/), so you can
 switch to the Libravatar avatar service or even your own Libravatar
 server.
 
-## Configuration
+## Change the Libravatar service to your own one
 
-In the [`gitlab.yml` gravatar section](https://gitlab.com/gitlab-org/gitlab/-/blob/672bd3902d86b78d730cea809fce312ec49d39d7/config/gitlab.yml.example#L122), set
+In the [`gitlab.yml` gravatar section](https://gitlab.com/gitlab-org/gitlab/-/blob/68dac188ec6b1b03d53365e7579422f44cbe7a1c/config/gitlab.yml.example#L469-476), set
 the configuration options as follows:
 
-### For HTTP
+**For Omnibus installations**
 
-```yaml
-  gravatar:
-    enabled: true
-    # gravatar URLs: possible placeholders: %{hash} %{size} %{email} %{username}
-    plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
-```
+1. Edit `/etc/gitlab/gitlab.rb`:
 
-### For HTTPS
+   ```ruby
+   gitlab_rails['gravatar_enabled'] = true
+   #### For HTTPS
+   gitlab_rails['gravatar_ssl_url'] = "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
+   #### Use this line instead for HTTP
+   # gitlab_rails['gravatar_plain_url'] = "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
+   ```
 
-```yaml
-  gravatar:
-    enabled: true
-    # gravatar URLs: possible placeholders: %{hash} %{size} %{email} %{username}
-    ssl_url: "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
-```
+1. Then run `sudo gitlab-ctl reconfigure` for the changes to take effect.
 
-### Your own Libravatar server
+**For installations from source**
 
-If you are [running your own Libravatar service](https://wiki.libravatar.org/running_your_own/),
-the URL is different in the configuration, but you must provide the same
-placeholders so GitLab can parse the URL correctly.
+1. Edit `config/gitlab.yml`:
 
-For example, you host a service on `http://libravatar.example.com` and the
-`plain_url` you must supply in `gitlab.yml` is
+   ```yaml
+     gravatar:
+       enabled: true
+       # default: https://www.gravatar.com/avatar/%{hash}?s=%{size}&d=identicon
+       plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
+       # default: https://secure.gravatar.com/avatar/%{hash}?s=%{size}&d=identicon
+       ssl_url: https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
+   ```
 
-`http://libravatar.example.com/avatar/%{hash}?s=%{size}&d=identicon`
+1. Save the file, and then [restart](restart_gitlab.md#installations-from-source)
+   GitLab for the changes to take effect.
 
-### Omnibus GitLab example
+## Set the Libravatar service to default (Gravatar)
 
-In `/etc/gitlab/gitlab.rb`:
+**For Omnibus installations**
 
-#### For HTTP
+1. Delete `gitlab_rails['gravatar_ssl_url']` or `gitlab_rails['gravatar_plain_url']` from `/etc/gitlab/gitlab.rb`.
+1. Then run `sudo gitlab-ctl reconfigure` for the changes to take effect.
 
-```ruby
-gitlab_rails['gravatar_enabled'] = true
-gitlab_rails['gravatar_plain_url'] = "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
-```
+**For installations from source**
 
-#### For HTTPS
+1. Remove `gravatar:` section from `config/gitlab.yml`.
+1. Save the file, and then [restart](restart_gitlab.md#installations-from-source)
+   GitLab for the changes to take effect.
 
-```ruby
-gitlab_rails['gravatar_enabled'] = true
-gitlab_rails['gravatar_ssl_url'] = "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=identicon"
-```
+## Disable Gravatar service
+
+For some reasons such as prohibiting to third-party service, you can disable Gravatar service as follows:
+
+**For Omnibus installations**
+
+1. Edit `/etc/gitlab/gitlab.rb`:
+
+   ```ruby
+   gitlab_rails['gravatar_enabled'] = false
+   ```
+
+1. Then run `sudo gitlab-ctl reconfigure` for the changes to take effect.
+
+**For installations from source**
+
+1. Edit `config/gitlab.yml`:
+
+   ```yaml
+     gravatar:
+       enabled: false
+   ```
+
+1. Save the file, and then [restart](restart_gitlab.md#installations-from-source)
+   GitLab for the changes to take effect.
+
+### Your own Libravatar server
+
+If you are [running your own Libravatar service](https://wiki.libravatar.org/running_your_own/),
+the URL is different in the configuration, but you must provide the same
+placeholders so GitLab can parse the URL correctly.
+
+For example, you host a service on `https://libravatar.example.com` and the
+`ssl_url` you must supply in `gitlab.yml` is:
 
-Then run `sudo gitlab-ctl reconfigure` for the changes to take effect.
+`https://libravatar.example.com/avatar/%{hash}?s=%{size}&d=identicon`
 
 ## Default URL for missing images
 
@@ -77,7 +108,7 @@ service.
 
 To use a set other than `identicon`, replace the `&d=identicon` portion of the
 URL with another supported set. For example, you can use the `retro` set, in
-which case the URL would look like: `plain_url: "http://cdn.libravatar.org/avatar/%{hash}?s=%{size}&d=retro"`
+which case the URL would look like: `ssl_url: "https://seccdn.libravatar.org/avatar/%{hash}?s=%{size}&d=retro"`
 
 ## Usage examples for Microsoft Office 365