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