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