README

   1 README for Evergreen trunk
   2
   3 Installing prerequisites:
   4 ========================
   5 Evergreen has a number of prerequisite packages that must be installed
   6 before you can successfully configure, compile, and install Evergreen.
   7
   8 1. Begin by installing the most recent version of OpenSRF (1.6.2 or later).
   9 You can download OpenSRF releases from
  10 http://evergreen-ils.org/downloads
  11
  12 2. On Debian, it's necessary to install Postgres 9 from backports.
  13
  14 On Squeeze, add the following line to /etc/apt/sources.list
  15
  16 deb http://www.backports.org/debian squeeze-backports main contrib
  17
  18 For Lenny, use lenny-backports instead.
  19
  20 Then run 'apt-get update'
  21
  22 3. On Debian and Ubuntu, the easiest way to install the rest of the
  23 prerequisites for Evergreen is to use the Makefile.install prerequisite
  24 installer.
  25
  26 Issue the following commands as the root user to install prerequisites
  27 using the Makefile.install prerequisite installer, substituting
  28 "debian-etch", "debian-lenny", "fedora-14", "ubuntu-hardy", "ubuntu-lucid",
  29 "centos", or "rhel" for <osname> below:
  30
  31 make -f Open-ILS/src/extras/Makefile.install <osname>
  32
  33 Note: "centos" and "rhel" are less tested than the debian, fedora,
  34 and ubuntu options.  Your patches and suggestions for improvement are
  35 welcome!
  36
  37 Configuration and compilation instructions:
  38 ==========================================
  39
  40 For the time being, we are still installing everything in the /openils/
  41 directory. If you are working with a version of Evergreen taken directly
  42 from the Subversion repository, rather than a packaged version of Evergreen,
  43 first see "Developer instructions" below.
  44
  45 Otherwise, issue the following commands to configure and build Evergreen:
  46
  47 ./configure --prefix=/openils --sysconfdir=/openils/conf
  48 make
  49
  50 Installation instructions:
  51 =========================
  52
  53 Once you have configured and compiled Evergreen, issue the following
  54 command as the root user to install Evergreen:
  55
  56 make STAFF_CLIENT_STAMP_ID=rel_trunk install
  57
  58 This will install Evergreen, including example configuration files in
  59 /openils/conf/ that you can use as templates for your own configuration files.
  60 The STAFF_CLIENT_STAMP_ID variable stamps the server-side and client-side files
  61 for the staff client to ensure that they match.
  62
  63 Install Dojo Toolkit:
  64 ====================
  65
  66 Evergreen uses the Dojo Toolkit to support its Web and staff client interfaces.
  67
  68 Download the Dojo Toolkit (Dojo + Dijit + DojoX) from
  69 http://dojotoolkit.org/downloads
  70
  71 Issue the following commands as the root user to fetch, extract, and copy the
  72 files into the correct directory, adjusting the version number to match the
  73 version of the Dojo Toolkit that you downloaded:
  74
  75 wget http://download.dojotoolkit.org/release-1.3.3/dojo-release-1.3.3.tar.gz
  76 tar -C /openils/var/web/js -xzf dojo-release-1.3.3.tar.gz
  77 cp -r /openils/var/web/js/dojo-release-1.3.3/* /openils/var/web/js/dojo/.
  78
  79 Create the oils_web.xml configuration file:
  80 ==========================================
  81 Many administration interfaces, such as acquisitions, bookings, and various
  82 configuration screens, depend on the correct configuration of HTML templates.
  83 Copying the sample configuration file into place should work in most cases:
  84
  85 cp /openils/conf/oils_web.xml.example /openils/conf/oils_web.xml
  86
  87 Change ownership of the Evergreen files:
  88 =======================================
  89
  90 All files in the /openils/ directory and subdirectories must be owned by the
  91 "opensrf" user. Issue the following command as the root user to change the
  92 ownership on the files:
  93
  94 chown -R opensrf:opensrf /openils
  95
  96 Configure the Apache Web server:
  97 ===============================
  98
  99 Use the example configuration files in Open-ILS/examples/apache/ to configure
 100 your Web server for the Evergreen catalog, staff client, Web services, and
 101 administration interfaces.
 102
 103 Configure OpenSRF for the Evergreen application:
 104 ===============================================
 105
 106 There are a number of example OpenSRF configuration files in /openils/conf/ that
 107 you can use as a template for your Evergreen installation.
 108
 109 cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml
 110 cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml
 111
 112 When you installed OpenSRF, you will have created four Jabber users on two
 113 separate domains and edited the opensrf_core.xml file accordingly. Please
 114 refer back to the OpenSRF README and edit the Evergreen version of the
 115 opensrf_core.xml file using the same Jabber users and domains as you used
 116 while installing and testing OpenSRF.
 117
 118 eg_db_config.pl, described in the following section, will set the database
 119 connection information in opensrf.xml for you.
 120
 121 Creating the Evergreen database:
 122 ===============================
 123
 124 PostgreSQL 9.0 will be installed on your system by the Makefile.install
 125 prerequisite installer if packages are available for your distribution, or
 126 you will have to compile PostgreSQL 9.0 from source and install it (which
 127 is beyond the scope of this document).
 128
 129 Once the PostgreSQL database server has been installed, you will need to
 130 create the database and add the appropriate languages and extensions to
 131 support Evergreen. Issue the following commands as the "postgres" user to set
 132 up a database called "evergreen". Note that the location of the PostgreSQL
 133 "contrib" packages may vary depending on your distribution. In the following
 134 commands, we assume that you are working with PostgreSQL 9.0 on a Debian-based
 135 system:
 136
 137 createdb --template template0 --lc-ctype=C --lc-collate=C --encoding UNICODE evergreen
 138 createlang plperl evergreen
 139 createlang plperlu evergreen
 140 createlang plpgsql evergreen
 141 psql -f /usr/share/postgresql/9.0/contrib/tablefunc.sql -d evergreen
 142 psql -f /usr/share/postgresql/9.0/contrib/tsearch2.sql -d evergreen
 143 psql -f /usr/share/postgresql/9.0/contrib/pgxml.sql -d evergreen
 144 psql -f /usr/share/postgresql/9.0/contrib/hstore.sql -d evergreen
 145
 146 Once you have created the Evergreen database, you need to create a PostgreSQL
 147 user to access the database. Issue the following command as the "postgres"
 148 user to create a new PostgreSQL user named "evergreen". When prompted, enter
 149 the new user's password and answer "yes" to make the new role a superuser:
 150
 151 createuser -P evergreen
 152
 153 Once you have created the Evergreen database, you also need to create the
 154 database schema and configure your configuration files to point at the
 155 database server. Issue the following command as root from inside the Evergreen
 156 source directory, replacing <user>, <password>, <hostname>, <port>, and <dbname>
 157 with the appropriate values for your PostgreSQL database, and <admin-user> and
 158 <admin-pass> with the values you want for the default Evergreen administrator
 159 account:
 160
 161 perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
 162        --service all --create-schema --create-offline \
 163        --user <user> --password <password> --hostname <hostname> --port <port> \
 164        --database <dbname> --admin-user <admin-user> --admin-pass <admin-pass>
 165
 166 This will create the database schema and configure all of the services in
 167 your /openils/conf/opensrf.xml configuration file to point to that database.
 168 It also creates the configuration files required by the Evergreen cgi-bin
 169 administration scripts, and set the user name and password for the default
 170 Evergreen administrator account to your requested values.
 171
 172 Developer instructions:
 173 ======================
 174
 175 Developers working directly with the source code from the Subversion
 176 repository will also need to install some extra packages and perform
 177 one more step before they can proceed with the "./configure" step.
 178
 179 Install the following packages:
 180   * autoconf
 181   * automake
 182   * libtool
 183
 184 Run the following command in the source directory to generate the configure
 185 script and Makefiles:
 186
 187 ./autogen.sh
 188
 189 After running 'make install', developers also need to install the Dojo Toolkit
 190 set of JavaScript libraries. The appropriate version of Dojo is included
 191 in Evergreen release tarballs; developers should install the Dojo 1.3.3
 192 version of Dojo as follows:
 193
 194 wget http://download.dojotoolkit.org/release-1.3.3/dojo-release-1.3.3.tar.gz
 195 tar xzf dojo-release-1.3.3.tar.gz
 196 cp -r dojo-release-1.3.3/* /openils/var/web/js/dojo/.
 197
 198 Getting help:
 199 ============
 200
 201 Need help installing or using Evergreen? Join the mailing lists at
 202 http://evergreen-ils.org/listserv.php or contact us on the Freenode
 203 IRC network on the #evergreen channel.