[doc] apacheds v2.0 docs

[Ross West <ro...@crsnetworks.ca>]

Hey there,

I've just got started with ADS and thought that it would be easier to
start with v2.0 rather than v1.5 for a new setup. (Yes I know that v2.0
is true beta - I'm not in production, and I'm a sucker for punishment I
guess)

Anyways, I'm in the process of doing up my own internal sysadmin
oriented docs here for v2.0 and with the lack of any public
documentation for it I can probably do mine up in a generic format for
the ADS website if there's any interest.

Initially I've got a full walk-through of ADS w/ ldap+kerb for debian,
(server+clients) plus a bunch of supplemental stuff (sysadmin oriented -
like logging, security, gotchas, etc). 

Cheers,
  Ross.

Re: [doc] apacheds v2.0 docs

[Emmanuel Lecharny <el...@gmail.com>]

Hi Ross,

comments inline...

On 2/7/12 11:53 PM, Ross West wrote:
> Okay, I'm about half way through doing up a set of docs based upon
> v2.0.0-M3 (I'll update to -M5 shortly), and just wanted to throw a
> couple of things "out there" for comments before I'm way too far to fix
> things.  This has morphed from the simpler docs I was thinking about
> earlier to a much larger thing.

>
> - Off the top: I've combined the two user guides (basic + advanced) into
> a single "admin" guide (lots of cut'n'paste done).  My focus is solidly
> on the system administration side of running a v2.0+ server as stable as
> possible and knowing what knobs to tweak in the configs.

We have created two separated guides because we realized that :
- not many users know about LDAP. Most of them are requested to "manage 
the damn LDAP server" because nobody else wants to do it
- most of the time, you just need to tweak a few things, not very complexe
- when it comes to get dirty, and nasty, then you need a very deep set 
od documentation about the server

This is why we started with a basic user guide (containing really the 
information that 90% of the users will need) and a advanced guys for 
thos crazy enough to have fun with LDAP :)

More seriously, it's difficult to merge both of them without going deep 
into the details from chapter one, and scare the beginners...

>
> - confluence layout: Currently I'm just keeping the current book.txt
> layout that's being used in the svn checkout I've got. I see in
> jira:DIRSERVER-1678 that there's thought in going to a chapter style
> layout for filenames.  Did this go any further, or is it "writer's
> choice" for the time being?

We have tried to list some chapters covering the different aspects of 
the server, but this is barely more than a writer choice. We can change 
that.

For instance, as every chapter has a incremental number, it's hard to 
add a new chapter in the middle : you have to change all the following 
chapter's numbers.

So if you have something better in mind, that would be worth discussing it.
>
> - Is the Directory Studio app considered the best/true way of
> configuring ApacheDS, or should I basically ignore it's built in
> configuration system and go with generic ldap instructions?

The biggest advantage of using Studio is that it's a GUI, so it's easier 
to explain in a document. Now, it would also be a good thing to explain 
the layouts and how to configure the server using LDAP.

