%META:TOPICINFO{author="TWikiContributor" date="1111929255" format="1.0" version="63"}%
%TOC%
%STARTINCLUDE%
---+!! TWiki Installation Guide

Please review the AdminSkillsAssumptions before you install TWiki.

TWiki should be fine with any web server and OS that meet the [[TWikiSystemRequirements][system requirements]]. See the cookbooks list at TWiki:Codev.CategoryCookbook for guidance for your particular platform.

If you need help, ask a question in the TWiki:Support web or on TWiki:Codev.TWikiIRC (irc.freenode.net, channel #twiki)

#StandardInstallation
---+ Basic Installation

	1 *Download* the TWiki distribution from http://TWiki.org/download.html.
	1 *Make a directory* for the installation and *unpack the distribution* in it.
	1 *Make sure* the user that runs CGI scripts on your system can read and write all files in the distribution.
	  %BR% Detailed instructions on file permissions are beyond the scope of this guide, but in general:
		* During installation and configuration, the CGI user needs to be able to read and write _everything_ in the distribution,
		* Once installation and configuration is complete, the CGI user needs write access to everything under the =data= and =pub= directories and to =lib/LocalSite.cfg=. _Everything else_ should be read-only.
		* Everybody else should be denied access to everything, always.
	1 *Make sure* Perl 5 and the Perl CGI library are installed on your system. 
	  %BR% The default location of Perl is =/usr/bin/perl=. *If it's somewhere else*, change the path to Perl in the first line of each script in the =twiki/bin= directory.
	  %BR% %H% Some systems require a special extension on perl scripts (e.g. =.cgi= or =.pl=). If necessary, rename all files in =twiki/bin=  (i.e. rename =view= to =view.pl= etc). If you do this, make sure you set the =ScriptSuffix= option in =configure= (Step 6).
	1 *Create the file* =/twiki/bin/LocalLib.cfg=.
	  %BR% There is a template for this file in =/twiki/bin/LocalLib.cfg.txt=.
	  %BR% The file must contain a setting for =$twikiLibPath=, which must point to the absolute file path of your =twiki/lib= e.g. =/home/httpd/twiki/lib=.
	  %BR% %H% If you need to install additional CPAN modules, but can't update the main Perl installation files on the server, you can set =$CPANBASE= to point to your personal CPAN install. Don't forget that the webserver user has to be able to read those files as well.
	1 *Configure the webserver* so you can execute the =bin/configure= script from your browser.
		* Explicit instructions for doing this are beyond the scope of this document, though there is a lot of advice on TWiki.org covering different configurations of webserver. To help you out, there's an example Apache =httpd.conf= file in =twiki_httpd_conf.txt= at the root of the package. This file also contains advice on securing your installation. There's also a script called =tools/rewriteshebang.pl= to help you in fixing up the shebang lines in your CGI scripts.
	1 Run the =configure= script from your browser, and resolve any errors or warnings it tells you about.
You now have a basic, unauthenticated installation running. At this point you can just point your Web browser at =http://yourdomain.com/twiki/bin/view= and start TWiki-ing away!

#AuthenticationOfUsers
---+ Next Steps
Once you have your TWiki running, you can move on to customise it for your users.
	* *Review TWikiPreferences settings* - read through it and set any additional settings you think you might need (you can click the 'Edit' button near the top to edit the settings in place)
		* %I% It is recommended to *copy* any settings or variables that you want to customize from [[%TWIKIWEB%.TWikiPreferences]] and *paste* them into [[%MAINWEB%.TWikiPreferences]]. This will protect your local customizations from being overwritten in later upgrades. See notes at top of [[%TWIKIWEB%.TWikiPreferences]] for more information.
	* *Customize user home pages* - read and change NewUserTemplate.
	* *Enable authentication* - read TWikiUserAuthentication.
	* *Enable e-mail notification* - read TWikiSiteTools#WebNotify to get WebChangesAlerts.
	* *Automate update of site statistics* - read TWikiSiteTools#WebStatistics
	* *Automate removal of expired sessions and lease files* - read TWikiScripts#tick_twiki_pl.
	* *Install Plugins* if needed - TWiki:Plugins is an extensive library of Plugins for TWiki, that enhance functionality in a huge number of ways. A few Plugins are pre-installed in the TWiki distribution. Installation instructions for the other Plugins can be found in the Plugin topics on [[TWiki:Plugins][TWiki.org]].

---+ Troubleshooting
The first step is to re-run the =configure= script and make sure you have resolved all errors, and are happy that you understand any warnings.

Failing that, please check the topics listed below, they include some important tips for HP-UX, Solaris, OS/390, and many other platforms.
	* For Unix or Linux, check TWiki:Codev/TWikiOnUnix and TWiki:Codev/TWikiOnLinux.
	* For Windows, check the TWiki:Codev/WindowsInstallCookbook. 
	* For <nop>MacOS X, check TWiki:Codev/TWikiOnMacOSX. 
	* To install TWiki on <nop>SourceForge, for use on a software development project, read TWiki:Codev/TWikiOnSourceForge
	* For other platforms, see TWiki:Codev/TWikiOn, and search the TWiki:Codev and TWiki:Support webs for other installation notes.

If you need help, ask a question in the TWiki:Support web or on TWiki:Codev.TWikiIRC (irc.freenode.net, channel #twiki)

%STOPINCLUDE%

__Related Topics:__ AdminDocumentationCategory
