$Id: INSTALL.txt,v 1.1 2004/01/12 22:14:04 comsubvie Exp $ Feedback -------- Your feedback is welcome to help make these installation instructions more useful, understandable, and complete. If you have any suggestions, criticisms, questions, or other comments, please send them to tavi-devel@lists.sourceforge.net. Thanks! WikkiTikkiTavi - Installation ----------------------------- (See below, under "WikkiTikkiTavi - Upgrading", if you are upgrading an existing 'Tavi installation.) See http://tavi.sourceforge.net/ for more detailed instructions dealing with virtual hosts, 'Tavi templates, URL rewriting, etc. 1. Choose a location in which to install 'Tavi. You do not need to install 'Tavi under your webspace; in fact, it is recommended that you do not do so. While there are no known security exploits in 'Tavi 0.21, it is best for security purposes to leave as few scripts exposed to the web as possible. Additionally, if you install 'Tavi in a central location, you can use it once for multiple wikis on your web server. This makes administration of virtual hosts or wiki farms much simpler. Upgrading to a later version of 'Tavi also is simplified, as you can upgrade multiple wikis in one step. For the sake of example, the following assumes that you have chosen to install 'Tavi in the following directory: /usr/local/lib/tavi/ Alternatively, you can install 'Tavi directly in your webspace and use it without complication; there is no reason that 'Tavi *must* be installed in a central location, although it is recommended. 2. Download the 'Tavi archive into the installation directory. You can find it at http://prdownloads.sourceforge.net/tavi/ 3. Unpack the archive in the installation directory. It should create a subdirectory named 'tavi-0.21'. 4. [Not necessary, but recommended.] Create a symbolic link in the installation directory that points to the archive subdirectory. For example, create a symbolic link in /usr/local/lib/tavi/ called 'tavi-current', that points to '/usr/local/lib/tavi/tavi-0.21'. This allows your wikis to point to 'tavi-current', allowing you to automatically upgrade them to a newer release by simply pointing 'tavi-current' to the new release's location. 5. Run install/create-db.pl to create the database tables for your wiki: Its first parameter should be the name of the (already created) MySQL database where the tables will be created. If you have not yet created the database, you should do so before running the script. Its second and third parameters are the user name and password to use to access the database. Optionally, you can include a fourth parameter to specify a prefix to be prepended to the table names. If you have access to only one MySQL database, you can use this feature to install multiple wikis in the same database. You may also include a fifth parameter to specify the hostname or IP address of the database server, if it is not the local host. Examples: perl ./create-db.pl wiki joe passwd perl ./create-db.pl project sally pass wiki_ database.example.com perl ./create-db.pl common jim key "" mysql.example.com 6. In the install/ directory, run the "configure.pl" script to generate a configuration file for your wiki. It takes one parameter, the location of the configuration file. For example: perl ./configure.pl /home/u/user12/tavi/config.php perl ./configure.pl ../config.php You will be prompted for such things as the URL to the wiki script, the name of your wiki, database information, etc. As with the 'Tavi source, it is recommended that you keep your configuration file in a location that cannot be accessed from the web. You may wish to double-check the 'config.php' file that was created by the configuration script, to make sure that the settings are correct. 7. If you installed 'Tavi in your webspace, then skip this step, since index.php is already accessible from the web. A. Now you have to create an entry point to your wiki. Choose a directory in your webspace to be the base point for your wiki. For sake of example, we will use /home/joe/public_html/mywiki/. B. Create a subdirectory named 'admin/' in this directory. E.g., /home/joe/public_html/mywiki/admin. C. In the base directory, create a symbolic link to the index.php in the 'Tavi installation. For example, create /home/joe/public_html/mywiki/index.php that is a link to /usr/local/lib/tavi/tavi-current/index.php. D. In the admin/ subdirectory, create a symbolic link to the index.php in the admin subdirectory in the 'Tavi installation. For example, create: /home/joe/public_html/mywiki/admin/index.php that is a link to /usr/local/lib/tavi/tavi-current/admin/index.php. 8. Configure your script so that it can access the 'Tavi scripts and so that it can access your configuration file. If you have installed 'Tavi in your webspace, and you have placed the config.php file in the root of that location, then you can skip this step. Otherwise, continue: A. Locate the directories for your 'Tavi installation and for your config.php file. For example, they might be: /usr/local/lib/tavi/tavi-current /home/joe/tavi/mywiki B. If you are running PHP as mod_php under Apache, add the directories to the .htaccess file in the directory where the wiki resides. Separate them with colons: php_value include_path "/home/joe/tavi/mywiki:/usr/local/lib/tavi/tavi-current" C. If, instead, you are running PHP as a CGI program, then you will have to similarly change the include_path in your php.ini file to point to the given directories. (To prevent this from affecting your other PHP scripts, see http://tavi.sourceforge.net/CGI+Wrapping.) 9. [Optional, but recommended.] Turn off register_globals for 'Tavi. While there are no known security exploits in 'Tavi 0.21, this is generally a good idea to make your scripts less liable to undiscovered exploits. A. If you are running PHP as mod_php under Apache, add the following line to the .htaccess file in the directory where the wiki resides: php_flag register_globals off B. If, instead, you are running PHP as a CGI program, then you will have to similarly change the register_globals setting in your php.ini file. (To prevent this from affecting your other PHP scripts, see http://tavi.sourceforge.net/CGI+Wrapping.) 10. Visit your wiki and start creating pages! Apart from your wiki's home page, you should also create RecentChanges, containing (at minimum) a wildcard subscription list like so: [[! *]] You should also create some InterWiki entries. See http://tavi.sourceforge.net/InterWiki for help. 11. Advertise your wiki. Feel free to put a link to your wiki on http://tavi.sourceforge.net/TaviSites. 12. Read more about using and administering 'Tavi at http://tavi.sourceforge.net/TaviDocumentation. Advanced ======== * Customizing Your Wiki See http://tavi.sourceforge.net/CustomizingTavi for help on how you can tweak your wiki's behavior and appearance to your heart's content. * Virtual Hosts and Wiki Farms If you are running a virtual host server, or a wiki farm, you might wish to install 'Tavi a single time, rather than once for each wiki. If you installed 'Tavi as suggested above, this will be easy to achieve. See http://tavi.sourceforge.net/VirtualHosts for help. * Using Templates 'Tavi allows you to configure templates to customize your wiki's appearance. To make things easier on yourself if you upgrade 'Tavi in the future, you should *copy* rather than directly edit the default template. See http://tavi.sourceforge.net/CustomizingTemplates for help. * URL Rewriting With a few simple tricks you can set up your wiki so the pages appear like http://example.com/wiki/PageName. See http://tavi.sourceforge.net/URL+Rewriting for help. * Sister Wikis 'Tavi allows you to set up *sister wikis*. 'Tavi will recognize pages on sister wikis that have the same names as pages on your wiki. It will display links to the sister wiki pages on your wiki's pages. See http://tavi.sourceforge.net/SisterWiki for help. * Automated Upgrades 'Tavi's configuration has been re-organized so that upgrades in the future should be nearly effortless. See http://tavi.sourceforge.net/AutomatedUpgrades for help. WikkiTikkiTavi - Upgrading ========================== 'Tavi version 0.21 has rearranged its configuration somewhat, to allow for more effortless upgrades in the future. Unfortunately, this means that upgrading from version 0.20 to version 0.21 will not quite be effortless. Fortunately, no database changes need to be made; the only changes are in configuration. config.php is no longer in the distribution. Instead, you create config.php when you install 'Tavi, and it is never overwritten, even if you later upgrade to a newer release. The simplest way to upgrade to 'Tavi 0.21 is to scrap your existing config.php and use install/configure.pl to generate a new one for you, as described above in "WikkiTikkiTavi - Installation". It will prompt you for all the relevant configuration values. If you have been using a customized template, we recommend that you place it in a directory other than template/. This will prevent it from being overwritten when you upgrade now (or later). (However, you may wish to consider using the new template as a starting point for your custom template, as it has been tweaked to be compliant with the XHTML-Strict standard.)