Update the README to include database installation instructions
[working/Evergreen.git] / 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.