From 87472c45841484a63be19eac9d2f3c3576b6a91a Mon Sep 17 00:00:00 2001
From: Takuya Noguchi <takninnovationresearch@gmail.com>
Date: Wed, 3 Aug 2022 11:21:01 +0000
Subject: [PATCH] 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 | 107 ++++++++++++++++++++-----------
1 file changed, 69 insertions(+), 38 deletions(-)
diff --git a/doc/administration/libravatar.md b/doc/administration/libravatar.md
index eac7c6f848bdd..0e59acde6f01d 100644
--- a/doc/administration/libravatar.md
+++ b/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
--
GitLab