source: trunk/INSTALL @ 594

Last change on this file since 594 was 585, checked in by Dominic Hargreaves, 17 years ago

Typo.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 10.4 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  "And the database user that can access that database?"
44  "And 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  "And 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 URL does the install directory map to?"
80
81Give the full address needed to access the installation directory with
82a web browser - for example http://london.openguides.org/cgi-bin/
83
84
85  "Do you want me to munge a custom lib path into the scripts?"
86
87If you have installed some or all of the required Perl modules (or indeed
88the OpenGuides modules themselves) into a private directory, you will
89need to tell the scripts where to find these modules.  Enter the paths
90to search here just as you would enter them in a 'use lib qw( ... );'
91in a Perl script.
92
93
94  "Do you want to use Plucene for searching?"
95
96From version 0.39 of OpenGuides, you have the option of using Plucene
97to index your wiki instead of Search::InvertedIndex.  If you answer
98yes to this question, you will need to make sure you have installed
99both Plucene, and CGI::Wiki version 0.56 or later.
100
101If you are changing to Plucene from Search::InvertedIndex, you will
102need to do two things:
103    - either delete your old indexes (they're just files in the index
104      directory) or use a different index directory
105    - reindex your entire wiki (see reindex.pl in the examples/
106      directory of this distribution)
107
108
109  "What directory can I use to store indexes in for searching?"
110
111You need a directory to store files used as indexes for the site. The
112user that your script will run as will need write permission on this
113directory.  Under some webserver configurations this might be a
114dedicated user - 'nobody' or 'www-data' for example, but for many
115multi-user systems this will just be yourself.
116
117
118  "Do you want to enable page deletion?"
119
120The default is to disable page deletion.  If you choose to enable the
121page deletion mechanism then you will need to add a password to your
122wiki.conf using a line such as
123  admin_pass = putyourpasswordhere
124Users who know this password will be able to delete unwanted pages -
125along with all their history - from your wiki.
126*** USE WITH CAUTION.  DELETED PAGES CANNOT BE RECOVERED. ***
127
128
129  "What's the URL of the wiki's stylesheet?"
130
131Supplying an answer to this question is optional.  There are example
132stylesheets in the examples/ directory - note that these will not be
133automatically installed.
134
135
136  "What's the wiki called?"
137
138This is a title which will appear at the top of every page.  If you have
139more than one OpenGuides installation at the same site then each should
140have a unique name, since this name is used to manage user preferences.
141
142
143  "Do you want the navigation bar included on the home page?"
144
145Answer "y" or "n".
146
147
148  "What should the home page of the wiki be called?"
149  "How would you describe the wiki?"
150  "What city is the wiki based in?"
151  "What country is the wiki based in?"
152  "Contact email address for the wiki admin?"
153
154Self explanatory.
155
156
157  "What language will the site be in? (Please give an ISO language code.)"
158
159eg "en" for English, "it" for Italian.
160See http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt
161
162
163  "What's the name of the node to use for the text formatting rules link?"
164
165From 0.19, OpenGuides allows users to choose whether or not to have a
166permanent link to the text formatting rules node in their navbar.  You
167need to put the name of that node in here for it to work, though.  You
168might want to call the node "Text Formatting Examples", "Text
169Formatting Rules", "House Style" or whatever.
170
171
172  "Distance calculation methods available are:
173      1) British National Grid
174      2) Irish National Grid
175      3) UTM ellipsoid
176   Which would you like to use?"
177
178  (and if you choose UTM ellipsoid)
179  "Which ellipsoid would you like to use? (eg 'Airy', 'WGS-84')"
180
181See http://www.vterrain.org/Projections/ for how this all works.
182A UTM (Universal Transverse Mercator) ellipsoid maps latitude and
183longitude to eastings and northings on a square grid, which allows
184more accurate distance calculations within the guide.  The British and
185Irish National Grids are scaled and parametrised versions of UTM
186ellipsoids (Airy 1830 in the British case, Modified Airy in the Irish).
187
188Please note that at the moment there is no provision for changing your
189mind later about which ellipsoid to use, but it shouldn't be too hard
190to write a conversion script so don't worry too much about picking the
191wrong one.  However do note that once you've entered some location
192data you should not change this value in the config file without running
193some kind of converter.
194
195If you decide to use the British or Irish National Grid, your users
196will be able to choose between entering location data as lat/long
197or as grid co-ordinates.
198
199You must have Geography::NationalGrid::GB installed to use the British
200National Grid, Geography::NationalGrid::IE to use the Irish National
201Grid, and Geo::Coordinates::UTM to use a UTM ellipsoid.
202
203* Dependency errors
204
205If, after you have answered these questions, the build script complains
206about missing dependencies, don't panic! Simply install them from CPAN and
207then try again. Note that a wiki.conf file will have been written out at
208this point, so if you retain it you won't have to answer all the questions
209again.
210
211* Custom templates and CSS
212
213Once you have installed OpenGuides you may wish to edit templates that
214provide site-specific design. These templates are stored in the directory
215custom-templates/ and are described in the file CUSTOMISATION. The id and
216class tags used for the CSS in OpenGuides are specified in README.CSS.
217
218* Web server configuration
219
220In order to let your web server serve up OpenGuides correctly, you will
221have to tell it to recognise your installation directory as one
222containing CGI scripts. However you can make your URLs nicer by
223employing mod_rewrite as well. The following Apache configuration
224directives show how:
225
226        Alias /myguide /usr/lib/cgi-bin/myguide
227        <Directory /usr/lib/cgi-bin/myguide>
228            Options FollowSymLinks Indexes ExecCGI
229            RewriteEngine on
230            RewriteBase /myguide/
231            RewriteRule ^$      wiki.cgi        [L]
232        </Directory>
233        Redirect /cgi-bin/myguide/ http://www.example.com/myguide/
234
235You will of course need to make the appropriate substitutions for
236your site. You also need to make sure that mod_rewrite is enabled in
237your web server before adding such a configuration. The final step in
238this URL tidying is to tell OpenGuides that the main CGI script can be
239assumed to be called from the root of the install directory; do this by
240setting the script name to be empty in wiki.conf:
241
242        # what do you want the script to be called?
243        script_name =
244
245Currently the Build script does not support this value, so you will
246have to make sure that you fix this up after an upgrade.
247
248
249* Multiple installations
250
251If you want to run multiple OpenGuides sites on one machine, you can use
252some tricks to make life easier. This isn't currently part of the official
253install routine, but will generally work. In the rest of this section we
254will assume that you already have a working OpenGuides install for a
255single site.
256
257Make a directory for the new site, and populate it with a set of symlinks
258to the main installation directory (ie. for wiki.cgi, supersearch.cgi,
259newpage.cgi, preferences.cgi, and the templates directory). wiki.conf
260will not be a symlink, since this will differ from the original site.
261In this case, simply copy the wiki.conf from the original install and
262modify it in the obvious way; most importantly, by giving it a different
263database name (we'll create the database in a moment). Don't forget to
264set up a separate directory for indices for the new site.
265
266Normally, the database is created by the installation process described
267above; however since we only want one copy of the modules and CGI
268programs, it isn't appropriate to run them again. So we will make use of
269the utility program "cgi-wiki-setupdb" which is included with the
270CGI::Wiki distribution. Documentation for this command can be found in
271its man page; run this with the appropriate arguments to create the
272new database.
273
274Once the key step of setting up the database has been performed, and the
275web server configured appropriately, the new site should be ready to go!
Note: See TracBrowser for help on using the repository browser.