Line: 1 to 1 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Added: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
> > | TWiki Reference Manual (TWiki-6.1.0, Mon, 16 Jul 2018, build 30610) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Added: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
> > |
TWiki Reference Manual (TWiki-6.1.0, Mon, 16 Jul 2018, build 30610) | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
> > | document.ondblclick=dblclick; --> | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Changed: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
< < | 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.
On this page:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Line: 22 to 25 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
TWiki Installation Guide
The following is installation instructions for the TWiki-6.1 production release on an Apache web server on Linux. Visit TWiki:TWiki.InstallingTWiki If you are upgrading from a previous version of TWiki, you probably want to read TWikiUpgradeGuide instead.
Preparing to install TWikiBefore attempting to install TWiki, you are encouraged to review the AdminSkillsAssumptions. This guide assumes you have, at a minimum, basic knowledge of server administration on the system on which TWiki is to be installed. While it is possible to install TWiki with FTP access alone (for example, on a hosted site), it is tricky and may require additional support from your hosting service (for example, in setting file ownership and installing missing Perl CPAN libraries).
To help setup a correct Apache configuration, you are very much encouraged to use the automatic tool TWiki:TWiki.ApacheConfigGenerator
While this installation guide specifically describes installation on an Apache web server on Linux, TWiki should work fine with any web server and OS that meet the system requirements (see below). For additional notes on installing TWiki on other systems, see TWiki:TWiki.InstallingTWiki#OtherPlatforms If you are installing TWiki without Unix/Linux root (administrator) privileges (for example, on a hosted domain), see "Notes on Installing TWiki on Non-Root Account" below for supplemental instructions to the basic steps presented below. If you are upgrading from an earlier major version of TWiki such as Cairo (TWiki-3) or TWiki 4.x you will need the information found at TWikiUpgradeGuide.
One of the more difficult tasks is installation of additional CPAN libraries. See TWiki:TWiki.HowToInstallCpanModules
If you need help, ask a question in the TWiki:Support.WebHome Basic Installation
You now have a basic, unauthenticated installation running. At this point you can just point your web browser at Important Server Security SettingsBefore you continue any further there are some basic and very important security settings you have to make sure are set correctly.
The TWiki:TWiki.ApacheConfigGenerator
Next Steps
Once you have TWiki installed and running, you might consider the following optional steps for setting up and customizing your TWiki site. Many of the references below refer to topics within your TWiki installation. For example, Enable Authentication of Users
This step provides for site access control and user activity tracking on your TWiki site. This is particularly important for sites that are publicly accessible on the web. This guide describes only the most common of several possible authentication setups for TWiki and is suitable for public web sites. For information about other setups, see TWikiUserAuthentication, and TWiki:TWiki.TWikiUserAuthenticationSupplement These are the steps for enabling "Template Login" which asks for a username and password in a web page, and processes them using the Apache 'htpasswd' password manager. Users can log in and log out.
You are strongly encouraged to read TWikiUserAuthentication, TWiki:TWiki.TWikiUserAuthenticationSupplement
Note: The other
<FilesMatch "(attach|edit|manage|rename|save|upload|mail|logon|rest|.*auth).*"> require valid-user </FilesMatch>
The TWiki:TWiki.ApacheConfigGenerator Define the Administrator User(s)Administrators have read and write access to any topic in TWiki, regardless of TWiki access controls. When you install TWiki one of the first things you will want to do is define yourself as an administrator. You become an administrator simply by adding yourself to the TWikiAdminGroup. It is the WikiName and not the login name you add to the group. Editing the Main.TWikiAdminGroup topic requires that you are an administrator. So to add the first administrator you need to login using the internal TWiki admin user login and the password you defined in configure.
Set TWiki PreferencesPreferences for customizing many aspects of TWiki are set simply by editing a special topic with TWiki.
Enable Email NotificationEach TWiki web has an automatic email notification service that sends you an email with links to all of the topics modified since the last alert. To enable this service:
Enable Signed Email Notification
TWiki administrative e-mails are an attractive target for SPAM generators and phishing attacks. One good way to protect against this possibility to enable S/MIME signatures on all administrative e-mails. To do this, you need an an X.509 certificate and private key for the the To enable TWiki to sign administrative e-mails:
All out-going administrative e-mails will now be signed. Enable WebStatisticsYou can generate a listing manually, or on an automated schedule, of visits to individual pages on a per web basis. For information on setting up this feature, see the TWikiSiteTools topic. Automate removal of expired sessions and lease files
Per default TWiki cleans out expired session and lease files each time any topic is viewed. This however comes at a cost of lower performance. It is an advantage to define a negative value in Enable Localization
TWiki now supports displaying of national (non-ascii) characters and presentation of basic interface elements in different languages. To enable these features, see the Tailor New User Profile TopicWhen a new users registers on your TWiki, a user profile topic is created for them based on the NewUserTemplate topic (and its UserForm). It contains additional resources you can use to:
If you choose to tailor anything you are strongly advised to copy NewUserTemplate and UserForm to the Main web and tailor the Main web copies. TWiki will look for the NewUserTemplate in the Main web first and if it does not exist TWiki uses the default from the TWiki web. By creating a Main.NewUserTemplate and its Main.UserForm you will not loose your customization next time you upgrade TWiki. If you added or removed fields from the user form you may also want to tailor TWikiRegistration. Custom Start Web and HomepageBy default the TWiki home is Main.WebHome. Users tend to create content starting from the homepage. In most cases it is better to create a new web (workspace) for default content. That way the Main web can be kept clean and used just for users and TWiki groups. For example, you could create an "Intranet" web if TWiki is primarily used as an intranet, or a "KB" web if used as a knowledge base, etc. If you have a dedicated web as a starting point you obviously want users start at the home of that web. This can be configured in two places: 1. Redirect from site home to web home, and 2. Set the wiki logo URL. 1. Redirect from site home to web home
When a user enters the domain name of your TWiki she expects to see the homepage. You can do that either with an Apache rewrite rule or an HTML meta redirect to redirect from
<html> <head> <meta http-equiv="refresh" content="0;/do/view/Intranet/WebHome" /> </head> <body> Redirecting to <a href="/do/view/Intranet/WebHome">Intranet home</a>... </body> </html> 2. Set the wiki logo URL When a user clicks on the logo in the upper left or on the "Home" link in the top-bar she expects to navigate to the new homepage. You can do that by defining and customizing the following setting in Main.TWikiPreferences as described in the Set TWiki Preferences section:
* URL of the logo: * Set WIKILOGOURL = %SCRIPTURLPATH{view}%/Intranet/WebHome Customize the Site Logo
Create a logo with a transparent background and a maximum height of 55 pixels. Attach it to Main.TWikiPreferences, raw-edit that topic, and set the following bullet, assuming the name of the logo is
* Logo of this TWiki installation: * Set WIKILOGOIMG = %PUBURLPATH%/%USERSWEB%/TWikiPreferences/my-logo-100x50.png Customize the Look of Your TWiki!The real power of TWiki lies in its flexibility to be customized to meet your needs. You can easily change the look of the default skins (called TopMenuSkin and PatternSkin) by reading the PatternSkinCustomization.
At the official TWiki website you can find more resources. A good place to start exploring what's possible is TWiki:TWiki.TWikiAdminCookBook Customize Special PagesSome pages are meant to be customized after choice of authentication. If you do not use the internal TWiki password manager the topics that contains the features for changing and resetting passwords and changing the email address should be changed to a note describing how to perform these tasks in your organization. The topics are:
Install Plugins
TWiki:Plugins.WebHome
You activate installed plugin in the Plugins section of
Some plugins require that you define their settings in WYSIWYG And Raw EditFrom TWiki release 4.2.0 on the WYSIWYG editor has been replaced by a much better and more powerful editor and it was decided that WYSIWYG would be the default edit mode. An Edit Raw link is available for those that have a need or preference for this mode. However you may prefer to have the same user interface as in TWiki 4.1 where Edit was the raw text editor and you had a WYSIWYG button. This is possible by adding the following setting in the Main.TWikiPreferences, WebPreferences or user hompages:
Copyright, License and Classification StatementsAt the bottom of each topic you will find a default copyright message saying "Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors." The WEBCOPYRIGHT setting defines this. This is often not adequate.
You change the copy right statement globally by taking these steps.
Troubleshooting
The first step is to re-run the
If, by any chance, you forget the "admin" password, the same used in "configure" script, then please login to the server. Delete
Failing that, please check TWiki:TWiki.InstallingTWiki
It is also advisable to review TWiki:Codev/KnownIssuesOfTWiki06x01
If you need help, ask a question in the TWiki:Support
AppendicesTWiki System Requirements
Low client and server base requirements are core features that keep TWiki widely deployable, particularly across a range of browser platforms and versions. Many Plugins
Server Requirements
TWiki is written in Perl 5, uses a number of shell commands, and requires RCS (Revision Control System)
Required CPAN ModulesMost of the CPAN libraries listesd below are part of a standard Perl installation so you most likely have them all!
See TWiki:TWiki.HowToInstallCpanModules
The following Perl CPAN
Optional CPAN ModulesThe following Perl modules may be used by TWiki:
See TWiki:TWiki.HowToInstallCpanModules
Most of them will probably already be available in your installation. You can check version numbers with the perl -e 'use FileHandle; print $FileHandle::VERSION."\n"' <-- SMELL: perhaps put download link to TWiki:Plugins.CpanContrib Client RequirementsThe TWiki standard installation has relatively low browser requirements:
CSS and Javascript are used in most skins, although there is a low-fat skin (Classic skin) available that minimizes these requirements. Some skins will require more recent releases of browsers. The default skin (Pattern) is tested on IE 6, Safari, and Mozilla 5.0 based browsers (such as Firefox). <--
SMELL: what are some actual known good version number requirements for these browsers (eg, FireFox 1.0, or 1.0.3, or 1.0.7, or ???), etc.
-->
You can easily select a balance of browser capability versus look and feel. Try the installed skins at TWikiSkinBrowser and more at TWiki:Plugins.SkinPackage
Important note about TWiki Plugins
Notes on Installing TWiki on Non-Root AccountThe following supplemental notes to the Basic Installation instructions apply to installing TWiki on a system where you don't have Unix/Linux root (administrator) privileges, for example, on a hosted Web account or an intranet server administered by someone else. Referring to the Basic Installation steps presented above:
For additional information about installing TWiki on a hosted accounts, see TWiki:TWiki.InstallingTWiki#WebHostingSites Installing Manually Without ConfigureIt is highly recommended to use run configure from the browser when setting up TWiki. Configure does a lot of the hard work for you. But there may be instances where you do not want to use configure or where configure simply won't run because of a missing dependency. The manual steps you have to take are:
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Added: | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
> > |
Warning: Can't find topic TWiki.WindowsInstallCookbook
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
TWiki Upgrade GuideThis guide covers upgrading from a previous version of TWiki (such as TWiki-5.1) to TWiki-6.1
OverviewTWiki-6.1.0 is a minor release that brings many usability enhancements, strengthens TWiki as an application platform, and has enhanced security. Use this guide to upgrade a previous TWiki release to TWiki-6.1. Use the TWikiInstallationGuide if you do not have data to carry forward.
Upgrade Requirements
Major Changes Compared to Earlier TWiki ReleasesSee TWikiReleaseNotes04x00, TWikiReleaseNotes04x01, TWikiReleaseNotes04x02, TWikiReleaseNotes04x03, TWikiReleaseNotes05x00, TWikiReleaseNotes05x01, TWikiReleaseNotes06x00, TWikiReleaseNotes06x01 New Upgrade Option with BackupRestorePlugin
TWiki now has a new solution to backup, restore and upgrade TWiki sites. It can be used via browser and on the command line. The BackupRestorePlugin is pre-installed in TWiki-5.1 and later releases; it can be installed in older TWiki releases as low as TWiki-2001-09-01 (Athens Release) to easily create a backup that can be restored on a new TWiki release. This offers an easy upgrade path for TWiki. Check TWiki:Plugins.BackupRestorePlugin Upgrade ProcedureThe 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. The main steps are:
Installation
Install Extensions
Copy your old webs to new TWiki
Copy Users And Their Topics From Main Web
Apply Customizations To The Skin
Apply Preferences From Old Installation
Switch-OverOnce you have tested the new TWiki you can switch over to the new site. If the same domain and URL is used:
If the domain or URL changes:
Customization of Special PagesSome pages in the TWiki web are meant to be customized after choice of authentication. If you do not use the internal TWiki password manager the topics that contains the features for changing and resetting passwords and changing the email address should be changed to a note describing how to perform these tasks in your organization. If you have made such customizations remember to replace these topics in the TWiki web with the tailored versions from your old installation. The topics are:
Upgrading from Cairo to TWiki-4 (additional advice)
FaviconTWiki-4'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 TWiki-4 it is assumed that each web has a favicon.ico file attached to the WebPreferences topic. When you upgrade from Cairo to TWiki-4 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.
To change the location of favicon.ico in TWikiPreferences to the TWiki web add the following setting to Main.TWikiPreferences:
* Set FAVICON = %PUBURLPATH%/%SYSTEMWEB%/%WEBPREFSTOPIC%/favicon.ico
TWikiUsers topic in Main webYour old Main.TWikiUsers topic will work in the new TWiki but you will need to ensure that the following four users from the TWikiUsersTemplate topic are copied to the existing TWikiUsers topic in proper alphabetical order:
* TWikiContributor - 2005-01-01 * TWikiGuest - guest - 1999-02-10 * TWikiRegistrationAgent - 2005-01-01 * UnknownUser - 2005-01-01 What these users are:
You additionally need to ensure that TWikiUsers has the
Important Changes since TWiki-4.0.5
Supported Perl versionTWiki 4.0.5 worked on Perl version 5.6.X. Reports from users has shown that unfortunately TWiki 4.1.0 does not support Perl versions older then 5.8.0. It is the goal that TWiki should work on at least Perl version 5.6.X but none of the developers have had access to Perl installations older than 5.8.0. Since TWiki 4.1.0 has some urgent bugs the development team decided to release TWiki 4.1.1 without resolving the issue with Perl 5.6.X. We will however address this and try and resolve it for a planned 4.1.2 release. The TWiki community is very interested in contributions from users that have fixes for the code which will enable TWiki to run on older versions of Perl.
See the WhatVersionsOfPerlAreSupported
Template spec changed
Until TWiki 4.0.5 TWikiTemplates the text inside template definition blocks (anything between This caused a lot of problems for skin developers when you wanted a newline before or after the block text. From TWiki 4.1.0 this has changed so that white space is no longer stripped. Skins like PatternSkin and NatSkin have been updated so that they work with the new behavior. But if you use an older skin or have written your own you will most likely need to make some adjustments.
It is not difficult. The general rule is - if you get mysterious blank lines in your skin, the newline after the The spec change have the same impact on CommentPlugin templates where you may have to remove the first line break after the TMPL:DEF. See the CommentPluginTemplate for examples of how comment template definitions should look like in TWiki-4.1.X An example: A CommentPlugin template that adds a comment as appending a row to a table. Before the spec change this would work.
<verbatim> %TMPL:DEF{OUTPUT:tabletest}%%POS:BEFORE% |%URLPARAM{"comment"}%| -- %WIKIUSERNAME% - %DATE% | %TMPL:END% </verbatim> From Twiki 4.1.0 the old template definition will add an empty line before the new table row. To fix it simply remove the new line before the table.
<verbatim> %TMPL:DEF{OUTPUT:tabletest}%%POS:BEFORE%|%URLPARAM{"comment"}%| -- %WIKIUSERNAME% - %DATE% | %TMPL:END% </verbatim> The advantage of the spec change is that now you can add leading and trailing white space including new lines. This was not possible before.
Important Changes since TWiki-4.1.0
New location for session and other temporary filesAn upgrader upgrading to 4.1.1 should note the following important change
The directory for passthrough files and session files have been replaced by a common directory for temporary files used by TWiki. Previously the two configure settings
It is highly recommended no longer to use the tmp directory common to other web applications and the new default will work fine for most. You may want to delete all the old session files in /tmp after the upgrade to 4.1.1. They all start with cgisess_. It is additionally highly recommended to limit write access to the
Important Changes since TWiki-4.1.2
New WYSIWYG EditorTWiki now ships with a new WYSIWYG editor based on TinyMCE which replaces the Kupu based editor. TinyMCE is not a perfect Wysiwyg editor but it is magnitudes better than the previously used Kupu editor. The WysiwygPlugin that drives the engine behind both TinyMCE has additionally been heavily improved so that fewer TWiki Applications are negatively affected by editing in WYSIWYG mode. When TinyMCEPlugin is enabled, the Edit button by default becomes WYSIWYG editing mode. A new Raw Edit link has been added to enable application developers to edit the good old way. The WYSIWYG button has been removed.
NEWTOPICLINKSYMBOL removedThe NEWTOPICLINKSYMBOL preference which was deprecated in 4.1 has now been removed from the code. If you want to control the appearance of new links, you can use NEWLINKFORMAT.
UserForm and NewUserTemplate Customization
When a new user registers on TWiki his user topic is created based on the
The
From 4.2.0 the
TWikiUsers no longer distributed
The
From 4.2.0 this file is no longer included in the TWiki distribution. When you register the first time TWiki creates the
New
|