From f2ef49f9507f50faf76a57a2d7761b92b1702bb1 Mon Sep 17 00:00:00 2001 From: gotjosh Date: Tue, 1 Oct 2019 09:18:59 +0100 Subject: [PATCH] Docs: LDAP Debug View documentation (#19513) * Docs: Add information regarding the LDAP Debug View * Add instructions to compress image when adding them to the documentation * Add a troubleshooting section to the docs documentation --- docs/README.md | 20 +++++++++++++++----- docs/sources/auth/ldap.md | 19 +++++++++++++++++++ docs/sources/guides/whats-new-in-v6-4.md | 2 +- 3 files changed, 35 insertions(+), 6 deletions(-) diff --git a/docs/README.md b/docs/README.md index 282820117e4..ecdf4f5353a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -61,19 +61,29 @@ Open [localhost:3004](http://localhost:3004) to view the docs. ### Images & Content -All markdown files are located in this repo (main grafana repo). But all images are added to the https://github.com/grafana/website repo. So the process of adding images is a bit complicated. +All markdown files are part of [this repository](https://github.com/grafana/grafana). However, all images are added to the [website repository](https://github.com/grafana/website). Therefore, the process of adding images is not as straightforward. These are the steps: -First you need create a feature (PR) branch of https://github.com/grafana/website so you can make change. Then add the image to the `/static/img/docs` directory. Then make a commit that adds the image. +1. Ensure you create a feature branch within the [website repository](https://github.com/grafana/website) to make the change. This branch needs to be based on the `old-docs` branch. +2. Ensure the image(s) are compressed and optimised e.g. Using [tinypng](https://tinypng.com/) +2. Add the image(s) to the `/static/img/docs` directory +3. Then, make a commit that adds the image(s) +4. The Pull Request you create needs to target where you branched off, the branch `old-docs` -Then run: +Finally, run: ``` make docs-build ``` -This will rebuild the docs docker container. +This will rebuild the docs docker image. -To be able to use the image you have to quit (CTRL-C) the `make watch` command (that you run in the same directory as this README). Then simply rerun `make watch`, it will restart the docs server but now with access to your image. +To be able to use your image(s) you have to quit (CTRL-C) the `make watch` command (that you run in the same directory as this README). Then simply rerun `make watch`, it will restart the docs server but now with access to your image(s). ### Editing content Changes to the markdown files should automatically cause a docs rebuild and live reload should reload the page in your browser. + +### Troubleshooting + +#### Running `make watch` errors out with `Warning: Task "default" not found.` + +Ensure that the docker image from the [website repository](https://github.com/grafana/website) is built using the `old-docs` branch. diff --git a/docs/sources/auth/ldap.md b/docs/sources/auth/ldap.md index ee5189eb7d0..fa12a40c4cf 100644 --- a/docs/sources/auth/ldap.md +++ b/docs/sources/auth/ldap.md @@ -90,6 +90,25 @@ member_of = "memberOf" email = "email" ``` +## LDAP Debug View + +> Only available in Grafana v6.4+ + +Grafana has an LDAP debug view built-in which allows you to test your LDAP configuration directly within Grafana. At the moment of writing, only Grafana admins can use the LDAP debug view. + +Within this view, you'll be able to see which LDAP servers are currently reachable and test your current configuration. + +{{< docs-imagebox img="/img/docs/ldap_debug.png" class="docs-image--no-shadow" max-width="600px" >}} + + +To use the debug view: + + 1. Type the username of a user that exists within any of your LDAP server(s) + 2. Then, press "Run" + 3. If the user is found within any of your LDAP instances, the mapping information is displayed + +{{< docs-imagebox img="/img/docs/ldap_debug_mapping_testing.png" class="docs-image--no-shadow" max-width="600px" >}} + ### Bind #### Bind & Bind Password diff --git a/docs/sources/guides/whats-new-in-v6-4.md b/docs/sources/guides/whats-new-in-v6-4.md index e105c641ea9..ddb49f30d55 100644 --- a/docs/sources/guides/whats-new-in-v6-4.md +++ b/docs/sources/guides/whats-new-in-v6-4.md @@ -117,7 +117,7 @@ You'll be able to see how a user authenticating with LDAP would be mapped and wh The feature is currently limited to Grafana Server Admins. -For more information on how to use this new feature, follow the [guide](TBD). +For more information on how to use this new feature, follow the [guide]({{< relref "auth/ldap.md#ldap-debug-view" >}}). ## Grafana Enterprise