initial merge/overlay profile editor ui
[working/Evergreen.git] / README
1 README for Evergreen 1.6
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.1 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", "ubuntu-hardy",
19 "ubuntu-intrepid", "ubuntu-karmic", "centos", "rhel", or "gentoo"
20 for <osname> below:
21
22 make -f Open-ILS/src/extras/Makefile.install <osname>
23
24 Note: "centos", "rhel", and "gentoo" are less tested than the debian
25 and ubuntu options.  Your patches and suggestions for improvement are
26 welcome!
27
28 Configuration and compilation instructions:
29 ==========================================
30
31 For the time being, we are still installing everything in the /openils/
32 directory. Issue the following commands to configure and build Evergreen:
33
34 ./configure --prefix=/openils --sysconfdir=/openils/conf
35 make
36
37 Installation instructions:
38 =========================
39
40 Once you have configured and compiled Evergreen, issue the following
41 command as the root user to install Evergreen:
42
43 make STAFF_CLIENT_BUILD_ID=rel_1_6_0_0 install
44
45 This will install Evergreen, including example configuration files in
46 /openils/conf/ that you can use as templates for your own configuration files.
47 The STAFF_CLIENT_BUILD_ID variable stamps the server-side and client-side files
48 for the staff client to ensure that they match.
49
50 Install Dojo Toolkit:
51 ====================
52
53 Evergreen uses the Dojo Toolkit to support its Web and staff client interfaces.
54
55 Download the Dojo Toolkit (Dojo + Dijit + DojoX) from
56 http://dojotoolkit.org/downloads
57
58 Issue the following commands as the root user to fetch, extract, and copy the
59 files into the correct directory, adjusting the version number to match the
60 version of the Dojo Toolkit that you downloaded:
61
62 wget http://download.dojotoolkit.org/release-1.3.2/dojo-release-1.3.2.tar.gz
63 tar -C /openils/var/web/js -xzf dojo-release-1.3.2.tar.gz
64 cp -r /openils/var/web/js/dojo-release-1.3.2/* /openils/var/web/js/dojo/.
65
66 Change ownership of the Evergreen files:
67 =======================================
68
69 All files in the /openils/ directory and subdirectories must be owned by the
70 "opensrf" user. Issue the following command as the root user to change the
71 ownership on the files:
72
73 chown -R opensrf:opensrf /openils
74
75 Configure the Apache Web server:
76 ===============================
77
78 Use the example configuration files in Open-ILS/examples/apache/ to configure
79 your Web server for the Evergreen catalog, staff client, Web services, and
80 administration interfaces.
81
82 Configure OpenSRF for the Evergreen application:
83 ===============================================
84
85 There are a number of example OpenSRF configuration files in /openils/conf/ that
86 you can use as a template for your Evergreen installation.
87
88 cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml
89 cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml
90
91 When you installed OpenSRF, you will have created four Jabber users on two
92 separate domains and edited the opensrf_core.xml file accordingly. Please
93 refer back to the OpenSRF README and edit the Evergreen version of the
94 opensrf_core.xml file using the same Jabber users and domains as you used
95 while installing and testing OpenSRF.
96
97 eg_db_config.pl, described in the following section, will set the database
98 connection information in opensrf.xml for you.
99
100 Creating the Evergreen database:
101 ===============================
102
103 PostgreSQL 8.2 or 8.3 will be installed on your system by the Makefile.install
104 prerequisite installer if packages are available for your distribution, or
105 you will have to compile PostgreSQL 8.2 or 8.3 from source and install it (which
106 is beyond the scope of this document).
107
108 Once the PostgreSQL database server has been installed, you will need to
109 create the database and add the appropriate languages and extensions to
110 support Evergreen. Issue the following commands as the "postgres" user to set
111 up a database called "evergreen". Note that the location of the PostgreSQL
112 "contrib" packages may vary depending on your distribution. In the following
113 commands, we assume that you are working with PostgreSQL 8.3 on a Debian-based
114 system:
115
116 createdb -E UNICODE evergreen
117 createlang plperl evergreen
118 createlang plperlu evergreen
119 createlang plpgsql evergreen
120 psql -f /usr/share/postgresql/8.3/contrib/tablefunc.sql -d evergreen
121 psql -f /usr/share/postgresql/8.3/contrib/tsearch2.sql -d evergreen
122 psql -f /usr/share/postgresql/8.3/contrib/pgxml.sql -d evergreen
123
124 Once you have created the Evergreen database, you need to create a PostgreSQL
125 user to access the database. Issue the following command as the "postgres"
126 user to create a new PostgreSQL user named "evergreen". When prompted, enter
127 the new user's password and answer "yes" to make the new role a superuser:
128
129 createuser -P evergreen
130
131 Once you have created the Evergreen database, you also need to create the
132 database schema and configure your configuration files to point at the
133 database server. Issue the following command as root from inside the Evergreen
134 source directory, replacing <user>, <password>, <hostname>, <port>, and <dbname>
135 with the appropriate values for your PostgreSQL database:
136
137 perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
138        --service all --create-schema --create-bootstrap --create-offline \
139        --user <user> --password <password> --hostname <hostname> --port <port> \
140        --database <dbname>
141
142 This will create the database schema and configure all of the services in
143 your /openils/conf/opensrf.xml configuration file to point to that database.
144 It also creates the configuration files required by the Evergreen cgi-bin
145 administration scripts.
146
147 Getting help:
148 ============
149
150 Need help installing or using Evergreen? Join the mailing lists at
151 http://evergreen-ils.org/listserv.php or contact us on the Freenode
152 IRC network on the #evergreen channel.