source: trunk/INSTALL

Last change on this file was 1348, checked in by kake, 9 years ago

Use the basic OpenGuides stylesheet if they don't supply a URL in their wiki.conf

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