source: trunk/INSTALL @ 278

Last change on this file since 278 was 278, checked in by Dominic Hargreaves, 18 years ago

Add documentation about multiple sites on one box, and about tidying up
the URLs with mod_rewrite. Also updated obsolete pointer to grubstreet to
the London guide.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 6.9 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  "What directory can I use to store indexes in for searching?"
86
87You need a directory to store files used as indexes for the site. The
88user that your script will run as will need write permission on this
89directory.  Under some webserver configurations this might be a
90dedicated user - 'nobody' or 'www-data' for example, but for many
91multi-user systems this will just be yourself.
92
93
94  "What's the URL of the wiki's stylesheet?"
95
96Supplying an answer to this question is optional.  There is an example
97stylesheet supplied by the Oxford OpenGuides team in the examples/
98directory - note that this will not be automatically installed.
99
100
101  "What's the wiki called?"
102
103This is a title which will appear at the top of every page.  If you have
104more than one OpenGuides installation at the same site then each should
105have a unique name, since this name is used to manage user preferences.
106
107
108  "Do you want the navigation bar included on the home page?"
109
110Answer "y" or "n".
111
112
113  "What should the home page of the wiki be called?"
114  "How would you describe the wiki?"
115  "What city is the wiki based in?"
116  "What country is the wiki based in?"
117  "Contact email address for the wiki admin?"
118
119Self explanatory.
120
121
122  "What's the name of the node to use for the text formatting rules link?"
123
124From 0.19, OpenGuides allows users to choose whether or not to have a
125permanent link to the text formatting rules node in their navbar.  You
126need to put the name of that node in here for it to work, though.  You
127might want to call the node "Text Formatting Examples", "Text
128Formatting Rules", "House Style" or whatever.
129
130
131* Web server configuration
132
133In order to let your web server serve up OpenGuides correctly, you will
134have to tell it to recognise your installation directory as one
135containing CGI scripts. However you can make your URLs nicer by
136employing mod_rewrite as well. The following Apache configuration
137directives show how:
138
139        Alias /myguide /usr/lib/cgi-bin/myguide
140        <Directory /usr/lib/cgi-bin/myguide>
141            Options FollowSymLinks Indexes ExecCGI
142            RewriteEngine on
143            RewriteBase /myguide/
144            RewriteRule ^$      wiki.cgi        [L]
145        </Directory>
146        Redirect /cgi-bin/myguide/ http://www.example.com/myguide/
147
148You will of course need to make the appropriate substitutions for
149your site. You also need to make sure that mod_rewrite is enabled in
150your web server before adding such a configuration. The final step in
151this URL tidying is to tell OpenGuides that the main CGI script can be
152assumed to be called from the root of the install directory; do this by
153setting the script name to be empty in wiki.conf:
154
155        # what do you want the script to be called?
156        script_name =
157
158Currently the Build script does not support this value, so you will
159have to make sure that you fix this up after an upgrade.
160
161
162* Multiple installations
163
164If you want to run multiple OpenGuides sites on one machine, you can use
165some tricks to make life easier. This isn't currently part of the official
166install routine, but will generally work. In the rest of this section we
167will assume that you already have a working OpenGuides install for a
168single site.
169
170Make a directory for the new site, and populate it with a set of symlinks
171to the main installation directory (ie. for wiki.cgi, supersearch.cgi,
172newpage.cgi, preferences.cgi, and the templates directory). wiki.conf
173will not be a symlink, since this will differ from the original site.
174In this case, simply copy the wiki.conf from the original install and
175modify it in the obvious way; most importantly, by giving it a different
176database name (we'll create the database in a moment). Don't forget to
177set up a separate directory for indices for the new site.
178
179Normally, the database is created by the installation process described
180above; however since we only want one copy of the modules and CGI
181programs, it isn't appropriate to run them again. So we will make use of
182the utility program "cgi-wiki-setupdb" which is included with the
183CGI::Wiki distribution. Documentation for this command can be found in
184its man page; run this with the appropriate arguments to create the
185new database.
186
187Once the key step of setting up the datbase has been performed, and the
188web server configured appropriately, the new site should be ready to go!
Note: See TracBrowser for help on using the repository browser.