[OPENDJ-5095] Add a DS Getting Started guide for beginners Created: 18/May/18  Updated: 08/Nov/19  Resolved: 01/Jun/18

Status: Done
Project: OpenDJ
Component/s: documentation, ease of use
Affects Version/s: 6.5.0
Fix Version/s: 6.5.0

Type: New Feature Priority: Major
Reporter: Jean-Noël Rouvignac Assignee: Mark Craig
Resolution: Fixed Votes: 0
Labels: None

Epic Link: Miscellaneous 6.5
Story Points: 8
Dev Assignee: Mark Craig

 Description   

DS docs favor trained and expert readers who have already had a helping hand to get started with directory services in general and ForgeRock DS in particular.

A Getting Started guide would offer a helping hand to beginners and readers who manage applications or services that consume directory services, but who do not know much about directory services.

Readers of the guide could expect to get a hands-on start with directory services within an hour, whereas a full training course requires a commitment of up to several days. To achieve this, the guide would willfully omit all the but the most common features, demonstrating only how to set up a server and perform common operations. It would, however, explain where to go as a follow up, assuming the reader is interested in learning more.

 

The getting started scenario should demonstrate the strengths of OpenDJ, namely multimaster replication, performance, etc.

Here are suggested steps for demonstrating multimaster replication:

  1. Install two directory servers
  2. Configure replication between them
  3. Add an entry on DS1
  4. Search on DS1 to verify the entry exists there
  5. Search on DS2 to verify the entry has been replicated
  6. Stop DS2 to simulate a network partition / server crash / etc.
  7. Modify the previously added entry on DS1
  8. Search on DS1 to verify the entry has been modified there
  9. Start DS2 to simulate a server recovery
  10. Search on DS2 to verify the entry has been modified there too
  11. Offer the reader to do the following exercise: restart at step 6. by stopping DS1 and modifying the entry on DS2, to demonstrate this is not the usual active-passive setup

Here are suggested steps for demonstrating performance:

  1. run modrate on DS1 for 10 seconds
  2. notice the number of requests happening
  3. run ldapsearch on cn=monitor to see the number of update appearing there?
  4. run searchrate on DS1 for 10 seconds
  5. notice the number of requests happening (this leaves replication the time to replicate all changes)
  6. then, should we run ldapsearch to export all entries from the two servers and use ldif-diff to verify they are the same on both servers?


 Comments   
Comment by Mark Craig [ 18/May/18 ]

Jean-Noël Rouvignac, "hands-on start with directory services within an hour" ?

What should we assume that "beginners" already know?

Comment by Jean-Noël Rouvignac [ 18/May/18 ]

What should we assume that "beginners" already know?

We should assume they know nothing at all. This is the target audience for getting started guides.

However do not spend too much time or energy explaining all the details. We do not want to lose the reader with uninteresting details at this stage.

For example, when describing what LDIF is (before adding an entry), using a very simple sentence is enough. For example, the first sentence in wikipedia articles make up for a good and succinct introduction.

Comment by Mark Craig [ 18/May/18 ]

It sounds like we want to:

  • Start with basic concepts for complete beginners
  • Keep the guide short so as not to put readers off
  • Address replication and multiple servers

One compromise would be to cover basic examples to introduce the key LDAP concepts, explain replication briefly, and then provide a scripted or interactive demonstration for replication that covers the items in the description. The guide could link to other documentation for details as necessary.

Unfortunately, the cost of making this work on Windows as well as UNIX looks high. Going to go with UNIX and shell as a first approximation.

Comment by Mark Craig [ 01/Jun/18 ]

Patch for new guide is merged, https://ea.forgerock.com/docs/ds/getting-started/

Waiting for Jenkins to build it.

Comment by Matthew Swift [ 07/Nov/19 ]

Moved to closed state because the fixVersion has already been released.

Generated at Sat Feb 27 21:39:56 UTC 2021 using Jira 7.13.12#713012-sha1:6e07c38070d5191bbf7353952ed38f111754533a.