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 Configuration and compilation instructions:
  54 -------------------------------------------
  55
  56 For the time being, we are still installing everything in the `/openils/`
  57 directory. If you are working with a version of Evergreen taken directly
  58 from the Git repository, rather than a packaged version of Evergreen,
  59 first see `Developer instructions` below.
  60
  61 Otherwise, issue the following commands to configure and build Evergreen:
  62
  63 [source, bash]
  64 ------------------------------------------------------------------------------
  65 ./configure --prefix=/openils --sysconfdir=/openils/conf
  66 make
  67 ------------------------------------------------------------------------------
  68
  69 Installation instructions:
  70 --------------------------
  71
  72 Once you have configured and compiled Evergreen, issue the following
  73 command as the root user to install Evergreen:
  74
  75 [source, bash]
  76 ------------------------------------------------------------------------------
  77 make install
  78 ------------------------------------------------------------------------------
  79
  80 This command installs Evergreen, including example configuration files in
  81 `/openils/conf/` that you can use as templates for your own configuration files.
  82
  83 Create the oils_web.xml configuration file:
  84 -------------------------------------------
  85 Many administration interfaces, such as acquisitions, bookings, and various
  86 configuration screens, depend on the correct configuration of HTML templates.
  87 Copying the sample configuration file into place should work in most cases:
  88
  89 [source, bash]
  90 ------------------------------------------------------------------------------
  91 cp /openils/conf/oils_web.xml.example /openils/conf/oils_web.xml
  92 ------------------------------------------------------------------------------
  93
  94 Change ownership of the Evergreen files:
  95 ----------------------------------------
  96
  97 All files in the `/openils/` directory and subdirectories must be owned by the
  98 `opensrf` user. Issue the following command as the root user to change the
  99 ownership on the files:
 100
 101 [source, bash]
 102 ------------------------------------------------------------------------------
 103 chown -R opensrf:opensrf /openils
 104 ------------------------------------------------------------------------------
 105
 106 Configure the Apache Web server:
 107 --------------------------------
 108
 109 1. Use the example configuration files in `Open-ILS/examples/apache/` to configure
 110 your Web server for the Evergreen catalog, staff client, Web services, and
 111 administration interfaces.
 112 +
 113 .Debian and Ubuntu
 114 [source,bash]
 115 ------------------------------------------------------------------------------
 116 cp Open-ILS/examples/apache/eg.conf       /etc/apache2/sites-available/
 117 cp Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/
 118 cp Open-ILS/examples/apache/startup.pl    /etc/apache2/
 119 # Now set up SSL
 120 mkdir /etc/apache2/ssl
 121 cd /etc/apache2/ssl
 122 ------------------------------------------------------------------------------
 123 +
 124 .Fedora
 125 [source,bash]
 126 ------------------------------------------------------------------------------
 127 cp Open-ILS/examples/apache/eg.conf       /etc/httpd/sites-available/
 128 cp Open-ILS/examples/apache/eg_vhost.conf /etc/httpd/
 129 cp Open-ILS/examples/apache/startup.pl    /etc/httpd/
 130 # Now set up SSL
 131 mkdir /etc/httpd/ssl
 132 cd /etc/httpd/ssl
 133 ------------------------------------------------------------------------------
 134 +
 135 2. Create an SSL key for the Apache server:
 136 +
 137 [source,bash]
 138 ------------------------------------------------------------------------------
 139 openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key
 140 ------------------------------------------------------------------------------
 141 +
 142 The `openssl` command cuts a new SSL key for your Apache server. For a
 143 production server, you should purchase a signed SSL certificate, but you can
 144 just use a self-signed certificate and accept the warnings in the staff client
 145 and browser during testing and development
 146 +
 147 3. Edit the `eg.conf` file that you copied into place.
 148   a. Replace `Allow from 10.0.0.0/8` with `Allow from all` (to enable
 149      access to the offline upload / execute interface from any workstation on
 150      any network - note that you must secure this for a production instance)
 151   b. Comment the line `Listen 443` as it conflicts with the same declaration
 152      elsewhere in the Apache configuration files.
 153 4. Change the user for the Apache server.
 154   * (Debian and Ubuntu): As the root user, edit `/etc/apache2/envvars`.
 155     Change `export APACHE_RUN_USER=www-data` to
 156     `export APACHE_RUN_USER=opensrf`.
 157   * (Fedora): As the root user, edit `/etc/httpd/conf/httpd.conf`. Change
 158     `User apache` to `User opensrf`.
 159 5. Configure Apache with performance settings appropriate for Evergreen:
 160   * (Debian and Ubuntu): As the root user, edit `/etc/apache2/apache2.conf`:
 161   * (Fedora): As the root user, edit `/etc/httpd/conf/httpd.conf`:
 162     a. Change `KeepAliveTimeout` to `1`. Higher values reduce the chance of
 163        a request timing out unexpectedly, but increase the risk of using up
 164        all available Apache child processes.
 165     b. 'Optional': Change `MaxKeepAliveRequests` to `100`
 166     c. Update the prefork configuration section to suit your environment. The
 167        following settings apply to a busy system:
 168 +
 169 [source,bash]
 170 ------------------------------------------------------------------------------
 171 <IfModule mpm_prefork_module>
 172    StartServers           20
 173    MinSpareServers         5
 174    MaxSpareServers        15
 175    MaxClients            150
 176    MaxRequestsPerChild 10000
 177 </IfModule>
 178 ------------------------------------------------------------------------------
 179 +
 180 6. (Debian and Ubuntu): As the root user, enable the Evergreen site:
 181 +
 182 [source,bash]
 183 ------------------------------------------------------------------------------
 184 a2dissite default  # OPTIONAL: disable the default site (the "It Works" page)
 185 a2ensite eg.conf
 186 ------------------------------------------------------------------------------
 187
 188 Configure OpenSRF for the Evergreen application:
 189 ------------------------------------------------
 190 There are a number of example OpenSRF configuration files in `/openils/conf/`
 191 that you can use as a template for your Evergreen installation.
 192
 193 [source, bash]
 194 ------------------------------------------------------------------------------
 195 cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml
 196 cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml
 197 ------------------------------------------------------------------------------
 198
 199 When you installed OpenSRF, you will have created four Jabber users on two
 200 separate domains and edited the `opensrf_core.xml` file accordingly. Please
 201 refer back to the OpenSRF README and edit the Evergreen version of the
 202 `opensrf_core.xml` file using the same Jabber users and domains as you used
 203 while installing and testing OpenSRF.
 204
 205 `eg_db_config.pl`, described in the following section, will set the database
 206 connection information in `opensrf.xml` for you.
 207
 208 Creating the Evergreen database:
 209 --------------------------------
 210
 211 By default, the `Makefile.install` prerequisite installer does not install
 212 the PostgreSQL 9.0 database server required by every Evergreen system;
 213 most libraries install the PostgreSQL database server on a dedicated
 214 machine. You can install the packages required by Debian, Ubuntu, or Fedora
 215 using the following commands:
 216
 217 .Installing PostgreSQL 9.0 server packages on Debian and Ubuntu
 218 [source, bash]
 219 ------------------------------------------------------------------------------
 220 make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_90
 221 ------------------------------------------------------------------------------
 222
 223 .Installing PostgreSQL 9.0 server packages on Fedora
 224 [source, bash]
 225 ------------------------------------------------------------------------------
 226 make -f Open-ILS/src/extras/Makefile.install install_fedora_pgsql_server
 227 ------------------------------------------------------------------------------
 228
 229 Once the PostgreSQL database server has been installed, you must
 230 create the database and add the appropriate languages and extensions to
 231 support Evergreen. Issue the following commands as the `postgres` user to set
 232 up a database called `evergreen`. Note that the location of the PostgreSQL
 233 `contrib` packages may vary depending on your distribution. In the following
 234 commands, we assume that you are working with PostgreSQL 9.0 on a Debian-based
 235 system:
 236
 237 [source, bash]
 238 ------------------------------------------------------------------------------
 239 createdb --template template0 --lc-ctype=C --lc-collate=C --encoding UNICODE evergreen
 240 createlang plperl evergreen
 241 createlang plperlu evergreen
 242 psql -f /usr/share/postgresql/9.0/contrib/tablefunc.sql -d evergreen
 243 psql -f /usr/share/postgresql/9.0/contrib/tsearch2.sql -d evergreen
 244 psql -f /usr/share/postgresql/9.0/contrib/pgxml.sql -d evergreen
 245 psql -f /usr/share/postgresql/9.0/contrib/hstore.sql -d evergreen
 246 ------------------------------------------------------------------------------
 247
 248 Once you have created the Evergreen database, you need to create a PostgreSQL
 249 user to access the database. Issue the following command as the `postgres`
 250 user to create a new PostgreSQL user named `evergreen`. When prompted, enter
 251 the new user's password and answer `yes` to make the new role a superuser:
 252
 253 [source, bash]
 254 ------------------------------------------------------------------------------
 255 createuser -P evergreen
 256 ------------------------------------------------------------------------------
 257
 258 Once you have created the Evergreen database, you also need to create the
 259 database schema and configure your configuration files to point at the
 260 database server. Issue the following command as root from inside the Evergreen
 261 source directory, replacing <user>, <password>, <hostname>, <port>, and <dbname>
 262 with the appropriate values for your PostgreSQL database, and <admin-user> and
 263 <admin-pass> with the values you want for the default Evergreen administrator
 264 account:
 265
 266 [source, bash]
 267 ------------------------------------------------------------------------------
 268 perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
 269        --service all --create-schema --create-offline \
 270        --user <user> --password <password> --hostname <hostname> --port <port> \
 271        --database <dbname> --admin-user <admin-user> --admin-pass <admin-pass>
 272 ------------------------------------------------------------------------------
 273
 274 This will create the database schema and configure all of the services in
 275 your `/openils/conf/opensrf.xml` configuration file to point to that database.
 276 It also creates the configuration files required by the Evergreen cgi-bin
 277 administration scripts, and set the user name and password for the default
 278 Evergreen administrator account to your requested values.
 279
 280 Developer instructions:
 281 -----------------------
 282
 283 Developers working directly with the source code from the Git
 284 repository will also need to install some extra packages and perform
 285 one more step before they can proceed with the `./configure` step.
 286
 287 Install the following packages:
 288   * autoconf
 289   * automake
 290   * libtool
 291
 292 Run the following command in the source directory to generate the configure
 293 script and Makefiles:
 294
 295 [source, bash]
 296 ------------------------------------------------------------------------------
 297 ./autogen.sh
 298 ------------------------------------------------------------------------------
 299
 300 After running `make install`, developers also need to install the Dojo Toolkit
 301 set of JavaScript libraries. The appropriate version of Dojo is included
 302 in Evergreen release tarballs; developers should install the Dojo 1.3.3
 303 version of Dojo as follows:
 304
 305 [source, bash]
 306 ------------------------------------------------------------------------------
 307 wget http://download.dojotoolkit.org/release-1.3.3/dojo-release-1.3.3.tar.gz
 308 tar -C /openils/var/web/js -xzf dojo-release-1.3.3.tar.gz
 309 cp -r /openils/var/web/js/dojo-release-1.3.3/* /openils/var/web/js/dojo/.
 310 ------------------------------------------------------------------------------
 311
 312 Getting help:
 313 -------------
 314
 315 Need help installing or using Evergreen? Join the mailing lists at
 316 http://evergreen-ils.org/listserv.php or contact us on the Freenode
 317 IRC network on the #evergreen channel.