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