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