README

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