Installing QuikWiki
-------------------


QuikWiki is a small wiki that provides, in addition to editing,
saving, and browsing wiki pages with a Web browser, inline JPEG and
GIF image display, version control for edited pages, and embedded Perl
page templates.


Requirements

Perl, version 5.6.0 or later. Also pod2html, if you want to view the
view the manual on-line.  Pod2html is part of the Perl source code
distribution.  If you don't have pod2html, consult your system
administrator.

Apache with mod_perl.  QuikWiki is untested with other HTTP servers.
The program tries to adhere to generic HTTP and CGI protocols.
QuikWiki should work with other Web servers that can run Perl CGI
scripts, although it's untested.  

The section, "Apache Configuration Notes," provides information about
how to configure Apache to run Perl CGI scripts.

Optionally, Revision Control System, if you want QuikWiki to keep
track of revisions.  Without RCS, QuikWiki makes backup copies of
edited pages by adding a, ".bak," extension.


Quick Install

   If the quick install doesn't work for some reason, go to the, 
   "Manual Install," section.  Also read the section, "Apache
   Configuration Notes."

1. Unpack the tar file.  

     tar zxvf quikwiki-<version>.tar.gz

   If you're logged in without superuser privileges, you can
   only install QuikWiki in the public HTML subdirectory of your 
   $HOME directory.  The directory name depends on the Web server 
   configuration.  The name should be something like, "public_html," 
   or, "htdocs."  Ask your Web administrator if you're not certain.

   QuikWiki should also work in any server-accessible directory 
   that has, "Options +ExecCGI," enabled in httpd.conf.

   If upgrading, make sure to back up the old QuikWiki directory.

