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.