README

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