Item3947: Better documentation on how to install CPAN libs (including a reference in the install doc)

Feedback by TWiki:Main/EricHHESCUDIER on 24 Apr 2007 at TWiki:TWiki/TWikiInstallationGuide:

It is very very difficult for someone like me to install twiki. I am almost ready to go back to mediawiki. I know how to setup apache whith PHP, Mysql using a variety of distribs, but all this perl stuff is semi illegible for me. And the docs are impossible to follow since they assume much that is not known to me ( or to anybody without a solid perl culture ). I think you should focus on writing a good step by step installation guide.

• You should at the very least point us to a good basic, step by step, apache+perl+CPAN setup guide or better write one specificly for a twiki setup.
• twiki needs several CPAN modules, but you never say how to install them and for a perl newbie like me CPAN is not very friendly
• point 4 of the basic installation guide "If you do this, make sure you set the ScriptSuffix option in configure (Step 6)" is quite confusing because when you get to step 6 there is no mention of this option, and if it is something that has to be set in the code, I can't see where to set it because there is not a commented line in the source saying "set ScriptSuffix option

here like this"

-- TWiki:Main/PeterThoeny - 24 Apr 2007

We have been waiting for someone to pick up the ball on rewriting the installation guide for at least two years. Confirmed.

CC

I am a bit puzzled by the remark by CC.

I completely rewrote the TWiki:TWiki/TWikiInstallationGuide just a few months ago. So I do not understand the "two year" statement.

In addition I have actually written a very detailed guide for RedHat type distros as a supplementary document. And there have been other contributions recently for other distros.

The problem is that when you include all the different environments that TWiki works in then there is NOT ONE way to install everything.

Examples. On a shared host where you are not root installing CPAN libs has to be done one way. And on a RedHat type distro where you have root access the best way to install packages is by using rpms of the CPAN libs which ensures a much better maintainability when you later have RedHat yum updating itself which all happens through the use of rpms.

Running yum and CPAN does not work behind firewalls unless you make a special setup temporarily - in many companies authentication is required to get through the firewall.

The real problem is that TWiki is too difficult to install PERIOD and that it depends on too many non-standard CPAN modules, and that some developers still cannot understand that installing CPAN modules is DIFFICULT for most people. But that discussion we have taken before and will take again. Sven is doing the right step with respect to debian and we need more of this for other environments.

Surely the installation guide can always get better and we will continuously improve it and in addition add more specialized supplimental documents - which I still think are too hidden on twiki.org.

And I will take the task to see how we can get Eric's inputs incorporated. I think the installation guide probably confuse more than it helps with respect to CPAN libs. It deserves a full topic on its own - and a less geeky one that we have right now which focus only on very manual ways to install libs.

But please - developers - read the real message in Eric's description: "twiki needs several CPAN modules, but you never say how to install them and for a perl newbie like me CPAN is not very friendly"

-- TWiki:Main.KennethLavrsen - 25 Apr 2007

I have taken the following action.

• Given the already existing Supplementary document TWiki:TWiki.HowToInstallCpanModules a prominent position on TWiki:TWiki.SupplementalDocument. We cannot put everything there but CPAN lib installation is high on the commonly asked questions we get so this one should be there in the Installation section.
• Given the TWiki:TWiki.HowToInstallCpanModules 3 links in the TWikiInstallationGuide topic which is compiled to INSTALL.html when you build TWiki.
• Given TWiki:TWiki.HowToInstallCpanModules a major extension so it also covers installing from modules like RPMs and debs and Gentoo. I hope I got things right for Debian and Gentoo.

I am not taking any actions on the Script Suffux problem. It is very clearly stated in the TWikiInstallationGuide and the reporter has clearly not looked very carefully in configure. I actually think he looked at the sources of configure which makes no sense at all. I think it is clear enough already in the installation guide that you run configure. It says "Run the configure script from your browser".

I think I have spent the 4 hours that this bug item deserves.

Waiting for release.

-- TWiki:Main.KennethLavrsen - 27 Apr 2007

Very cool, nice work Kenneth!

-- TWiki:Main.PeterThoeny - 27 Apr 2007

You're right Kenneth I looked inside the sources of configure because I was unable to run configure sor I infered ( wrongly it seems ) that maybe the suffix was the reason, and it had to be set up in the code... I hope I'll have some free time next week to begin the setup process from scratch on a fresh apache install, and I hope the added links will save me from failure...

-- TWiki:Main.EricHHESCUDIER - 04 May 2007

Cleaned "WaitingFor" field.

-- TWiki:Main.GilmarSantosJr - 10 Aug 2008