>
> - NTP, HTTP, DNS servers: Are these actually part of the system, or
> really just proof of concept type services that aren't really used in
> day to day ops (Ie: Do I attempt to document them or tell people to just
> keep them disabled)
They are proof of concept. You can ignore them atm.
>
> - Tanuki Java Service Wrapper - I'm assuming this is the community
> edition that gets installed?  [I'm just going over logging options]

Yes. This is the only one which has a ASL 2.0 compatible licence. We 
haven't upgraded to anything above 3.2.3.
>
>
>
> I think that's it for the moment, but I'm sure I'll have more later.

You will always be welcomed !


-- 
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com

Re: [doc] apacheds v2.0 docs

[Ross West <ro...@crsnetworks.ca>]

Okay, I'm about half way through doing up a set of docs based upon
v2.0.0-M3 (I'll update to -M5 shortly), and just wanted to throw a
couple of things "out there" for comments before I'm way too far to fix
things.  This has morphed from the simpler docs I was thinking about
earlier to a much larger thing.

- Off the top: I've combined the two user guides (basic + advanced) into
a single "admin" guide (lots of cut'n'paste done).  My focus is solidly
on the system administration side of running a v2.0+ server as stable as
possible and knowing what knobs to tweak in the configs.

- confluence layout: Currently I'm just keeping the current book.txt
layout that's being used in the svn checkout I've got. I see in
jira:DIRSERVER-1678 that there's thought in going to a chapter style
layout for filenames.  Did this go any further, or is it "writer's
choice" for the time being?

- Is the Directory Studio app considered the best/true way of
configuring ApacheDS, or should I basically ignore it's built in
configuration system and go with generic ldap instructions?

- NTP, HTTP, DNS servers: Are these actually part of the system, or
really just proof of concept type services that aren't really used in
day to day ops (Ie: Do I attempt to document them or tell people to just
keep them disabled)

- Tanuki Java Service Wrapper - I'm assuming this is the community
edition that gets installed?  [I'm just going over logging options]



I think that's it for the moment, but I'm sure I'll have more later.

Cheers,
  Ross.

Re: [doc] apacheds v2.0 docs

[Alex Karasulu <ak...@apache.org>]

On Fri, Feb 3, 2012 at 5:26 PM, Emmanuel Lecharny <el...@gmail.com>wrote:

> On 2/3/12 4:10 PM, Ross West wrote:
>
>> Hey there,
>>
>> I've just got started with ADS and thought that it would be easier to
>> start with v2.0 rather than v1.5 for a new setup. (Yes I know that v2.0
>> is true beta - I'm not in production, and I'm a sucker for punishment I
>> guess)
>>
>> Anyways, I'm in the process of doing up my own internal sysadmin
>> oriented docs here for v2.0 and with the lack of any public
>> documentation for it I can probably do mine up in a generic format for
>> the ADS website if there's any interest.
>>
> You bet we are interested !
>
>
Damn right!

-- 
Best Regards,
-- Alex

Re: [doc] apacheds v2.0 docs

[Ross West <ro...@crsnetworks.ca>]

> You bet we are interested !
> 
> Actually, we have a first drop of docs which is not yet published 
> (mainly a refactoring of the 1.5.7 documentation).

Yeah, I found that and it was a help for my initial start, but so much
has changed between v1.5 and v2.0 (especially in regards to the
server.xml being gone) it's very hard to follow - hence my redo of it.
There's also a bunch of little gotchas that aren't well documented when
it comes to the client side interaction (encryption levels, etc).

> as we know have the tooling to convert a confluence format to pdf and 
> html, we don't anymore use the XML format. AFAICT, all the xml pages 
> have been converted to confluence.

Okay, so confluence is your doc/markup language, I can work with that.
I'll get started using it and see what I can do for you guys.


Cheers,
  Ross.

Re: [doc] apacheds v2.0 docs

[Emmanuel Lecharny <el...@gmail.com>]

On 2/3/12 4:10 PM, Ross West wrote:
> Hey there,
>
> I've just got started with ADS and thought that it would be easier to
> start with v2.0 rather than v1.5 for a new setup. (Yes I know that v2.0
> is true beta - I'm not in production, and I'm a sucker for punishment I
> guess)
>
> Anyways, I'm in the process of doing up my own internal sysadmin
> oriented docs here for v2.0 and with the lack of any public
> documentation for it I can probably do mine up in a generic format for
> the ADS website if there's any interest.
You bet we are interested !

Actually, we have a first drop of docs which is not yet published 
(mainly a refactoring of the 1.5.7 documentation).

It can be found here :

http://svn.apache.org/repos/asf/directory/documentation/apacheds-manuals/trunk/

Note that we have two different format for the documentation :
- a xml format (docbook)
- a confluence format

as we know have the tooling to convert a confluence format to pdf and 
html, we don't anymore use the XML format. AFAICT, all the xml pages 
have been converted to confluence.

You can read the README.TXT to get a clue about how to generate the pdf 
and html pages from those pages.

If you are interested, you can provide patches to the existing 
documentation...

Thanks a lot !


-- 
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com