root/branches/new-install-process/SETUP

OpenGuides setup instructions
=============================

OpenGuides installation has two steps - installing the modules, and setting
up a Guide.  Module installation is described in INSTALL, and setting up
a Guide is described in this file.  You need to install the modules before
you can set up a Guide.


* Basic setup

Guide setup is done using the script

  openguides-install

which should have been installed somewhere suitable when you installed
the modules.  If it isn't in your path, then you could try the
"locate" or "find" commands to figure out where it is.  If it doesn't
seem to be anywhere on your system, then you may be using an old version
of OpenGuides - upgrade to the latest version, and then try again.

When you run this script, it will ask you a number of questions.  Once
you've answered them all, the script will write out a configuration file
containing all your answers, and then install the CGI scripts, templates,
any static content (e.g. CSS), and the configuration file in the places
you told it to.

These questions are described below in the section entitled "Setup questions".


* Important note for those using SQLite:

The user that your Guide is running as must have write access to not only
the database file itself, but the directory that the file is in, in order
that it can write a lockfile. If it doesn't have write access to the
database file, you'll see errors like "Unhandled error: [DBD::SQLite::db do
failed...".


* Custom templates and CSS

Once you have set up a Guide, you may wish to edit certain of the templates
that provide site-specific design. These templates are stored in the
directory custom-templates/ by default and are described in the file
CUSTOMISATION.

The id and class tags used for the CSS in OpenGuides are specified in
README.CSS.


* Security

The openguides-install script will try to create an .htaccess file (or
modify any existing one) in order to protect wiki.conf, which contains
sensitive data (specifically, passwords).  However we cannot tell whether
apache (or any other web server you may be using) is using this file, so
you should check that is it functioning and that you cannot access
wiki.conf over HTTP.

You should also configure wiki.conf with the minimum permissions required
so that local users cannot read the file. This is difficult to automate,
but the file should be probably be mode 0640, owned by root or an admin
user, and set to the group the web server runs with.


* 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 installation script does not support this value, so you will
have to make sure that you fix this up after an upgrade.


* Setup questions

When you run the openguides-install script, it will check the current
directory to see if it can find a wiki.conf file.  If it doesn't find one,
it will check that you want to continue with the installation.  If you choose
yes, then a number of questions will follow; these are described below.


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

Options here are "postgres", "mysql", or "sqlite".  If you choose an option
that you don't have the appropriate database driver for, then the script will
tell you this and exit.


  "What's the full filename of the SQLite database this site runs on?"

You will only be asked this question if you chose sqlite in the previous
question.  Enter the full path, e.g. /home/kake/data.db, even if the file
is/will be in the current directory.  You do not have to create this file
in advance; the setup process will do this for you.


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

You will only be asked these questions if you chose mysql or postgres in
the question about the type of database.

You should create (or ask your ISP/sysadmin to create) a database
specifically for your Guide.  If you wish to run more than one Guide, then
each one will need its own database.  The final two questions are optional.
If your database user doesn't need a password to access the database, then
just press RETURN to skip the question about passwords.  Similarly, if the
database is running on a local machine with username/password
authentication then just press RETURN to skip the question about the
machine that the database is hosted on.  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 directory should I install the templates in?" 
  "Where should I look for custom templates?"

Normally these will be in the install directory, but they can be anywhere.
Custom templates are intended to be user-modified, so you might want to
put them somewhere in /etc.


  "What URL does the install directory map to?"

Give the full address needed to access the installation directory with
a web browser, including the "http://" prefix - for example,
http://london.openguides.org/


  "Do you want me to munge a custom lib path into the scripts?"

If you have installed some or all of the required Perl modules (or indeed
the OpenGuides modules themselves) into a private directory, you will
need to tell the scripts where to find these modules.  Enter the paths
to search here just as you would enter them in a 'use lib qw( ... );'
in a Perl script.


  "Do you want to use Plucene for searching?"

This question is no longer asked, but documentation here is retained for
the benefit of people upgrading.

If you are changing to Plucene from Search::InvertedIndex, you will
need to do two things:
    - either delete your old indexes (they're just files in the index
      directory) or use a different index directory
    - reindex your entire wiki (see reindex.pl in the examples/
      directory of this distribution)


  "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?"
  "Please specify a password for the site admin."

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 by answering the question above or manually 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 site'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".


  "Do you want the ten most recent changes included on the home page?"

Answer "y" or "n".


  "Do you want the Random Page link to avoid returning a locale page?
  "Do you want the Random Page link to avoid returning a category page?

Answer "y" or "n".  The defaults are "n", which means that Random Page is as
likely to return a category or locale page as anything else.  If the category
and locale pages on your Guide are generally just lists of things in that
category/locale, you probably want to pick "y" here.  If, on the other hand,
your category/locale pages generally have substantial content of their own,
you may prefer to choose "n".


  "Do you want the content to appear above the navbar in the HTML?"

Answer "y" or "n".  The default is "n", for reasons of backwards
compatibility with existing stylesheets, but the recommended answer is
"y", as this will help search engines to find the most relevant parts
of your pages.


  "What should the home page of the wiki be called?"
  "How would you describe the wiki?"

