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