• Do not register here on develop.twiki.org, login with your twiki.org account.
• Use View topic Item7848 for generic doc work for TWiki-6.1.1. Use View topic Item7851 for doc work on extensions that are not part of a release. More... Close
• Anything you create or change in standard webs (Main, TWiki, Sandbox etc) will be automatically reverted on every SVN update.
Does this site look broken?. Use the LitterTray web for test cases.

The TWikiInstallationGuide has been reduced to a very short description, assuming familiarity with Apache and CGI configuration.

The Cairo TWiki:TWiki.TWikiInstallationGuide has detailed installation instructions, tailored for people who are not so familiar with Apache and CGI configuration.

While I agree that a short installation guide is better for experienced admins, we cannot neglect the fact that many people who install TWiki are not familiar with system administration. We should make it easier not harder for those folks to install TWiki. The new configure script does a lot to make installation easier, but there are many things configure cannot address (file permissions, Apache configuration, non-root account setup, I18N, e-mail setup, etc)

Not sure what is better: Expand the existing installation guide, or create a new TWikiInstallationGuideForDummies.

-- PTh

Neither. My intent was to move platform-specific installation instructions into TWiki.org. That's why I started Codev:CategoryCookbook

This achieves a number of goals:

  1. Reduces the amount of content that has to be maintained in the release.
  2. Allows the install guides to be extended by the community as necessary.
  3. Reduces linkage between TWiki and Apache. Too many apache errors are seen as TWiki errors.
  4. Increases visibility of TWiki.org as an information resource.

I'm not at all sure I have the guides in the right places on twiki.org; that is something that needs more thought. But the release should be kept tight, and cookbooks and detailed install guides developed on twiki.org.


I agree with CC


Fair enough point. Are the detailed instructions carried over to the cookbook(s) in Codev?

Yes, in Codev. At the time I was soloing the docs and didn't want to overwrite what was already in TWki web on twiki.org.

Also the changes since Cairo?

I did look, but IIRC I didn't find anything applicable.

A consequence of this change is that the cookbooks need to be maintained at the same quality as the official docs, which is easier said than done.

Well, that's up to you as webmaster of TWiki.org. But IMHO it's an excellent opportunity to demonstrate the power of a wiki in the community maintainance of a current doc set; something which has been missing from TWiki to date.

Also, it needs to be made very clear in TWikiInstallationGuide where to look for detailed instructions.

I thought it was pretty clear; you may want to rework my text.

-- PTh

Actually the Dakar release is more difficult to install and configure in ONE area. There are now two ways to setup authentocation: Template and Apache. And it is quite difficult - even for a person who has installed earlier versions of TWiki - to figure out what exactly to put in httpd.conf or .htaccess to get the authentication right. There should be an example doc for each type.

Additionally we need a Dakar only set of special topics on TWiki.org for config files for mod_perl and SpeedyCGI using Apache2. What is on TWiki.org now is a mix of Apache 1 and Apache 2 and it is quite confusing.

I spent quite a long time getting LDAP authentication working but it is working now - so I can contribute with a topic on that part. The example files currently in the beta are good but the problem is that it is not clear if they are for template or Apache authentication and there seem to be a huge difference how you should set these up.


Since the documentation in the distribution is hard to keep up to date I propose that a DakarApacheConfigurationIndex is created which the distribution docs refers to.

Do we really need another doc? Can't we simply refactor existing docs? At worst, add CategoryInstallation?

And on this index there should be links to ...

  • Apache config - standard example for TWiki::Client::TemplateLogin
  • Apache config - standard example for TWiki::Client::ApacheLogin
  • Apache config - standard example for LDAP authentication and Sessions (special case of ApacheLogin where it is important that you do things right to avoid a major slowdown from a slow LDAP server)
  • Apache config - mod_perl - Dakar on Apache 2.0
  • Apache config - mod_perl - Dakar on Apache 1.3
  • Apache config - Speedy CGI - Dakar on Apache 2.0
  • Apache config - Speedy CGI - Dakar on Apache 1.3

I think people will be able to combine these for making for example Apache2 LDAP with mod_perl.

I propose writing very little in these topics and instead let the examples talk.

An excellent opportunity for you to contribute, thanks!

The advantage of this approach is that we get some of the old obsolete info eliminated, we get dynamic up to date docs on TWiki.org and the full completion of all these topics will not gate the release of Dakar. But there should be a short section in the distribution installation docs that refers to the config index on TWiki.org.

-- TWiki:Main.KennethLavrsen

My comments in red above.

I have one question: Is Codev really the right place? I threw the cookbooks into Codev because it had a number of existing cookbooks, and the category infrastructure foir linking them, but I would have thought this was the appropriate role for the TWiki.org version of the TWiki web, myself. A sort of extended documentation database, enhancing what is in the distribution.


The Codev web is fine. It could be also the TWiki web or the Support web. The important thing is to put content consistently just in one web, hence the Codev web since it already has some cookbooks.

Kenneth brings some good points, right on the mark. Don't forget that the average user installing TWiki has less experience than the assumed AdminSkillsAssumptions. The step-bystep instructions in Cairo's InstallationGuide have been written to account for that.

-- PTh

Aye - but my point is that the Codev web is huge - so big it is unsearchable, and if it was to be searched, would more than likely return results which are hopelessly out of date or - worse - downright dangerous.


On the other hand, the installation docs need to be index and linked properly, I do not see a big need to make them searchable. The installation docs are accessible with the TWiki:Codev.CategoryCookbook classification.

An admin wants to install TWiki on platform X with constraints Y an X (no root, non standard installation tree, ldap auth, ...). As such (s)he wants to find the right docs easily, e.g. in the distribution or a click away leading to a topic on twiki.org.

We really need step-by-step installation instructions for a typical installation on Linux with TWiki internal authentication. Tailored for a team lead who wants to install TWiki and who has never heard of httpd.conf and sudo (a not so uncommon persona of a new admin TWiki).

-- PTh

OK, it's up to you, but I think you may be storing up trouble here. Consider this scenario; someone is using a different component that no-one has tried yet - say an accelerator module; for example, they want to use FastCGI. They will want to use a search to collect all the combined wisdom from all prior installers of mod_perl and speedycgi. Try this for yourself - see how long it takes to mine any useful information from Codev. There will always be configurations that are not covered by the docs, and we have to make it as easy as possible to find "possibly relevant" docs. Of course you may be able to write a search page that constrains the search to a single category....


FWIW, TWiki:Support/ProblemsInstallingInWin98 has: "Have so far spent the day reading through all the cookbooks, instructions and comments, and installed as per the written advice. However, am having problems running it."

This is not an uncommon comment in the Support web. Hence the need to create a good index, to refactor the exitisting cookbooks and to create good step-by-step instructions.

-- PTh

no time, no time, must rush -- SD

Summary TWikiInstallationGuide written for admins only; needs support from twiki.org
ReportedBy PeterThoeny

SVN Range

AppliesTo Engine

Priority Normal
CurrentState Closed

Checkins 8580 8632 8637 8656 8664
Edit | Attach | Watch | Print version | History: r16 < r15 < r14 < r13 < r12 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r16 - 2006-02-01 - SvenDowideit
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 2008-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback