LP865817: Fix Located URI visibility test
[Evergreen.git] / README
1 README for Evergreen master
2 ===========================
3
4 Installing prerequisites:
5 -------------------------
6
7 Evergreen has a number of prerequisite packages that must be installed
8 before you can successfully configure, compile, and install Evergreen.
9
10 1. Begin by installing the most recent version of OpenSRF (2.0 or later).
11    You can download OpenSRF releases from http://evergreen-ils.org/downloads
12 2. On many distributions, it is necessary to install PostgreSQL 9 from external
13    repositories.
14 +
15   * On Debian Squeeze, add the following line to `/etc/apt/sources.list`:
16 +
17 [source, bash]
18 ------------------------------------------------------------------------------
19 deb http://backports.debian.org/debian-backports squeeze-backports main contrib
20 ------------------------------------------------------------------------------
21 +
22   * On Ubuntu Lucid, add the following line to `/etc/apt/sources.list`:
23 +
24 [source, bash]
25 ------------------------------------------------------------------------------
26 deb http://archive.ubuntu.com/ubuntu lucid-backports main universe multiverse restricted
27 ------------------------------------------------------------------------------
28 +
29   * Fedora 15 comes with PostgreSQL 9, so no additional steps are required.
30 +
31 3. On Debian and Ubuntu, run `aptitude update` to retrieve the new packages
32    from the backports repository.
33 4. On Debian and Ubuntu, the easiest way to install the rest of the
34    prerequisites for Evergreen is to use the Makefile.install prerequisite
35    installer.
36 5. Issue the following commands as the root user to install prerequisites
37    using the Makefile.install prerequisite installer, substituting
38    `debian-squeeze`, `fedora15`, `ubuntu-lucid`, `centos`, or
39    `rhel` for <osname> below:
40 +
41 [source, bash]
42 ------------------------------------------------------------------------------
43 make -f Open-ILS/src/extras/Makefile.install <osname>
44 ------------------------------------------------------------------------------
45 +
46 Note: `centos` and `rhel` are less tested than the `debian`, `fedora`,
47 and `ubuntu` options.  Your patches and suggestions for improvement are
48 welcome!
49 +
50 6. Add the libdbi-libdbd libraries to the system dynamic library path by
51    issuing the following commands as the root user:
52 +
53 .Debian / Ubuntu
54 [source, bash]
55 ------------------------------------------------------------------------------
56 echo "/usr/local/lib/dbd" > /etc/ld.so.conf.d/eg.conf
57 ldconfig
58 ------------------------------------------------------------------------------
59 +
60 .Fedora
61 [source, bash]
62 ------------------------------------------------------------------------------
63 echo "/usr/lib64/dbd" > /etc/ld.so.conf.d/eg.conf
64 ldconfig
65 ------------------------------------------------------------------------------
66
67 Configuration and compilation instructions:
68 -------------------------------------------
69
70 For the time being, we are still installing everything in the `/openils/`
71 directory. If you are working with a version of Evergreen taken directly
72 from the Git repository, rather than a packaged version of Evergreen,
73 first see `Developer instructions` below.
74
75 Otherwise, issue the following commands to configure and build Evergreen:
76
77 [source, bash]
78 ------------------------------------------------------------------------------
79 ./configure --prefix=/openils --sysconfdir=/openils/conf
80 make
81 ------------------------------------------------------------------------------
82
83 Installation instructions:
84 --------------------------
85
86 1. Once you have configured and compiled Evergreen, issue the following
87    command as the root user to install Evergreen, build the server portion of
88    the staff client, and copy example configuration files to `/openils/conf`.
89    Change the value of the `STAFF_CLIENT_STAMP_ID` variable to match the version
90    of the staff client that you will use to connect to the Evergreen server.
91 +
92 [source, bash]
93 ------------------------------------------------------------------------------
94 make STAFF_CLIENT_STAMP_ID=rel_name install
95 ------------------------------------------------------------------------------
96 +
97 2. The server portion of the staff client expects `http://hostname/xul/server`
98    to resolve. The following command creates a symbolic link pointing to the
99    `server` subdirectory of the server portion of the staff client that we just
100    built using the staff client ID 'rel_name':
101 +
102 [source, bash]
103 ------------------------------------------------------------------------------
104 cd /openils/var/web/xul
105 ln -sf rel_name/server server
106 ------------------------------------------------------------------------------
107
108 Change ownership of the Evergreen files:
109 ----------------------------------------
110
111 All files in the `/openils/` directory and subdirectories must be owned by the
112 `opensrf` user. Issue the following command as the root user to change the
113 ownership on the files:
114
115 [source, bash]
116 ------------------------------------------------------------------------------
117 chown -R opensrf:opensrf /openils
118 ------------------------------------------------------------------------------
119
120 Configure the Apache Web server:
121 --------------------------------
122
123 1. Use the example configuration files in `Open-ILS/examples/apache/` to configure
124 your Web server for the Evergreen catalog, staff client, Web services, and
125 administration interfaces.
126 +
127 .Debian and Ubuntu
128 [source,bash]
129 ------------------------------------------------------------------------------
130 cp Open-ILS/examples/apache/eg.conf       /etc/apache2/sites-available/
131 cp Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/
132 cp Open-ILS/examples/apache/startup.pl    /etc/apache2/
133 # Now set up SSL
134 mkdir /etc/apache2/ssl
135 cd /etc/apache2/ssl
136 ------------------------------------------------------------------------------
137 +
138 .Fedora
139 [source,bash]
140 ------------------------------------------------------------------------------
141 cp Open-ILS/examples/apache/eg.conf       /etc/httpd/sites-available/
142 cp Open-ILS/examples/apache/eg_vhost.conf /etc/httpd/
143 cp Open-ILS/examples/apache/startup.pl    /etc/httpd/
144 # Now set up SSL
145 mkdir /etc/httpd/ssl
146 cd /etc/httpd/ssl
147 ------------------------------------------------------------------------------
148 +
149 2. Create an SSL key for the Apache server:
150 +
151 [source,bash]
152 ------------------------------------------------------------------------------
153 openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key
154 ------------------------------------------------------------------------------
155 +
156 The `openssl` command cuts a new SSL key for your Apache server. For a
157 production server, you should purchase a signed SSL certificate, but you can
158 just use a self-signed certificate and accept the warnings in the staff client
159 and browser during testing and development
160 +
161 3. Edit the `eg.conf` file that you copied into place.
162   a. Replace `Allow from 10.0.0.0/8` with `Allow from all` (to enable
163      access to the offline upload / execute interface from any workstation on
164      any network - note that you must secure this for a production instance)
165 4. Change the user for the Apache server.
166   * (Debian and Ubuntu): As the root user, edit `/etc/apache2/envvars`.
167     Change `export APACHE_RUN_USER=www-data` to 
168     `export APACHE_RUN_USER=opensrf`.
169   * (Fedora): As the root user, edit `/etc/httpd/conf/httpd.conf`. Change
170     `User apache` to `User opensrf`.
171 5. Configure Apache with performance settings appropriate for Evergreen:
172   * (Debian and Ubuntu): As the root user, edit `/etc/apache2/apache2.conf`:
173   * (Fedora): As the root user, edit `/etc/httpd/conf/httpd.conf`:
174     a. Change `KeepAliveTimeout` to `1`. Higher values reduce the chance of
175        a request timing out unexpectedly, but increase the risk of using up
176        all available Apache child processes.
177     b. 'Optional': Change `MaxKeepAliveRequests` to `100`
178     c. Update the prefork configuration section to suit your environment. The
179        following settings apply to a busy system:
180 +
181 [source,bash]
182 ------------------------------------------------------------------------------
183 <IfModule mpm_prefork_module>
184    StartServers           20
185    MinSpareServers         5
186    MaxSpareServers        15
187    MaxClients            150
188    MaxRequestsPerChild 10000
189 </IfModule>
190 ------------------------------------------------------------------------------
191 +
192 6. (Debian and Ubuntu): As the root user, enable the Evergreen site:
193 +
194 [source,bash]
195 ------------------------------------------------------------------------------
196 a2dissite default  # OPTIONAL: disable the default site (the "It Works" page)
197 a2ensite eg.conf
198 ------------------------------------------------------------------------------
199
200 Configure OpenSRF for the Evergreen application:
201 ------------------------------------------------
202 There are a number of example OpenSRF configuration files in `/openils/conf/`
203 that you can use as a template for your Evergreen installation.
204
205 [source, bash]
206 ------------------------------------------------------------------------------
207 cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml
208 cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml
209 ------------------------------------------------------------------------------
210
211 When you installed OpenSRF, you created four Jabber users on two
212 separate domains and edited the `opensrf_core.xml` file accordingly. Please
213 refer back to the OpenSRF README and edit the Evergreen version of the
214 `opensrf_core.xml` file using the same Jabber users and domains as you used
215 while installing and testing OpenSRF.
216
217 `eg_db_config.pl`, described in the following section, sets the database
218 connection information in `opensrf.xml` for you.
219
220 Creating the Evergreen database:
221 --------------------------------
222
223 By default, the `Makefile.install` prerequisite installer does not install
224 the PostgreSQL 9.0 database server required by every Evergreen system;
225 for production use, most libraries install the PostgreSQL database server on a
226 dedicated machine. You can install the packages required by Debian, Ubuntu, or
227 Fedora on the machine of your choice using the following commands:
228
229 .(Debian / Ubuntu) Installing PostgreSQL 9.0 server packages
230 [source, bash]
231 ------------------------------------------------------------------------------
232 make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_90
233 ------------------------------------------------------------------------------
234
235 .(Fedora 15) Installing PostgreSQL 9.0 server packages
236 [source, bash]
237 ------------------------------------------------------------------------------
238 make -f Open-ILS/src/extras/Makefile.install install_fedora_pgsql_server
239 ------------------------------------------------------------------------------
240
241 For a standalone PostgreSQL server, install the following Perl modules as the
242 root user:
243
244 .(Debian / Ubuntu) Installing additional Perl modules on a standalone PostgreSQL 9.0 server
245 [source, bash]
246 ------------------------------------------------------------------------------
247 aptitude install gcc libxml-libxml-perl libxml-libxslt-perl
248 cpan Business::ISBN
249 cpan JSON::XS
250 cpan Library::CallNumber::LC
251 cpan MARC::Record
252 cpan MARC::File::XML
253 cpan UUID::Tiny
254 ------------------------------------------------------------------------------
255
256 .(Fedora 15) Installing additional Perl modules on a standalone PostgreSQL 9.0 server
257 [source, bash]
258 ------------------------------------------------------------------------------
259 yum install gcc perl-XML-LibXML perl-XML-LibXSLT perl-Business-ISBN
260 cpan JSON::XS
261 cpan Library::CallNumber::LC
262 cpan MARC::Record
263 cpan MARC::File::XML
264 cpan UUID::Tiny
265 ------------------------------------------------------------------------------
266
267 You need to create a PostgreSQL superuser to create and access the database.
268 Issue the following command as the `postgres` user to create a new PostgreSQL
269 superuser named `evergreen`. When prompted, enter the new user's password:
270
271 [source, bash]
272 ------------------------------------------------------------------------------
273 createuser -s -P evergreen
274 ------------------------------------------------------------------------------
275
276 Once you have created the Evergreen superuser, you also need to create the
277 database and schema, and configure your configuration files to point at the
278 database server. Issue the following command as root from inside the Evergreen
279 source directory, replacing <user>, <password>, <hostname>, <port>, and <dbname>
280 with the appropriate values for your PostgreSQL database (where <user> and
281 <password> are for the PostgreSQL superuser you just created), and replace
282 <admin-user> and <admin-pass> with the values you want for the default
283 Evergreen administrator account:
284
285 [source, bash]
286 ------------------------------------------------------------------------------
287 perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
288        --service all --create-database --create-schema --create-offline \
289        --user <user> --password <password> --hostname <hostname> --port <port> \
290        --database <dbname> --admin-user <admin-user> --admin-pass <admin-pass>
291 ------------------------------------------------------------------------------
292
293 This creates the database and schema and configures all of the services in
294 your `/openils/conf/opensrf.xml` configuration file to point to that database.
295 It also creates the configuration files required by the Evergreen cgi-bin
296 administration scripts, and sets the user name and password for the default
297 Evergreen administrator account to your requested values.
298
299 Creating the database on a remote server
300 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
301 In a production instance of Evergreen, your PostgreSQL server should be
302 installed on a dedicated server. To create the database in that case, you
303 can either:
304
305   *  Install the PostgreSQL contrib modules on the machine on which you
306      are installing the Evergreen code, and use the --create-database
307      option from that machine, or
308   *  Copy the `Open-ILS/src/sql/Pg/create-database.sql` script to your
309      PostgreSQL server and invoke it with:
310 +
311 [source, bash]
312 ------------------------------------------------------------------------------
313 psql -vdb_name=<dbname> -vcontrib_dir=`pg_config --sharedir`/contrib
314 ------------------------------------------------------------------------------
315
316 Then you can issue the `eg_db_config.pl` command as above _without_ the
317 `--create-database` argument to create your schema and configure your
318 configuration files.
319
320 Developer instructions:
321 -----------------------
322
323 Developers working directly with the source code from the Git
324 repository must also install some extra packages and perform
325 one more step before they can proceed with the `./configure` step.
326
327 Install the following packages:
328
329   * autoconf
330   * automake
331   * libtool
332
333 Run the following command in the source directory to generate the configure
334 script and Makefiles:
335
336 [source, bash]
337 ------------------------------------------------------------------------------
338 ./autogen.sh
339 ------------------------------------------------------------------------------
340
341 After running `make install`, developers also need to install the Dojo Toolkit
342 set of JavaScript libraries. The appropriate version of Dojo is included
343 in Evergreen release tarballs; developers should install the Dojo 1.3.3
344 version of Dojo as follows:
345
346 [source, bash]
347 ------------------------------------------------------------------------------
348 wget http://download.dojotoolkit.org/release-1.3.3/dojo-release-1.3.3.tar.gz
349 tar -C /openils/var/web/js -xzf dojo-release-1.3.3.tar.gz
350 cp -r /openils/var/web/js/dojo-release-1.3.3/* /openils/var/web/js/dojo/.
351 ------------------------------------------------------------------------------
352
353 Starting Evergreen
354 ------------------
355 1. As the root user, start the `memcached` and `ejabberd` services (if they aren't already running):
356 +
357 [source, bash]
358 ------------------------------------------------------------------------------
359 /etc/init.d/ejabberd start
360 /etc/init.d/memcached start
361 ------------------------------------------------------------------------------
362 +
363 2. As the opensrf user, start Evergreen. The `-l` flag in the following command
364 is only necessary if you want to force Evergreen to treat the hostname as
365 `localhost`; if you configured `opensrf.xml` using the real hostname
366 of your machine as returned by `perl -ENet::Domain 'print
367 Net::Domain::hostfqdn() . "\n";'`, you should not use the `-l` flag.
368 +
369 [source, bash]
370 ------------------------------------------------------------------------------
371 osrf_ctl.sh -l -a start_all</code>
372 ------------------------------------------------------------------------------
373 +
374   ** If you receive the error message `bash: osrf_ctl.sh: command not found`,
375      then your environment variable `PATH` does not include the `/openils/bin`
376      directory; this should have been set in the opensrf user's `.bashrc`
377      configuration file. To manually set the `PATH` variable, edit the
378      configuration file `~/.bashrc` as the opensrf user and add the following
379      line:
380 +
381 [source, bash]
382 ------------------------------------------------------------------------------
383 export PATH=$PATH:/openils/bin
384 ------------------------------------------------------------------------------
385 +
386 3. As the `opensrf` user, generate the Web files needed by the staff client
387    and catalogue and update the organization unit proximity (you need to do
388    this the first time you start Evergreen, and after that each time you
389    change the library hierarchy in `config.cgi`):
390 +
391 [source, bash]
392 ------------------------------------------------------------------------------
393 autogen.sh -u
394 ------------------------------------------------------------------------------
395 +
396 4. As the `root` user, restart the Apache Web server:
397 +
398 [source, bash]
399 ------------------------------------------------------------------------------
400 /etc/init.d/apache2 restart
401 ------------------------------------------------------------------------------
402 +
403 If the Apache Web server was running when you started the OpenSRF services, you
404 might not be able to successfully log in to the OPAC or staff client until the
405 Apache Web server is restarted.
406
407 Testing connections to Evergreen
408 --------------------------------
409
410 Once you have installed and started Evergreen, test your connection to
411 Evergreen via `srfsh`. Start `srfsh` and try to log onto the Evergreen server
412 using the administrator user name and password that you set using the
413 `eg_db_config.pl` command:
414
415 [source, bash]
416 ------------------------------------------------------------------------------
417 /openils/bin/srfsh
418 srfsh% login <admin-user> <admin-pass>
419 ------------------------------------------------------------------------------
420
421 You should see a result like:
422
423     Received Data: "250bf1518c7527a03249858687714376"
424     ------------------------------------
425     Request Completed Successfully
426     Request Time in seconds: 0.045286
427     ------------------------------------
428
429     Received Data: {
430        "ilsevent":0,
431        "textcode":"SUCCESS",
432        "desc":" ",
433        "pid":21616,
434        "stacktrace":"oils_auth.c:304",
435        "payload":{
436           "authtoken":"e5f9827cc0f93b503a1cc66bee6bdd1a",
437           "authtime":420
438        }
439
440     }
441
442     ------------------------------------
443     Request Completed Successfully
444     Request Time in seconds: 1.336568
445     ------------------------------------
446
447 If this does not work, it's time to do some troubleshooting.
448
449   * As the opensrf user, run the `settings-tester.pl` script to see if it
450     finds any system configuration problems. The script is found at
451     `Open-ILS/src/support-scripts/settings-tester.pl` in the Evergreen source
452     tree.
453   * Follow the steps in the http://evergreen-ils.org/dokuwiki/doku.php?id=troubleshooting:checking_for_errors[troubleshooting guide].
454   * If you have faithfully followed the entire set of installation steps
455     listed here, you are probably extremely close to a working system.
456     Gather your configuration files and log files and contact the
457     http://open-ils.org/listserv.php[Evergreen development mailing list]
458     for assistance before making any drastic changes to your system
459     configuration.
460
461 Getting help:
462 -------------
463
464 Need help installing or using Evergreen? Join the mailing lists at
465 http://evergreen-ils.org/listserv.php or contact us on the Freenode
466 IRC network on the #evergreen channel.