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