Changeset 1169


Ignore:
Timestamp:
Jun 21, 2008, 5:55:10 PM (13 years ago)
Author:
kake
Message:

Documentation updates that I forgot to commit (ta Aidy).

Location:
branches/new-install-process
Files:
1 added
1 edited

Legend:

Unmodified
Added
Removed
  • branches/new-install-process/INSTALL

    r1145 r1169  
    22====================================
    33
     4OpenGuides installation has two steps - installing the modules, and setting
     5up a Guide.  Module installation is described in this file, and setting up
     6a Guide is described in SETUP.
    47
    5 If while following the instructions below or while trying to use your
    6 OpenGuides install you see an error that you don't understand, please
    7 consult the TROUBLESHOOTING file.
    88
    9 For details about installing multiple OpenGuides sites on a single
    10 server, or installing OpenGuides into a directory that isn't where
    11 your system Perl library is, see further down this file.
     9* Basic installation of modules
    1210
    13 * Basic installation
     11The OpenGuides distribution _should_ be installable with CPAN.pm or
     12CPANPLUS.pm - i.e., the CPAN shell - and this is probably the simplest
     13way to do it unless you already know you prefer manual installation.
     14
     15If you do prefer manual installation, then:
    1416
    1517Unpack the distribution (using for example 'tar' or 'WinZip'), and set
    16 your working directory to be the top level of the distribution.
    17 
    18 If you have an existing "wiki.conf" configuration file and you wish
    19 to keep using the values in that, copy it to this directory.
     18your working directory (using for example 'cd') to be the top level of
     19the distribution.
    2020
    2121Now execute the following commands:
    2222
    23 perl Build.PL
    24 perl Build
    25 perl Build test
    26 perl Build install
     23  perl Build.PL
     24  perl Build
     25  perl Build test
    2726
    28 The very first of these commands asks a number of questions regarding
    29 the installation.
     27These will prepare your system for installation of the modules, and run some
     28tests to make sure that everything is OK.  If everything is not OK, then please
     29report a bug.  If everything is OK, i.e. all the tests report success, then
    3030
     31  perl Build install
    3132
    32   "Skip OpenGuides configuration?"
     33should install the modules for you.  If you get error messages saying
     34you don't have the correct permissions, then you need to do something
     35along the lines of 'sudo perl Build install', or install the modules
     36in a directory that you do have permission to write to (see below), or
     37ask your sysadmin to do the installation for you.
    3338
    34 Answer "n" to this question unless you really know what you're doing.
    35 It's mainly there for developers. (If you already have a configuration
    36 file, and wish to use it without the build script asking you this
    37 question, run Build.PL with the option --force. This will also skip
    38 the "Continue with install?" question.)
    39 
    40 
    41   "What type of database do you want the site to run on?"
    42 
    43 Answer "postgres", "mysql", or "sqlite".
    44 
    45 
    46   "What's the name of the database that this site runs on?"
    47   "...the database user that can access that database?"
    48   "...the password that they use to access the database?"
    49 
    50 You should create (or ask your ISP/sysadmin to create) a database
    51 specifically for the use of OpenGuides.  If you have more than one
    52 OpenGuides installation, for example if you run guides for more than
    53 one city, each installation will need its own database.
    54 
    55 
    56   "...the machine that the database is hosted on? (blank if local"
    57 
    58 If the database is running on a local machine with username/password
    59 authentication then just press RETURN to skip this question.  If it
    60 is running on a local machine with IDENT authentication then you may
    61 need to answer "localhost" to this question.  If it is running on a
    62 remote machine then enter the full hostname of that machine.
    63 
    64 
    65   "What do you want the script to be called?"
    66 
    67 The default is for the main script to be called "wiki.cgi", but
    68 you may prefer to name it after your city - "leeds-guide.cgi" for
    69 example.  Note that your webserver may be configured to only allow
    70 execution of scripts ending in, for example, ".cgi"
    71 
    72 
    73   "What directory should I install it in?"
    74 
    75 You need to pick a directory for the OpenGuides software to be
    76 installed in.  This must be one known to the webserver as containing
    77 CGI scripts.  You will need to have write permission on this directory
    78 when you come to run "perl Build install"; unless this is a private
    79 directory belonging to you then this might require an 'su' or 'sudo'
    80 to root under Unix.
    81 
    82 
    83   "What directory should I install the templates in?"
    84   "Where should I look for custom templates?"
    85 
    86 Normally these will be in the install directory, but they can be anywhere.
    87 Custom templates are intended to be user-modified, so you might want to
    88 put them somewhere in /etc.
    89 
    90 
    91   "What URL does the install directory map to?"
    92 
    93 Give the full address needed to access the installation directory with
    94 a web browser - for example http://london.openguides.org/
    95 
    96 
    97   "Do you want me to munge a custom lib path into the scripts?"
    98 
    99 If you have installed some or all of the required Perl modules (or indeed
    100 the OpenGuides modules themselves) into a private directory, you will
    101 need to tell the scripts where to find these modules.  Enter the paths
    102 to search here just as you would enter them in a 'use lib qw( ... );'
    103 in a Perl script.
    104 
    105 
    106   "Do you want to use Plucene for searching?"
    107 
    108 This question is no longer asked, but documentation here is retained for
    109 the benefit of people upgrading.
    110 
    111 If you are changing to Plucene from Search::InvertedIndex, you will
    112 need to do two things:
    113     - either delete your old indexes (they're just files in the index
    114       directory) or use a different index directory
    115     - reindex your entire wiki (see reindex.pl in the examples/
    116       directory of this distribution)
    117 
    118 
    119   "What directory can I use to store indexes in for searching?"
    120 
    121 You need a directory to store files used as indexes for the site. The
    122 user that your script will run as will need write permission on this
    123 directory.  Under some webserver configurations this might be a
    124 dedicated user - 'nobody' or 'www-data' for example, but for many
    125 multi-user systems this will just be yourself.
    126 
    127 
    128   "Do you want to enable page deletion?"
    129   "Please specify a password for the site admin."
    130 
    131 The default is to disable page deletion.  If you choose to enable the
    132 page deletion mechanism then you will need to add a password to your
    133 wiki.conf by answering the question above or manually using a line such as
    134   admin_pass = putyourpasswordhere
    135 Users who know this password will be able to delete unwanted pages -
    136 along with all their history - from your wiki.
    137 *** USE WITH CAUTION.  DELETED PAGES CANNOT BE RECOVERED. ***
    138 
    139 
    140   "What's the URL of the site's stylesheet?"
    141 
    142 Supplying an answer to this question is optional.  There are example
    143 stylesheets in the examples/ directory - note that these will not be
    144 automatically installed.
    145 
    146 
    147   "What's the wiki called?"
    148 
    149 This is a title which will appear at the top of every page.  If you have
    150 more than one OpenGuides installation at the same site then each should
    151 have a unique name, since this name is used to manage user preferences.
    152 
    153 
    154   "Do you want the navigation bar included on the home page?"
    155 
    156 Answer "y" or "n".
    157 
    158 
    159   "Do you want the ten most recent changes included on the home page?"
    160 
    161 Answer "y" or "n".
    162 
    163 
    164   "Do you want the Random Page link to avoid returning a locale page?
    165   "Do you want the Random Page link to avoid returning a category page?
    166 
    167 Answer "y" or "n".  The defaults are "n", which means that Random Page is as
    168 likely to return a category or locale page as anything else.  If the category
    169 and locale pages on your Guide are generally just lists of things in that
    170 category/locale, you probably want to pick "y" here.  If, on the other hand,
    171 your category/locale pages generally have substantial content of their own,
    172 you may prefer to choose "n".
    173 
    174 
    175   "Do you want the content to appear above the navbar in the HTML?"
    176 
    177 Answer "y" or "n".  The default is "n", for reasons of backwards
    178 compatibility with existing stylesheets, but the recommended answer is
    179 "y", as this will help search engines to find the most relevant parts
    180 of your pages.
    181 
    182 
    183   "What should the home page of the wiki be called?"
    184   "How would you describe the wiki?"
    185 
    186 Self-explanatory.
    187 
    188 
    189   "What city is the wiki based in?"
    190   "What country is the wiki based in?"
    191 
    192 If the wiki will not be city or country specific you can leave either or
    193 both of these blank.
    194 
    195 
    196   "Contact email address for the wiki admin?"
    197 
    198 Self explanatory.
    199 
    200 
    201   "What language will the site be in? (Please give an ISO language code.)"
    202 
    203 eg "en" for English, "it" for Italian.
    204 See http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt
    205 
    206 
    207   "What's the name of the node or page to use for the text formatting
    208    rules link?"
    209   "What URL do you want to use for the text formatting rules"
    210 
    211 From 0.19, OpenGuides allows users to choose whether or not to have a
    212 permanent link to the text formatting rules node or page in their navbar.
    213 You need to put the name of that node or URL in here for it to work, though.
    214 You might want to call the node "Text Formatting Examples",
    215 "Text Formatting Rules", "House Style" or whatever.
    216 
    217 Note that these the latter question will override the former, so if you
    218 want to use a local node make sure to leave the latter blank.
    219 
    220   "Make node titles link to node backlinks (C2 style)?"
    221 
    222 This refers to turning titles into links which bring up a list of referring
    223 pages. This was the convention with older wikis ("C2" refers to the original
    224 wiki at http://c2.com/cgi/wiki), but is not intuitive.
    225 
    226   "Do you have a Google Maps API key to use with this guide?"
    227 
    228 If you want Google Maps integration, you need to register with Google to get
    229 an API key. Visit http://www.google.com/apis/maps/signup.html and follow the
    230 instructions. Paste the great long string into the console window where you
    231 are installing. See README.GMAPS for more information.
    232 
    233   "What is the longitude of the centre point of a map to draw for your guide?"
    234   "What is the latitude of the centre point of a map to draw for your guide?"
    235 
    236 It's probably a good idea to pick some notionally central point for your
    237 guide. For example, Carfax for Oxford, Charing Cross for London. As a
    238 convenience, you may paste in a Google Maps URL for the centre longitude
    239 question and the (long,lat) will be parsed out from the URL.
    240 
    241   "What default zoom level shall we use for Google Maps?"
    242   "What default zoom level shall we use for Google Maps in the search results?"
    243 
    244 The defaults are probably appropriate in most cases.
    245 
    246   "Would you like to display a Google Map on every node that has geodata?"
    247 
    248 Answer "y" or "n".  Note that an answer of "y" will only take effect if you've
    249 supplied a Google Maps API key above.  Note further that users can choose to
    250 turn this off in their preferences.
    251  
    252   "Forcibly treat stored lat/long data as if they used the WGS84 ellipsoid?"
    253 
    254 Default this answer if you don't know what it means.
    255 
    256   "Do you have a Google Analytics key to use with this guide?"
    257 
    258 If you'd like to use Google Analytics to track the traffic on your guide,
    259 visit http://www.google.com/analytics/ to sign up for a key.  The answer to
    260 this question is the string in quotes in the HTML fragment they ask you to
    261 paste into your HTML, something along the lines of _uacct = "UA-1234567-1"
    262 - it's the UA-1234567-1 part that you need to put in here.  If you've
    263 forgotten your key, go to Analytics Settings, click "Edit" under Settings,
    264 then click "Check Status" in the top right-hand corner of the box with grey
    265 stripes.
    266 
    267 
    268   "What licence will you use for the guide?"
    269 
    270 We strongly recommend that you think at the outset about the licence your
    271 guide will use, for maximum usefulness. In particular for a guide that will
    272 be on the OpenGuides network, we recommend the
    273 "Creative Commons Attribution-ShareAlike 2.5" licence.
    274 
    275   "What is the URL to your licence?"
    276 
    277 If you used our recommendation above the URL you will want here is:
    278 http://creativecommons.org/licenses/by-sa/2.5/
    279 
    280   "What is the URL to your local page about your licensing policy?"
    281 
    282 You should probably include a page on your wiki about your local licensing
    283 policy, but you can leave this blank for now if you don't have one yet.
    284 
    285   "What module would you like to use for spam detection? (optional)"
    286 
    287 The module you choose should have a method called "looks_like_spam", which
    288 accepts a hash with content and metadata as keys, and returns true or false
    289 to the question of whether the edit should be considered to be spam.
    290 
    291   "What directory should we install static content (CSS, images, javascript)
    292    to?"
    293 
    294 OpenGuides comes with some static content which will be installed
    295 automatically.
    296 
    297   "What is the URL corresponding to the static content?"
    298 
    299 You will need to configure the above directory in your web server, then
    300 input the URL the content will be visible at here.
    301 
    302   "Should we send email notifications when a moderated node is edited?"
    303 
    304 For spam avoidance, you can configure certain nodes to require moderation.
    305 To ensure that such edits are noticed, OpenGuides can email you.
    306 
    307   "Distance calculation methods available are:
    308       1) British National Grid
    309       2) Irish National Grid
    310       3) UTM ellipsoid
    311    Which would you like to use?"
    312 
    313   (and if you choose UTM ellipsoid)
    314   "Which ellipsoid would you like to use? (eg 'Airy', 'WGS-84')"
    315 
    316 See http://www.vterrain.org/Projections/ for how this all works.
    317 A UTM (Universal Transverse Mercator) ellipsoid maps latitude and
    318 longitude to eastings and northings on a square grid, which allows
    319 more accurate distance calculations within the guide.  The British and
    320 Irish National Grids are scaled and parametrised versions of UTM
    321 ellipsoids (Airy 1830 in the British case, Modified Airy in the Irish).
    322 
    323 Please note that at the moment there is no provision for changing your
    324 mind later about which ellipsoid to use, but it shouldn't be too hard
    325 to write a conversion script so don't worry too much about picking the
    326 wrong one.  However do note that once you've entered some location
    327 data you should not change this value in the config file without running
    328 some kind of converter.
    329 
    330 If you decide to use the British or Irish National Grid, your users
    331 will be able to choose between entering location data as lat/long
    332 or as grid co-ordinates.
    333 
    334 You must have Geography::NationalGrid::GB installed to use the British
    335 National Grid, Geography::NationalGrid::IE to use the Irish National
    336 Grid, and Geo::Coordinates::UTM to use a UTM ellipsoid.
    337 
    338 If you want to use a UTM ellipsoid, WGS-84 is the best choice, as it
    339 will allow you to use the Google Maps support with the minimum of fuss.
    340 
    341 * Dependency errors
    342 
    343 If, after you have answered these questions, the build script complains
    344 about missing dependencies, don't panic! Simply install them from CPAN and
    345 then try again. Note that a wiki.conf file will have been written out at
    346 this point, so if you retain it you won't have to answer all the questions
    347 again.
    348 
    349 * Custom templates and CSS
    350 
    351 Once you have installed OpenGuides you may wish to edit templates that
    352 provide site-specific design. These templates are stored in the directory
    353 custom-templates/ by default and are described in the file CUSTOMISATION.
    354 
    355 The id and class tags used for the CSS in OpenGuides are specified in
    356 README.CSS.
    357 
    358 * Security
    359 
    360 The installer will try to create (or modify an existing) a .htaccess file
    361 to protect wiki.conf, which contains sensitive data (ie passwords).
    362 However we cannot tell whether apache (or any other web server you may be
    363 using) is using this file, so you should check that it functioning and that
    364 you cannot access wiki.conf over HTTP.
    365 
    366 You should also configure wiki.conf with the minimum permissions required
    367 so that local users cannot read the file. This is difficult to automate,
    368 but the file should be probably be mode 0640, owned by root or an admin
    369 user, and set to the group the web server runs with.
    370 
    371 * Web server configuration
    372 
    373 In order to let your web server serve up OpenGuides correctly, you will
    374 have to tell it to recognise your installation directory as one
    375 containing CGI scripts. However you can make your URLs nicer by
    376 employing mod_rewrite as well. The following Apache configuration
    377 directives show how:
    378 
    379         Alias /myguide /usr/lib/cgi-bin/myguide
    380         <Directory /usr/lib/cgi-bin/myguide>
    381             Options FollowSymLinks Indexes ExecCGI
    382             RewriteEngine on
    383             RewriteBase /myguide/
    384             RewriteRule ^$      wiki.cgi        [L]
    385         </Directory>
    386         Redirect /cgi-bin/myguide/ http://www.example.com/myguide/
    387 
    388 You will of course need to make the appropriate substitutions for
    389 your site. You also need to make sure that mod_rewrite is enabled in
    390 your web server before adding such a configuration. The final step in
    391 this URL tidying is to tell OpenGuides that the main CGI script can be
    392 assumed to be called from the root of the install directory; do this by
    393 setting the script name to be empty in wiki.conf:
    394 
    395         # what do you want the script to be called?
    396         script_name =
    397 
    398 Currently the Build script does not support this value, so you will
    399 have to make sure that you fix this up after an upgrade.
    40039
    40140* Custom install locations
     
    41655  perl Build.PL config='sitelib=/path/to/my/modules/'
    41756
    418 If any or all of the modules required by the OpenGuides scripts are in
    419 a private directory, then you'll need to tell the scripts where to find
    420 them. See the section above about munging in a custom lib path.
    421 
    422 ----------------------------------------------------------------------
    423 
    424 Important note for those using SQLite:
    425 
    426 The user your CGI is running as must have write access to not only the
    427 database file itself, but the directory that the file is in, in order
    428 that it can write a lockfile. If it doesn't have write access to the
    429 database file, you'll see errors like "Unhandled error: [DBD::SQLite::db
    430 do failed...".
    431 
    432 ----------------------------------------------------------------------
    433 
    434 * Multiple installations
    435 
    436 If you want to run multiple OpenGuides sites on one machine, you can use
    437 some tricks to make life easier. This isn't currently part of the official
    438 install routine, but will generally work. In the rest of this section we
    439 will assume that you already have a working OpenGuides install for a
    440 single site.
    441 
    442 Make a directory for the new site, and populate it with a set of symlinks
    443 to the main installation directory (ie. for wiki.cgi, supersearch.cgi,
    444 newpage.cgi, preferences.cgi, and the templates directory). wiki.conf
    445 will not be a symlink, since this will differ from the original site.
    446 In this case, simply copy the wiki.conf from the original install and
    447 modify it in the obvious way; most importantly, by giving it a different
    448 database name (we'll create the database in a moment). Don't forget to
    449 set up a separate directory for indices for the new site.
    450 
    451 Normally, the database is created by the installation process described
    452 above; however since we only want one copy of the modules and CGI
    453 programs, it isn't appropriate to run them again. So we will make use of
    454 the utility program "cgi-wiki-setupdb" which is included with the
    455 Wiki::Toolkit distribution. Documentation for this command can be found in
    456 its man page; run this with the appropriate arguments to create the
    457 new database.
    458 
    459 Once the key step of setting up the database has been performed, and the
    460 web server configured appropriately, the new site should be ready to go!
     57If you do choose this option, then when you come to set up a Guide you'll
     58need to make sure that the scripts know where to find your modules.  See
     59the documentation on custom lib paths in SETUP.
Note: See TracChangeset for help on using the changeset viewer.