README cleanup
[working/Evergreen.git] / README
1 README for Evergreen 1.4
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.0 or later).
9 You can download OpenSRF 1.0.1 from
10 http://evergreen-ils.org/downloads/OpenSRF-1.0.1.tar.gz
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 "debian"
18 or "ubuntu" for <osname> below:
19
20 make -f Open-ILS/src/extras/Makefile.install <osname>
21
22 Note: You may also be able to use "centos" to install the Evergreen 
23 prerequisites for CentOS 5 and RHEL 5, or "gentoo" for Gentoo - but
24 these are less tested distributions. Your patches and suggestions for
25 improvement are welcome!
26
27 Configuration and compilation instructions:
28 ==========================================
29
30 For the time being, we are still installing everything in the /openils/
31 directory (with the exception of the Perl modules, which are installed
32 into system directories). Issue the following commands to configure and
33 build Evergreen:
34
35 ./configure --prefix=/openils --sysconfdir=/openils/conf
36 make
37
38 Installation instructions:
39 =========================
40
41 Once you have configured and compiled Evergreen, issue the following
42 command as the root user to install Evergreen:
43
44 make STAFF_CLIENT_BUILD_ID=rel_1_4_0_0 install
45
46 This will install Evergreen, including example configuration files in
47 /openils/conf/ that you can use as templates for your own configuration files.
48 The STAFF_CLIENT_BUILD_ID variable stamps the server-side and client-side files
49 for the staff client to ensure that they match.
50
51 Change ownership of the Evergreen files:
52 =======================================
53
54 All files in the /openils/ directory and subdirectories must be owned by the
55 "opensrf" user. Issue the following command as the root user to change the
56 ownership on the files:
57
58 chown -R opensrf:opensrf /openils
59
60 Configure the Apache Web server:
61 ===============================
62
63 Use the example configuration files in Open-ILS/examples/apache/ to configure
64 your Web server for the Evergreen catalog, staff client, Web services, and
65 administration interfaces.
66
67 Configure OpenSRF for the Evergreen application:
68 ===============================================
69
70 There are a number of example OpenSRF configuration files in /openils/conf/ that
71 you can use as a template for your Evergreen installation.
72
73 cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml
74 cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml
75
76 Note that eg_db_config.pl will set the database connection information in
77 opensrf.xml for you.
78
79 Creating the Evergreen database:
80 ===============================
81
82 PostgreSQL 8.2 will be installed on your system by the Makefile.install
83 prerequisite installer, but you will need to create the database and add the
84 appropriate languages and extensions to support Evergreen. Issue the following
85 commands as the "postgres" user to set up a database called "evergreen". Note
86 that the location of the PostgreSQL "contrib" packages may vary depending on
87 your distribution:
88
89 createdb -E UNICODE evergreen
90 createlang plperl evergreen
91 createlang plperlu evergreen
92 createlang plpgsql evergreen
93 psql -f /usr/share/postgresql/8.2/contrib/tablefunc.sql
94 psql -f /usr/share/postgresql/8.2/contrib/tsearch2.sql
95 psql -f /usr/share/postgresql/8.2/contrib/pgxml.sql
96
97 Once you have created the Evergreen database, you need to create a PostgreSQL
98 user to access the database. Issue the following command as the "postgres"
99 user to create a new PostgreSQL user named "evergreen". When prompted, enter
100 the new user's password and answer "yes" to make the new role a superuser:
101
102 createuser -P evergreen
103
104 Once you have created the Evergreen database, you also need to create the
105 database schema and configure your configuration files to point at the
106 database server. Issue the following command as root from inside the Evergreen
107 source directory, replacing <user>, <password>, <hostname>, <port>, and <dbname>
108 with the appropriate values for your PostgreSQL database:
109
110 perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
111        --service all --create-schema --create-bootstrap --user <user> \
112        --password <password> --hostname <hostname> --port <port> \
113        --database <dbname>
114
115 This will create the database schema and configure all of the services in
116 your /openils/conf/opensrf.xml configuration file to point to that database.
117 It also creates the configuration file required by the Evergreen cgi-bin
118 administration scripts.
119
120 Getting help:
121 ============
122
123 Need help installing or using Evergreen? Join the mailing lists at
124 http://evergreen-ils.org/listserv.php or contact us on the Freenode
125 IRC network on the #evergreen channel.