Self-explanatory.


  "What city is the wiki based in?"
  "What country is the wiki based in?"

If the wiki will not be city or country specific you can leave either or
both of these blank.


  "Contact email address for the wiki admin?"

Self explanatory.


  "What language will the site be in? (Please give an ISO language code.)"

eg "en" for English, "it" for Italian.
See http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt


  "What's the name of the node or page to use for the text formatting
   rules link?"
  "What URL do you want to use for the text formatting rules"

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

Note that these the latter question will override the former, so if you
want to use a local node make sure to leave the latter blank.

  "Make node titles link to node backlinks (C2 style)?"

This refers to turning titles into links which bring up a list of referring
pages. This was the convention with older wikis ("C2" refers to the original
wiki at http://c2.com/cgi/wiki), but is not intuitive.

  "Do you have a Google Maps API key to use with this guide?"

If you want Google Maps integration, you need to register with Google to get
an API key. Visit http://www.google.com/apis/maps/signup.html and follow the
instructions. Paste the great long string into the console window where you
are installing. See README.GMAPS for more information.

  "What is the longitude of the centre point of a map to draw for your guide?"
  "What is the latitude of the centre point of a map to draw for your guide?"

It's probably a good idea to pick some notionally central point for your
guide. For example, Carfax for Oxford, Charing Cross for London. As a
convenience, you may paste in a Google Maps URL for the centre longitude
question and the (long,lat) will be parsed out from the URL.

  "What default zoom level shall we use for Google Maps?"
  "What default zoom level shall we use for Google Maps in the search results?"

The defaults are probably appropriate in most cases.

  "Would you like to display a Google Map on every node that has geodata?"

Answer "y" or "n".  Note that an answer of "y" will only take effect if you've
supplied a Google Maps API key above.  Note further that users can choose to
turn this off in their preferences.
 
  "Forcibly treat stored lat/long data as if they used the WGS84 ellipsoid?"

Default this answer if you don't know what it means.

  "Do you have a Google Analytics key to use with this guide?"

If you'd like to use Google Analytics to track the traffic on your guide,
visit http://www.google.com/analytics/ to sign up for a key.  The answer to
this question is the string in quotes in the HTML fragment they ask you to
paste into your HTML, something along the lines of _uacct = "UA-1234567-1"
- it's the UA-1234567-1 part that you need to put in here.  If you've
forgotten your key, go to Analytics Settings, click "Edit" under Settings,
then click "Check Status" in the top right-hand corner of the box with grey
stripes.


  "What licence will you use for the guide?"

We strongly recommend that you think at the outset about the licence your
guide will use, for maximum usefulness. In particular for a guide that will
be on the OpenGuides network, we recommend the
"Creative Commons Attribution-ShareAlike 2.5" licence.

  "What is the URL to your licence?"

If you used our recommendation above the URL you will want here is:
http://creativecommons.org/licenses/by-sa/2.5/

  "What is the URL to your local page about your licensing policy?"

You should probably include a page on your wiki about your local licensing
policy, but you can leave this blank for now if you don't have one yet.

  "What module would you like to use for spam detection? (optional)"

The module you choose should have a method called "looks_like_spam", which
accepts a hash with content and metadata as keys, and returns true or false
to the question of whether the edit should be considered to be spam. 

  "What directory should we install static content (CSS, images, javascript)
   to?"

OpenGuides comes with some static content which will be installed
automatically.

  "What is the URL corresponding to the static content?"

You will need to configure the above directory in your web server, then
input the URL the content will be visible at here.

  "Should we send email notifications when a moderated node is edited?"

For spam avoidance, you can configure certain nodes to require moderation.
To ensure that such edits are noticed, OpenGuides can email you.

  "Distance calculation methods available are:
      1) British National Grid
      2) Irish National Grid
      3) UTM ellipsoid
   Which would you like to use?"

  (and if you choose UTM ellipsoid)
  "Which ellipsoid would you like to use? (eg 'Airy', 'WGS-84')"

See http://www.vterrain.org/Projections/ for how this all works.
A UTM (Universal Transverse Mercator) ellipsoid maps latitude and
longitude to eastings and northings on a square grid, which allows
more accurate distance calculations within the guide.  The British and
Irish National Grids are scaled and parametrised versions of UTM
ellipsoids (Airy 1830 in the British case, Modified Airy in the Irish).

Please note that at the moment there is no provision for changing your
mind later about which ellipsoid to use, but it shouldn't be too hard
to write a conversion script so don't worry too much about picking the
wrong one.  However do note that once you've entered some location
data you should not change this value in the config file without running
some kind of converter.

If you decide to use the British or Irish National Grid, your users
will be able to choose between entering location data as lat/long
or as grid co-ordinates.

You must have Geography::NationalGrid::GB installed to use the British
National Grid, Geography::NationalGrid::IE to use the Irish National
Grid, and Geo::Coordinates::UTM to use a UTM ellipsoid.

If you want to use a UTM ellipsoid, WGS-84 is the best choice, as it
will allow you to use the Google Maps support with the minimum of fuss.