OpenGuides installation instructions
====================================


If while following the instructions below or while trying to use your
OpenGuides install you see an error that you don't understand, please
consult the TROUBLESHOOTING file.

For details about installing multiple OpenGuides sites on a single
server, see further down this file.

* Basic installation

Unpack the distribution (using for example 'tar' or 'WinZip'), and set
your working directory to be the top level of the distribution.

If you have an existing "wiki.conf" configuration file and you wish
to keep using the values in that, copy it to this directory.

Now execute the following commands:

perl Build.PL
perl Build
perl Build test
perl Build install

The very first of these commands asks a number of questions regarding
the installation.


  "Skip OpenGuides configuration?"

Answer "n" to this question unless you really know what you're doing.
It's mainly there for developers.


  "what type of database do you want the site to run on?"

Answer "postgres", "mysql", or "sqlite".


  "What's the name of the database that this site runs on?"
  "And the database user that can access that database?"
  "And the password that they use to access the database?"

You should create (or ask your ISP/sysadmin to create) a database
specifically for the use of OpenGuides.  If you have more than one
OpenGuides installation, for example if you run guides for more than
one city, each installation will need its own database.


  "And the machine that the database is hosted on? (blank if local)",

If the database is running on a local machine with username/password
authentication then just press RETURN to skip this question.  If it
is running on a local machine with IDENT authentication then you may
need to answer "localhost" to this question.  If it is running on a
remote machine then enter the full hostname of that machine.


  "What do you want the script to be called?"

The default is for the main script to be called "wiki.cgi", but
you may prefer to name it after your city - "leeds-guide.cgi" for
example.  Note that your webserver may be configured to only allow
execution of scripts ending in, for example, ".cgi"


  "What directory should I install it in?"

You need to pick a directory for the OpenGuides software to be
installed in.  This must be one known to the webserver as containing
CGI scripts.  You will need to have write permission on this directory
when you come to run "perl Build install"; unless this is a private
directory belonging to you then this might require an 'su' or 'sudo'
to root under Unix.


  "What URL does the install directory map to?"

Give the full address needed to access the installation directory with
a web browser - for example http://london.openguides.org/cgi-bin/


  "What directory can I use to store indexes in for searching?"

You need a directory to store files used as indexes for the site. The
user that your script will run as will need write permission on this
directory.  Under some webserver configurations this might be a
dedicated user - 'nobody' or 'www-data' for example, but for many
multi-user systems this will just be yourself.


  "Do you want to enable page deletion?"

The default is to disable page deletion.  If you choose to enable the
page deletion mechanism then you will need to add a password to your
wiki.conf using a line such as
  admin_pass = putyourpasswordhere
Users who know this password will be able to delete unwanted pages -
along with all their history - from your wiki.
*** USE WITH CAUTION.  DELETED PAGES CANNOT BE RECOVERED. ***


  "What's the URL of the wiki's stylesheet?"

Supplying an answer to this question is optional.  There are example
stylesheets in the examples/ directory - note that these will not be 
automatically installed.


  "What's the wiki called?"

This is a title which will appear at the top of every page.  If you have
more than one OpenGuides installation at the same site then each should
have a unique name, since this name is used to manage user preferences.


  "Do you want the navigation bar included on the home page?"

Answer "y" or "n".


  "What should the home page of the wiki be called?"
  "How would you describe the wiki?"
  "What city is the wiki based in?"
  "What country is the wiki based in?"
  "Contact email address for the wiki admin?"

Self explanatory.


  "What's the name of the node to use for the text formatting rules link?"

From 0.19, OpenGuides allows users to choose whether or not to have a
permanent link to the text formatting rules node in their navbar.  You
need to put the name of that node in here for it to work, though.  You
might want to call the node "Text Formatting Examples", "Text
Formatting Rules", "House Style" or whatever.


* Web server configuration

In order to let your web server serve up OpenGuides correctly, you will
have to tell it to recognise your installation directory as one
containing CGI scripts. However you can make your URLs nicer by
employing mod_rewrite as well. The following Apache configuration
directives show how:

	Alias /myguide /usr/lib/cgi-bin/myguide
	<Directory /usr/lib/cgi-bin/myguide>
	    Options FollowSymLinks Indexes ExecCGI
	    RewriteEngine on
	    RewriteBase /myguide/
	    RewriteRule ^$      wiki.cgi        [L]
	</Directory>
	Redirect /cgi-bin/myguide/ http://www.example.com/myguide/

You will of course need to make the appropriate substitutions for
your site. You also need to make sure that mod_rewrite is enabled in
your web server before adding such a configuration. The final step in
this URL tidying is to tell OpenGuides that the main CGI script can be
assumed to be called from the root of the install directory; do this by
setting the script name to be empty in wiki.conf:

	# what do you want the script to be called?
	script_name =

Currently the Build script does not support this value, so you will
have to make sure that you fix this up after an upgrade.


* Multiple installations

If you want to run multiple OpenGuides sites on one machine, you can use
some tricks to make life easier. This isn't currently part of the official
install routine, but will generally work. In the rest of this section we
will assume that you already have a working OpenGuides install for a
single site.

Make a directory for the new site, and populate it with a set of symlinks
to the main installation directory (ie. for wiki.cgi, supersearch.cgi,
newpage.cgi, preferences.cgi, and the templates directory). wiki.conf
will not be a symlink, since this will differ from the original site.
In this case, simply copy the wiki.conf from the original install and
modify it in the obvious way; most importantly, by giving it a different
database name (we'll create the database in a moment). Don't forget to
set up a separate directory for indices for the new site.

Normally, the database is created by the installation process described
above; however since we only want one copy of the modules and CGI
programs, it isn't appropriate to run them again. So we will make use of
the utility program "cgi-wiki-setupdb" which is included with the
CGI::Wiki distribution. Documentation for this command can be found in
its man page; run this with the appropriate arguments to create the
new database.

Once the key step of setting up the datbase has been performed, and the
web server configured appropriately, the new site should be ready to go!
