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.



Unpack the distribution (using for example 'tar' or 'WinZip'), and set
your working directory to be the top level of the distribution, then
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?  postgres/mysql"

Answer either "postgres" or "mysql".


  "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 Postgres or
MySQL 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.
(TODO - support SQLite as well (requires faffing with install scripts,
bit messy but CGI::Wiki already supports this so won't be hard))


  "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.


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

Supplying an answer to this question is optional.  TODO - supply and
optionally install a simple stylesheet with the OpenGuides distribution.


  "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.


  "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.

