Support Fedora 15 as a target in Makefile.install
[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 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://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 STAFF_CLIENT_STAMP_ID=rel_trunk install
78 ------------------------------------------------------------------------------
79
80 This will install Evergreen, including example configuration files in
81 `/openils/conf/` that you can use as templates for your own configuration files.
82 The `STAFF_CLIENT_STAMP_ID` variable stamps the server-side and client-side files
83 for the staff client to ensure that they match.
84
85 Create the oils_web.xml configuration file:
86 -------------------------------------------
87 Many administration interfaces, such as acquisitions, bookings, and various
88 configuration screens, depend on the correct configuration of HTML templates.
89 Copying the sample configuration file into place should work in most cases:
90
91 [source, bash]
92 ------------------------------------------------------------------------------
93 cp /openils/conf/oils_web.xml.example /openils/conf/oils_web.xml
94 ------------------------------------------------------------------------------
95
96 Change ownership of the Evergreen files:
97 ----------------------------------------
98
99 All files in the `/openils/` directory and subdirectories must be owned by the
100 `opensrf` user. Issue the following command as the root user to change the
101 ownership on the files:
102
103 [source, bash]
104 ------------------------------------------------------------------------------
105 chown -R opensrf:opensrf /openils
106 ------------------------------------------------------------------------------
107
108 Configure the Apache Web server:
109 --------------------------------
110
111 Use the example configuration files in `Open-ILS/examples/apache/` to configure
112 your Web server for the Evergreen catalog, staff client, Web services, and
113 administration interfaces.
114
115 Configure OpenSRF for the Evergreen application:
116 ------------------------------------------------
117
118 There are a number of example OpenSRF configuration files in `/openils/conf/`
119 that you can use as a template for your Evergreen installation.
120
121 [source, bash]
122 ------------------------------------------------------------------------------
123 cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml
124 cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml
125 ------------------------------------------------------------------------------
126
127 When you installed OpenSRF, you will have created four Jabber users on two
128 separate domains and edited the `opensrf_core.xml` file accordingly. Please
129 refer back to the OpenSRF README and edit the Evergreen version of the
130 `opensrf_core.xml` file using the same Jabber users and domains as you used
131 while installing and testing OpenSRF.
132
133 `eg_db_config.pl`, described in the following section, will set the database
134 connection information in `opensrf.xml` for you.
135
136 Creating the Evergreen database:
137 --------------------------------
138
139 PostgreSQL 9.0 will be installed on your system by the `Makefile.install`
140 prerequisite installer if packages are available for your distribution, or
141 you will have to compile PostgreSQL 9.0 from source and install it (which
142 is beyond the scope of this document).
143
144 Once the PostgreSQL database server has been installed, you will need to
145 create the database and add the appropriate languages and extensions to
146 support Evergreen. Issue the following commands as the `postgres` user to set
147 up a database called `evergreen`. Note that the location of the PostgreSQL
148 `contrib` packages may vary depending on your distribution. In the following
149 commands, we assume that you are working with PostgreSQL 9.0 on a Debian-based
150 system:
151
152 [source, bash]
153 ------------------------------------------------------------------------------
154 createdb --template template0 --lc-ctype=C --lc-collate=C --encoding UNICODE evergreen
155 createlang plperl evergreen
156 createlang plperlu evergreen
157 psql -f /usr/share/postgresql/9.0/contrib/tablefunc.sql -d evergreen
158 psql -f /usr/share/postgresql/9.0/contrib/tsearch2.sql -d evergreen
159 psql -f /usr/share/postgresql/9.0/contrib/pgxml.sql -d evergreen
160 psql -f /usr/share/postgresql/9.0/contrib/hstore.sql -d evergreen
161 ------------------------------------------------------------------------------
162
163 Once you have created the Evergreen database, you need to create a PostgreSQL
164 user to access the database. Issue the following command as the `postgres`
165 user to create a new PostgreSQL user named `evergreen`. When prompted, enter
166 the new user's password and answer `yes` to make the new role a superuser:
167
168 [source, bash]
169 ------------------------------------------------------------------------------
170 createuser -P evergreen
171 ------------------------------------------------------------------------------
172
173 Once you have created the Evergreen database, you also need to create the
174 database schema and configure your configuration files to point at the
175 database server. Issue the following command as root from inside the Evergreen
176 source directory, replacing <user>, <password>, <hostname>, <port>, and <dbname>
177 with the appropriate values for your PostgreSQL database, and <admin-user> and
178 <admin-pass> with the values you want for the default Evergreen administrator
179 account:
180
181 [source, bash]
182 ------------------------------------------------------------------------------
183 perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
184        --service all --create-schema --create-offline \
185        --user <user> --password <password> --hostname <hostname> --port <port> \
186        --database <dbname> --admin-user <admin-user> --admin-pass <admin-pass>
187 ------------------------------------------------------------------------------
188
189 This will create the database schema and configure all of the services in
190 your `/openils/conf/opensrf.xml` configuration file to point to that database.
191 It also creates the configuration files required by the Evergreen cgi-bin
192 administration scripts, and set the user name and password for the default
193 Evergreen administrator account to your requested values.
194
195 Developer instructions:
196 -----------------------
197
198 Developers working directly with the source code from the Git
199 repository will also need to install some extra packages and perform
200 one more step before they can proceed with the `./configure` step.
201
202 Install the following packages:
203   * autoconf
204   * automake
205   * libtool
206
207 Run the following command in the source directory to generate the configure
208 script and Makefiles:
209
210 [source, bash]
211 ------------------------------------------------------------------------------
212 ./autogen.sh
213 ------------------------------------------------------------------------------
214
215 After running `make install`, developers also need to install the Dojo Toolkit
216 set of JavaScript libraries. The appropriate version of Dojo is included
217 in Evergreen release tarballs; developers should install the Dojo 1.3.3
218 version of Dojo as follows:
219
220 [source, bash]
221 ------------------------------------------------------------------------------
222 wget http://download.dojotoolkit.org/release-1.3.3/dojo-release-1.3.3.tar.gz
223 tar -C /openils/var/web/js -xzf dojo-release-1.3.3.tar.gz
224 cp -r /openils/var/web/js/dojo-release-1.3.3/* /openils/var/web/js/dojo/.
225 ------------------------------------------------------------------------------
226
227 Getting help:
228 -------------
229
230 Need help installing or using Evergreen? Join the mailing lists at
231 http://evergreen-ils.org/listserv.php or contact us on the Freenode
232 IRC network on the #evergreen channel.