|
>
> | TWiki Reference Manual (Tue, 04 Jul 2006 build 10807) |
| |
TWiki Reference Manual (Tue, 04 Jul 2006 build 10807) |
>
> | document.ondblclick=dblclick;
-->
|
| | |
|
<
< | This page contains all documentation topics as one long, complete reference sheet.
|
>
> | This page contains all documentation topics as one long, complete reference sheet.
|
| | Doubleclick anywhere to return to the top of the page. |
| | TWiki Installation Guide
Installation instructions for the TWiki 4.0 production release.
If you are upgrading from a previous version of TWiki, you probably want to read TWikiUpgradeGuide instead.
TWiki should be fine with any web server and OS that meet the system requirements. The following installation instructions are written for experienced system administrators; please review the AdminSkillsAssumptions before you install TWiki. If you need help, ask a question in the TWiki:Support web or on TWiki:Codev.TWikiIRC (irc.freenode.net, channel #twiki)
 Hint: TWiki:TWiki.InstallingTWiki on TWiki.org has supplemental documentation that help you install TWiki on different platforms, environments and web hosting sites.
Basic Installation
- Download the TWiki distribution from http://TWiki.org/download.html.
- Make a directory for the installation and unpack the distribution in it.
- Make sure the user that runs CGI scripts on your system can read and write all files in the distribution.
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.
- Make sure Perl 5 and the Perl CGI library are installed on your system.
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.
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).
- Create the file
/twiki/bin/LocalLib.cfg.
There is a template for this file in /twiki/bin/LocalLib.cfg.txt.
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.
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.
- 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.
- 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!
Next Steps
Once you have your TWiki running, you can move on to customise it for your users.
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.
- TWiki:TWiki.InstallingTWiki on TWiki.org has supplemental documentation that help you install TWiki on different platforms, environments and web hosting sites.
- If you need help, ask a question in the TWiki:Support web or on TWiki:Codev.TWikiIRC (irc.freenode.net, channel #twiki)
|
|
>
> |
Warning: Can't find topic TWiki.WindowsInstallCookbook
|
| | TWiki Upgrade Guide
Upgrade from the previous TWiki 01-Sep-2004 Prodcution Release to TWiki-4.0.0
Overview
TWiki-4.0.0 is a major new release. You can chose between an automated upgrade using a script or a manual update.
Upgrade Requirements
- Please review the AdminSkillsAssumptions before you upgrade TWiki
- Review TWiki:TWiki.TWikiUpgradeTo04x00x00 for latest information and experience notes.
- To upgrade from a release prior to TWiki Release 01-Sep-2004, start with TWiki:TWiki.UpgradingTWiki on TWiki.org
- To upgrade from a standard TWiki Release 01-Sep-2004 to the latest TWiki-4.0.0 Production Release, follow the instructions below
- Once the upgrade has been applied, an existing earlier installation will still be able to read all the topics, but should not be used to write. Make sure you take a backup!
- Not all Plugins written for TWiki Release 01-Sep-2004 are fully supported with Dakar. Make sure the Plugins you use can be upgraded as well!
Major Changes Compared to TWiki Release 01-Sep-2004
See TWikiReleaseNotes04x00.
Automated Upgrade Procedure
If you would prefer to do things manually, or if you made custom modifications to distributed files (except topics), then skip to the manual upgrade procedure below.
The upgrade script is called "UpgradeTwiki", and is found in the root of the distribution. It can be run by any user, though you will need to make sure you correct the permissions so that the webserver user can write all files in the new installation when you have finished. The upgrade script does not write to your existing installation.
The upgrade script will upgrade the TWiki core only. Plugins will need to be upgraded separately.
Note: To upgrade from a Beta, do not use UpgradeTWiki. Instead follow the steps outlined in Upgrading a Beta, below.
It will:
- Create a new TWiki installation, placing the files from the distribution there as appropriate
- Where possible, merge the changes you've made in your existing topics and attachments into the new twiki
- Where not possible, it will tell you, and you can inspect those differences manually
- Create new configuration files for the new TWiki based on your existing configuation information
- Set the permissions in the new TWiki so that it should work straight away
- Attempt to setup authentication for your new TWiki, if you are using .htaccess in the old one
- Tell you what else you need to do
To perform the upgrade, you need to:
- Check first if there is a newer
UpgradeTwiki script available, see TWiki:Codev.UpgradeTWiki
- Create a new directory for your new installation: Let's call this
distro/
- Put the distribution zip file in
distro/
- Unzip it
- Choose a directory for the new installation. I will call this
new_twiki. This directory must not already exist.
- Change directory to
distro/ and run:
./UpgradeTwiki <full path to existing_twiki's setlib.cfg> <full path to new_twiki>
- confirm your system settings by pointing your browser to the
configure script
Assuming all goes well, UpgradeTwiki will give you the final instructions.
Visit TWiki:Codev.KnownIssuesOfTWiki04x00x00 and fix known issues that apply to you.
There are a few points worth noting:
-
UpgradeTwiki may not be able to merge all the changes you made in your existing TWiki into the new installation, but it will tell you which ones it couldn't deal with
-
UpgradeTwiki creates the new installation in a new directory tree. It makes a complete copy of all your existing data, so:
- Clearly you need to point it to a location where there is enough space
- If you have symlinks under your
data/ directory in your existing installation, these are reproduced as actual directories in the new structure. It is up to you to pull these sub-directories out again and re-symlink as needed
-
UpgradeTwiki doesn't deal with custom templates or Plugins, you will have to reinstall these in the new installation.
- If you are using the Htpasswd login manager, then note that email addresses for users have moved out of user topics and into the password database. There is a script that performs this extra upgrade step for you - see
tools/upgrade_emails.pl.
Manual Upgrade Procedure
The following steps are a rough guide to upgrading only. It is impossible to give detailed instructions, as what you have to do may depend on whether you can configure the webserver or not, and how much you have changed distributed files in your current TWiki release.
- Follow the installation instructions, and install the new release in a new directory.
- Copy your local webs over to the data and pub directories of the new install
- You could also use softlinks to link the web directories in data and pub to the old installation area
- Unlock the rcs files in data and pub directories from the old installation using the following shell commands:
-
find data -name '*,v' -exec rcs -r -u -M '{}' \;
-
find pub -name '*,v' -exec rcs -r -u -M '{}' \;
- Examine your old TWiki.cfg, and for each local setting, set the corresponding value in the
configure interface for the new install.
- If you can't use
configure, then copy the new TWiki.cfg to LocalSite.cfg, and edit LocalSite.cfg. Remove all the settings that you didn't change in your previous install, and change the remaining settings to the values from your old TWiki.cfg.
- Transfer any customized and local settings from TWiki.TWikiPreferences to the topic pointed at by {LocalSitePreferences} (Main.TWikiPreferences). This avoids having to write over files in the distribution.
- If you changed any of the topics in the original TWiki distribution, you will have to transfer your changes to the new install manually. There is no simple way to do this, though the following procedure may help:
- Install a copy of the original TWiki release you were using in a temporary directory
- Use 'diff' to find changed files, and transfer the changes into the new Dakar install.
- Install updated plugins into your new area.
- Point your webserver at the new install.
- Visit TWiki:Codev.KnownIssuesOfTWiki04x00x00 and fix known issues that apply to you.
- If you are using the Htpasswd login manager, then note that email addresses for users have moved out of user topics and into the password database. There is a script that performs this extra upgrade step for you - see
tools/upgrade_emails.pl.
You are highly recommended not to change any distributed files if you can avoid it, to simplify future upgrades!
Upgrading a Beta
If you followed the recommendations and avoided modifying any distributed files, then this is quite straightforward:
- Follow the installation instructions, and install the new release in a new directory.
- Copy your local webs over to the data and pub directories of the new install
- Be careful to copy over the user topics and TWikiUsers?.txt in the Main web
- Copy over your
bin/LocalLib.cfg and lib/LocalSite.cfg files
- Copy over any local files you created (such as .htpasswd and .htaccess files)
- Point your webserver at the new install.
If you changed any of the distributed files, you will have to continue from Step 5 above.
Upgrading from Cairo to TWiki4 (additional advice)
Favicon
TWiki4's PatternSkin introduces the use of the favicon feature which most browsers use to show a small icon in front of the URL and for bookmarks.
In TWiki4 it is assumed that each web has a favicon.ico file attached to the WebPreferences topic. When you upgrade from Cairo to TWiki4 you do not have this file and you will get flooded with errors the error log of your web server. There are two solutions to this.
- Attach a favicon.ico file to WebPreferences in each web.
- Change the setting of the location of favicon.ico in TWikiPreferences so all webs use the favicon.ico from the TWiki web. This is the fastest and easiest solution.
To change the location of favicon.ico in TWikiPreferences to the TWiki web add this line to TWikiPreferences
* Set FAVICON = %PUBURLPATH%/%TWIKIWEB%/%WEBPREFSTOPIC%/favicon.ico
|
It is recommended to copy any settings or variables that you want to customize from 
Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.