source: trunk/INSTALL @ 1129

Last change on this file since 1129 was 1129, checked in by Earle Martin, 14 years ago

The section about installing into a private directory really belongs in INSTALL, not TROUBLESHOOTING.

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