2. Change to the source code directory and run the configuration
   script.  Configure asks if you want to create a RCS directory 
   for page revisions, and the user ID for the QuikWiki files and 
   directories.  If you're installing quikwiki in <DocumentRoot>, 
   you'll need to have write permissions in that directory 
   (i.e., you're the administrator).

   If you're installing QuikWiki in $HOME/public_html, configure asks
   if you want to rename quikwiki.cgi to index.cgi, so you can avoid
   typing the program name if the Web server configuration does not 
   permit executing symlinked programs in User directories.

     # cd quickwiki-<version>
     # perl configure   

That's it!  (Or, that should be it.) If you don't see the QuikWiki
HomePage, refer to the "Manual Installation" section below.

Browse to the HomePage by typing, in your Web browser,

   http://<server_address>/quikwiki/quikwiki.cgi

Or, alternately,

   http://<server_address>/quikwiki/

If you installed QuikWiki in your ~/public_html directory,

   http://<server_address>/~<your_user_name>/quikwiki/quikwiki.cgi

Substituting the actual network address of the server for
<server_address>, and your actual user name for <your_user_name>.  

If for some reason RCS doesn't provide a Revision number or Last
Modified date/time in the page footer, edit and then save the page to
create the RCS repository.  If you have trouble saving the revision,
double-check the permissions of the page, the RCS subdirectory, and
the RCS archive.

To view QuikWiki's Perl Online Documentation, browse to:

    http://<server_address>/quikwiki/quikwiki.cgi?doc

or click on the, "doc," link in the page header.


Manual Installation

1. Unpack the tar file and change to the QuikWiki source directory.

     tar zxvf quikwiki-<version>.tar.gz
     cd quikwiki-<version>

2. Determine in the location of the system's, "htdocs," directory, 
   the directory named by the "DocumentRoot" directive in the 
   server's httpd.conf file, or the name of the $HOME directory's
   public HTML subdirectory.  The server also needs to have, "Options 
   ExecCGI," enabled for that directory.  Ask your Web administrator 
   if you're not certain.

2. Make quikwiki.cgi executable with the shell command:

     chmod +x quikwiki.cgi

3. If installing system's <DocumentRoot> directory:

     mkdir <DocumentRoot>/quikwiki

   If installing in your public HTML directory:

     mkdir $HOME/<public HTML directory>/quikwiki

3. (Optional)  To use RCS to manage revisions, create a, "RCS," 
   subdirectory.

     mkdir <DocumentRoot>/quikwiki/RCS

   or
 
     mkdir $HOME/<public HTML directory>/quikwiki/RCS

4. If installing the QuikWiki pages and quikwiki.cgi to
   the document directory:

     cp quikwiki.cgi HomePage WikiHeader WikiFooter <DocumentRoot>/quikwiki
     cp eg/QuikReference <DocumentRoot>/quikwiki

   or

     cp quikwiki.cgi HomePage WikiHeader WikiFooter $HOME/<public_html>/quikwiki
     cp eg/QuikReference $HOME/<public_html>/quikwiki

5.  If installing quikwiki.cgi to a script directory. These
    examples use /usr/local/apache/cgi-bin.  In this case,
    you also need to specify in which directory or directories
    the pages are located.  See, "Apache Configuration Notes,"
    below.

     cp HomePage WikiHeader WikiFooter <DocumentRoot>/quikwiki
     cp eg/QuikReference <DocumentRoot>/quikwiki
`    cp quikwiki.cgi /usr/local/apache/cgi-bin

   or

     cp HomePage WikiHeader WikiFooter $HOME/<public_html>/quikwiki
     cp eg/QuikReference $HOME/<public_html>/quikwiki
`    cp quikwiki.cgi /usr/local/apache/cgi-bin

6. You can omit the script name if, "DirectoryIndex index.cgi," is 
   set in, "httpd.conf," or the directory's, ".htaccess," file.  
   You'll need to symlink quikwiki.cgi to index.cgi.

   Change to the installation directory and run the shell command:

     ln -s quikwiki.cgi index.cgi

   The Web server must be configured to permit this.  If the server
   won't execute the script through a symlink, you can also rename
   quikwiki.cgi to index.cgi.  Again, ask your Web administrator.

7. Make sure that Apache can read and write the files.  The
   directories and files need to be owned by the same user as 
   the HTTPD server process, or the user that owns a $HOME<public HTML>
   directory.  

   This example uses, "apache," but the owner should be the 
   user named in the, "User," http.conf directive if installing 
   system-wide.

     cd ..
     chown -R apache quikwiki

   Or even better, make the files and directories group-writable.

   If you have trouble saving page revisions, make certain that the 
   ownership and permissions of the quikwiki and RCS subdirectories,
   the page itself, and the RCS archive, allow you to write to those
   files and directories.


Apache Configuration Notes

There is copious documentation in the mod_perl and Apache source code
packages.  It is easier to allow mod_perl's build to also configure
Apache; then, you can simply, "make install," the HTTP server. 

The HTTPD daemon needs to be configured with modules that are either
loaded at run time (look at the, "Load Module," directive in
httpd.conf, or compiled into the server daemon.  Running "httpd -l"
should provide output like this.

  Compiled-in modules:
    http_core.c
    mod_env.c
    mod_log_config.c
    mod_mime.c
    mod_negotiation.c
    mod_status.c
    mod_include.c
    mod_autoindex.c
    mod_dir.c
    mod_cgi.c
    mod_asis.c
    mod_imap.c
    mod_actions.c
    mod_userdir.c
    mod_alias.c
    mod_access.c
    mod_auth.c
    mod_setenvif.c
    mod_perl.c
  suexec: disabled; invalid wrapper /usr/local/apache/bin/suexec

At least a few of the following httpd.conf directives are necessary
to run QuikWiki or any Perl CGI script.


  # Perl script handler.  This might be present but commented out in 
  # a default httpd.conf file.  The actual path to the Perl binary 
  # should have been configured during compilation.
  <IfModule mod_perl.c>
    <Location /perl>
      SetHandler perl-script
      PerlHandler Apache::Registry
      Options +ExecCGI
    </Location>
  </IfModule>


  # This line should also be uncommented
  AddHandler cgi-script .cgi


  # Adding index.cgi allows you to omit the script's name in URLs.
  <IfModule mod_dir.c>
     DirectoryIndex index.html index.cgi
  </IfModule>


  # The UserDir directive needs to be set if installing
  # in $HOME/public_html
  <IfModule mod_userdir.c>
      UserDir public_html
  </IfModule>


  # The "<Directory /usr/local/apache/htdocs> (use the
  # actual value of DocumentRoot) section should contain the 
  # following options:
      Options Indexes FollowSymLinks ExecCGI


  # These are the default options for ~/public_html subdirectories in
  # the default Apache configuration and should be uncommented in 
  # httpd.conf
  <Directory /home/*/public_html>
    AllowOverride FileInfo AuthConfig Limit
    Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec ExecCGI
    <Limit GET POST OPTIONS PROPFIND>
        Order allow,deny
        Allow from all
    </Limit>
    <LimitExcept GET POST OPTIONS PROPFIND>
        Order deny,allow
        Deny from all
    </LimitExcept>
  </Directory>


  # As an alternative, options can be set in the quikwiki 
  # subdirectory only.
  <Directory /usr/local/apache/htdocs/quikwiki>
      Options +ExecCGI
      # Allow access only by hosts on local network.
      Order allow,deny
      Allow from 192.168.0
  </Directory>


  # In a QuikWiki subdirectory, you can set options in a 
  # .htaccess file.
  Options ExecCGI


  # But this must still be allowed in httpd.conf:
  AllowOverride Options

  #
  #  If you installed quikwiki.cgi in a script directory
  #  and the pages in a different directory you need
  #  to set the environment variable $WIKIPATH in the
  #  Web server's environment.
  #

  SetEnv WIKIPATH  "/usr/local/apache/htdocs/quikwiki:~/public_html/quikwiki"

  #
  # PassEnv allows you to pass an environment variable from the
  # shell that starts the server.
  #

  PassEnv WIKIPATH

  # Then, before starting the server, enter at the shell prompt:

  WIKIPATH="/usr/local/apache/htdocs/quikwiki:~/public_html/quikwiki"; export WIKIPATH

  # You can also list the directories in the quikwiki.cgi script
  # itself.  Add the directories in the line:

  unshift @wikipath, qw(./);


Licensing

  Quikwiki is free software.  You can modify and distribute QuikWiki
  using the same licensing terms as Perl itself.  Consult the file 
  "Artistic" for details.

  Questions concerning QuikWiki (or Apache) configuration, bug
  reports, and suggestions should be sent to the author, 
  rkies@cpan.org.

$Id: README,v 1.3 2007/06/26 04:26:53 kiesling Exp $