| TWiki dir: | What it is: | Where to copy: | Example: |
|---|---|---|---|
twiki/bin |
CGI bin | cgi-bin enabled dir | /home/smith/public_html/cgi-bin |
twiki/lib |
library files | same level like twiki/bin |
/home/smith/public_html/lib |
twiki/pub |
public files | htdoc enabled dir | /home/smith/public_html/pub |
twiki/data |
topic data | outside of htdoc tree (for security) | /home/smith/twiki/data |
twiki/templates |
web templates | outside of htdoc tree (for security) | /home/smith/twiki/templates |
Script### Step 2: Check the Server Directory Settings * Restart Apache by `/etc/rc.d/rc5.d/S85httpd restart` . * Test if the `twiki/bin` directory is cgi-enabled: * Enter the URL of that directory into your browser ( `http://your.domain.com/twiki/bin` ). It is not set correctly as cgi-bin in case you get something like `"Index of /twiki/bin"` . It is OK if you get a message like `"Forbidden. You don't have permission to access /twiki/bin/ on this server."` * Execute the `testenv` script from your browser ( `http://your.domain.com/twiki/bin/testenv` ). It shows a table with all CGI environment variables. It also tests the settings in yourAlias /twiki/bin/ "/home/httpd/twiki/bin/" > Alias /twiki/ "/home/httpd/twiki/" > <Directory "/home/httpd/twiki/bin"> > Options +ExecCGI > Set Handler cgi-script > Allow from all > </Directory> > <Directory "/home/httpd/twiki/pub"> > Options Follow Sym Links +Includes > Allow Override None > Allow from all > </Directory>
**twiki/lib/TWiki.cfg** configuration file, which you will set later on.
### Step 3: Enable Perl File Permissions
* Make sure Perl 5 and the Perl CGI library are installed on your system. Default location of Perl executable is `/usr/bin/perl`. In case Perl is installed in a different location, the first line of all Perl scripts in the **twiki/bin** directory must be changed (alternatively you can create a symbolic link from **/usr/bin/perl** ).
* **IMPORTANT:** On most ISP virtual domain accounts, Perl CGI scripts require a **.cgi** extension to run. Some systems need **.pl**, the regular Perl extension. Change all **twiki/bin** scripts appropriately if necssary.
* To be able to edit the Perl scripts and **.tmpl** files it is necessary to **chown** and **chgrp -R twiki** so all the files have the owner you want.
* The CGI scripts execute as **nobody**. Set the file permission of all Perl scripts in the **twiki/bin** directory as executable to **-rwxr-xr-x** (755).
* Set the permission of all files below `twiki/data` so that they are writable by user `nobody`. A simple way is to **chmod** them to **-rw-rw-r--** (664) and to **chown** them to **nobody**.
* Set the permission of the **twiki/data** directory and its subdirectories so that files in there are writable by user **nobody**. A simple way is to chmod them to **drwxrwxr-x** (775) and to **chown** them to **nobody**.
* Set the permission of the `twiki/pub` directory and all its subdirectories so that files in there are writable by user `nobody`. A simple way is to **chmod** them to **drwxrwxr-x** (775) and to **chown** them to **nobody**.
### Step 4: Set the Main Configuration File
* Edit the file **twiki/lib/TWiki.cfg** and set the variables to your needs.
* Set the file extension in the `$scriptSuffix` variable to **cgi** or **pl** if required.
* Make sure RCS is installed. Set `$rcsDir` in `twiki/lib/TWiki.cfg` to mach the location of your RCS binaries.
* Note in case the CGI scripts are **_not_** running as user `nobody`: The `*,v` RCS repository files delivered with the installation package are locked by user `nobody` . In case the user is different (e.g. `www-data` ), it is not possible to check in files, this has the effect that the topic version number does not increase when saving a topic. In this case you need to unlock all repository files and lock them as user `www-data` (check the rcs man pages), or simply delete all the repository files. A simple way to switch the locker of the RCS files is to use sed: **http://your.domain.com/twiki/bin/view** and start TWiki-ing away!
* Edit the [[TWikiPreferences]] topic in the TWiki:%TWIKIWEB% web to set the WIKIWEBMASTER email address, the WEBCOPYRIGHT message and other preferences.
* Edit the [[WebNotify]] topic in all webs and set the users you want to notify.
That's it for the standard virgin installation of TWiki. Read on to learn how to customize TWiki.
## Additional Server-Level Options
Complete a Standard Installation and your new TWiki site should be up and running. You can develop and manage most aspects of your site from the browser interface. Core set-up functions require direct access to the server file system, via Telnet or FTP. You can make server-level site changes during installation, or at any time afterwards.
### Creating a New Web
* To create a new web:
1. **Create** a new web data directory under `twiki/data` and check the file permission of the directory.
* Use a name consisting of characters `A..Z` , `a..z` but **_not_** in [[WikiNotation]].
2. **Copy** all files from the `twiki/data/_default` directory to the new data directory, preserving the original files' owner, group and permissions (on Unix, use `cp -p`). The data files must be writable by the owner the CGI scripts are running on (usually, `nobody`).
* **_Hint:_** You can set permissions of `.txt` and `.txt,v` files to `-rw-rw-rw-` (666) and then edit the topic using your browser; RCS will restore the file permissions correctly when saving the topic.
3. **Add** the new web to the web list (visible in the upper right corner of each topic) by editing the site-level preferences, %TWIKIWEB%.%WIKIPREFSTOPIC%:
* Add the new web to the %WIKIWEBLIST% variable.
4. **Update** the web settings by editing the WebPreferences topic of the new web:
* Customize the %WEBTOPICLIST% variable to contain the web-specific links you prefer.
* Set the WEBBGCOLOR variable to a color. The number represents the unique color for the web.
* Set Plugins, access privileges, custom variables, other web-level options (ex: %WEBCOPYRIGHT% can be set for an individual web).
5. **Add** the new web to the color-coded web directory table by editing the %TWIKIWEB%.TWikiWebsTable topic.
6. **Test** the new web: view pages, create a new page.
* That's it for a basic new web set-up. You can also further customize the web:
* Create customized templates in the new templates directory (otherwise, templates are inherited from `twiki/templates`).
* **_NOTE:_** For web-specific templates in a `templates` subdirectory, ex: `twiki/templates/someweb`.
* Create [[TWikiForms]] to add form-based page input that's stored separately from the main free-form topic text.
* **_NOTE:_** User home topics are located in the %WIKITOOLNAME%.%MAINWEB% web - don't try to move them or create them in other webs. From any web you can refer to users located in the %WIKITOOLNAME%.%MAINWEB% web with %MAINWEB%.UserName or %MAINWEB%.UserName - using the %MAINWEB% variable is preferable, particularly if you might change the %MAINWEB% web name.
### Adding Variables & Rendering Rules
* You can add new %VARIABLES%. Define site-level variables in the [[TWikiPreferences]] topic. See also [[TWikiVariables]].
* You can add new rendering rules or add new functionality to TWiki. To insure an easy upgrade of TWiki, it is recommended to do this sort of customization with [[TWikiPlugins]] and the Plugins API.
### Enabling Basic Authentication (.htaccess)
* If you are on a non-authenticated server - not using SSL - and you would like to authenticate users:
1. **Rename** file `.htaccess.txt` in the `twiki/bin` directory to `.htaccess` and change it to your needs. For details, consult the HTTP server documentation (for Apache server: [[1]](http://www.apache.org/docs/mod/directives.html), [[2]](http://www.mcs.kent.edu/system/web_help/htaccess/introduction.html)). In particular, the following red part needs to be configured correctly: Redirect /urlpath/to/TWiki/index.html http://your.domain.com/urlpath/to/TWiki/bin/viewAuthUserFile /filepath/to/TWiki/data/.htpasswdErrorDocument 401 /urlpath/to/TWiki/bin/oops/TWiki/TWikiRegistration?template=oopsauth
* **_NOTE:_** In case you renamed the CGI script files to have a file extension you need to reflect that in the `edit`, `view`, `preview`, etc entries in `.htaccess`.
* **_NOTE:_** The browser should ask for login name and password when you click on the Edit link. In case `.htaccess` does not have the desired effect you need to enable it: Add "AllowOverride All" to the Directory section of `access.conf` for your `twiki/bin` directory.
2. **Copy** the [[TWikiRegistrationPub]] topic to [[TWikiRegistration]]. Do that by either editing the topics in the%TWIKIWEB% web, or by renaming the `.txt` and `.txt,v` files in the `twiki/data/%TWIKIWEB%` directory.
* **_NOTE:_** You can customize the registration form if needed, like deleting or adding input tags. The `name=""` parameter of the input tags must start with: `"Twk0..."` (if this is an optional entry), or `"Twk1..."` (if this is a required entry). This will ensure that the fields are processed correctly.
* * A new line containing user name and encrypted password gets added to the `data/.htpasswd` file when a users registers. The file that comes with the TWiki installation contains a few user accounts of TWiki core team members (needed for testing). You can edit the file and delete those lines.
## TWiki File System Info
See [[TWikiDocumentation]] for an installed system snapshot and descriptions of all files in the TWiki 01-Sep-2001 distribution.
-- [[MikeMannix]] - 07 Sep 2001