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-.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 , 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- # 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:///quikwiki/quikwiki.cgi Or, alternately, http:///quikwiki/ If you installed QuikWiki in your ~/public_html directory, http:///~/quikwiki/quikwiki.cgi Substituting the actual network address of the server for , and your actual user name for . 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:///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-.tar.gz cd quikwiki- 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 directory: mkdir /quikwiki If installing in your public HTML directory: mkdir $HOME//quikwiki 3. (Optional) To use RCS to manage revisions, create a, "RCS," subdirectory. mkdir /quikwiki/RCS or mkdir $HOME//quikwiki/RCS 4. If installing the QuikWiki pages and quikwiki.cgi to the document directory: cp quikwiki.cgi HomePage WikiHeader WikiFooter /quikwiki cp eg/QuikReference /quikwiki or cp quikwiki.cgi HomePage WikiHeader WikiFooter $HOME//quikwiki cp eg/QuikReference $HOME//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 /quikwiki cp eg/QuikReference /quikwiki ` cp quikwiki.cgi /usr/local/apache/cgi-bin or cp HomePage WikiHeader WikiFooter $HOME//quikwiki cp eg/QuikReference $HOME//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 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. SetHandler perl-script PerlHandler Apache::Registry Options +ExecCGI # This line should also be uncommented AddHandler cgi-script .cgi # Adding index.cgi allows you to omit the script's name in URLs. DirectoryIndex index.html index.cgi # The UserDir directive needs to be set if installing # in $HOME/public_html UserDir public_html # The " (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 AllowOverride FileInfo AuthConfig Limit Options MultiViews Indexes SymLinksIfOwnerMatch IncludesNoExec ExecCGI Order allow,deny Allow from all Order deny,allow Deny from all # As an alternative, options can be set in the quikwiki # subdirectory only. Options +ExecCGI # Allow access only by hosts on local network. Order allow,deny Allow from 192.168.0 # 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 $