source: trunk/INSTALL @ 1037

Last change on this file since 1037 was 1037, checked in by kake, 14 years ago

Added experimental support for local spam detection modules.

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