README

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