admin/server_install.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <chapter xml:id="server_install" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="EN"\r
   3     xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">\r
   4 \r
   5 \r
   6 <info>\r
   7     <title>Installing the Evergreen Server</title>\r
   8 </info>\r
   9 <simplesect id="_preamble_referenced_user_accounts">\r
  10 <title>Preamble: referenced user accounts</title>\r
  11 <simpara>In subsequent simplesects, we will refer to a number of different accounts, as\r
  12 follows:</simpara>\r
  13 <itemizedlist>\r
  14 <listitem>\r
  15 <simpara>\r
  16 Linux user accounts:\r
  17 </simpara>\r
  18 <itemizedlist>\r
  19 <listitem>\r
  20 <simpara>\r
  21 The <emphasis role="strong">user</emphasis> Linux account is the account that you use to log onto the\r
  22        Linux system as a regular user.\r
  23 </simpara>\r
  24 </listitem>\r
  25 <listitem>\r
  26 <simpara>\r
  27 The <emphasis role="strong">root</emphasis> Linux account is an account that has system administrator\r
  28        privileges. On Debian and Fedora you can switch to this account from\r
  29        your <emphasis role="strong">user</emphasis> account by issuing the <literal>su -</literal> command and entering the\r
  30        password for the <emphasis role="strong">root</emphasis> account when prompted. On Ubuntu you can switch\r
  31        to this account from your <emphasis role="strong">user</emphasis> account using the <literal>sudo su -</literal> command\r
  32        and entering the password for your <emphasis role="strong">user</emphasis> account when prompted.\r
  33 </simpara>\r
  34 </listitem>\r
  35 <listitem>\r
  36 <simpara>\r
  37 The <emphasis role="strong">opensrf</emphasis> Linux account is an account that you create when installing\r
  38        OpenSRF. You can switch to this account from the <emphasis role="strong">root</emphasis> account by\r
  39        issuing the <literal>su - opensrf</literal> command.\r
  40 </simpara>\r
  41 </listitem>\r
  42 <listitem>\r
  43 <simpara>\r
  44 The <emphasis role="strong">postgres</emphasis> Linux account is created automatically when you install\r
  45        the PostgreSQL database server. You can switch to this account from the\r
  46        <emphasis role="strong">root</emphasis> account by issuing the <literal>su - postgres</literal> command.\r
  47 </simpara>\r
  48 </listitem>\r
  49 </itemizedlist>\r
  50 </listitem>\r
  51 <listitem>\r
  52 <simpara>\r
  53 PostgreSQL user accounts:\r
  54 </simpara>\r
  55 <itemizedlist>\r
  56 <listitem>\r
  57 <simpara>\r
  58 The <emphasis role="strong">evergreen</emphasis> PostgreSQL account is a superuser account that you will\r
  59        create to connect to the PostgreSQL database server.\r
  60 </simpara>\r
  61 </listitem>\r
  62 </itemizedlist>\r
  63 </listitem>\r
  64 <listitem>\r
  65 <simpara>\r
  66 Evergreen administrator account:\r
  67 </simpara>\r
  68 <itemizedlist>\r
  69 <listitem>\r
  70 <simpara>\r
  71 The <emphasis role="strong">egadmin</emphasis> Evergreen account is an administrator account for\r
  72        Evergreen that you will use to test connectivity and configure your\r
  73        Evergreen instance.\r
  74 </simpara>\r
  75 </listitem>\r
  76 </itemizedlist>\r
  77 </listitem>\r
  78 </itemizedlist>\r
  79 </simplesect>\r
  80 <simplesect id="_preamble_getting_an_evergreen_official_release_tarball">\r
  81 <title>Preamble: Getting an Evergreen official release tarball</title>\r
  82 <simpara>To download and extract the source for the current release of Evergreen, issue\r
  83 the following commands as the <emphasis role="strong">user</emphasis> Linux account:</simpara>\r
  84 <programlisting language="bash" linenumbering="unnumbered">wget -c http://evergreen-ils.org/downloads/Evergreen-ILS-2.1.1.tar.gz\r
  85 tar xzf Evergreen-ILS-2.1.1.tar.gz</programlisting>\r
  86 </simplesect>\r
  87 <simplesect id="_preamble_developer_instructions">\r
  88 <title>Preamble: Developer instructions</title>\r
  89 <note><simpara>Skip this section if you are using an official release tarball downloaded\r
  90 from <ulink url="http://evergreen-ils.org/downloads">http://evergreen-ils.org/downloads</ulink></simpara></note>\r
  91 <simpara>Developers working directly with the source code from the Git repository,\r
  92 rather than an official release tarball, must install some extra packages\r
  93 and perform one step before they can proceed with the <literal>./configure</literal> step.</simpara>\r
  94 <simpara>As the <emphasis role="strong">root</emphasis> Linux account, install the following packages:</simpara>\r
  95 <itemizedlist>\r
  96 <listitem>\r
  97 <simpara>\r
  98 autoconf\r
  99 </simpara>\r
 100 </listitem>\r
 101 <listitem>\r
 102 <simpara>\r
 103 automake\r
 104 </simpara>\r
 105 </listitem>\r
 106 <listitem>\r
 107 <simpara>\r
 108 libtool\r
 109 </simpara>\r
 110 </listitem>\r
 111 </itemizedlist>\r
 112 <simpara>As the <emphasis role="strong">user</emphasis> Linux account, issue the following command in the Evergreen\r
 113 source directory to generate the configure script and Makefiles:</simpara>\r
 114 <programlisting language="bash" linenumbering="unnumbered">./autogen.sh</programlisting>\r
 115 <simpara>After running <literal>make install</literal>, developers also need to install the Dojo Toolkit\r
 116 set of JavaScript libraries. The appropriate version of Dojo is included\r
 117 in Evergreen release tarballs. Developers should install the Dojo 1.3.3\r
 118 version of Dojo by issuing the following commands as the <emphasis role="strong">opensrf</emphasis> Linux\r
 119 account:</simpara>\r
 120 <programlisting language="bash" linenumbering="unnumbered">wget http://download.dojotoolkit.org/release-1.3.3/dojo-release-1.3.3.tar.gz\r
 121 tar -C /openils/var/web/js -xzf dojo-release-1.3.3.tar.gz\r
 122 cp -r /openils/var/web/js/dojo-release-1.3.3/* /openils/var/web/js/dojo/.</programlisting>\r
 123 </simplesect>\r
 124 <simplesect id="_installing_prerequisites">\r
 125 <title>Installing prerequisites</title>\r
 126 <simpara>Evergreen has a number of prerequisite packages that must be installed\r
 127 before you can successfully configure, compile, and install Evergreen.</simpara>\r
 128 <orderedlist numeration="arabic">\r
 129 <listitem>\r
 130 <simpara>\r
 131 Begin by installing the most recent version of OpenSRF (2.0 or later).\r
 132    You can download OpenSRF releases from <ulink url="http://evergreen-ils.org/opensrf.php">http://evergreen-ils.org/opensrf.php</ulink>\r
 133 </simpara>\r
 134 </listitem>\r
 135 <listitem>\r
 136 <simpara>\r
 137 On many distributions, it is necessary to install PostgreSQL 9 from external\r
 138    repositories.\r
 139 </simpara>\r
 140 <itemizedlist>\r
 141 <listitem>\r
 142 <simpara>\r
 143 On Debian Squeeze, open <literal>/etc/apt/sources.list</literal> in a text editor as the\r
 144     <emphasis role="strong">root</emphasis> Linux account and add the following line:\r
 145 </simpara>\r
 146 <programlisting language="bash" linenumbering="unnumbered">deb http://backports.debian.org/debian-backports squeeze-backports main contrib</programlisting>\r
 147 </listitem>\r
 148 <listitem>\r
 149 <simpara>\r
 150 On Ubuntu Lucid, you can use a PPA (personal package archive), which are\r
 151     package sources hosted on Launchpad. The one most commonly used by Evergreen\r
 152     Community members is maintained by Martin Pitt, who also maintains the\r
 153     official PostgreSQL packages for Ubuntu. As the <emphasis role="strong">root</emphasis> Linux account, issue\r
 154     the following commands to add the PPA source:\r
 155 </simpara>\r
 156 <programlisting language="bash" linenumbering="unnumbered">apt-get install python-software-properties\r
 157 add-apt-repository ppa:pitti/postgresql</programlisting>\r
 158 </listitem>\r
 159 <listitem>\r
 160 <simpara>\r
 161 Fedora 15 comes with PostgreSQL 9, so no additional steps are required.\r
 162 </simpara>\r
 163 </listitem>\r
 164 </itemizedlist>\r
 165 </listitem>\r
 166 <listitem>\r
 167 <simpara>\r
 168 On Debian and Ubuntu, run <literal>aptitude update</literal> as the <emphasis role="strong">root</emphasis> Linux account to\r
 169    retrieve the new packages from the backports repository.\r
 170 </simpara>\r
 171 </listitem>\r
 172 <listitem>\r
 173 <simpara>\r
 174 Issue the following commands as the <emphasis role="strong">root</emphasis> Linux account to install\r
 175    prerequisites using the <literal>Makefile.install</literal> prerequisite installer,\r
 176    substituting <literal>debian-squeeze</literal>, <literal>fedora15</literal>, <literal>ubuntu-lucid</literal>, <literal>centos</literal>, or\r
 177    <literal>rhel</literal> for &lt;osname&gt; below:\r
 178 </simpara>\r
 179 <programlisting language="bash" linenumbering="unnumbered">make -f Open-ILS/src/extras/Makefile.install &lt;osname&gt;</programlisting>\r
 180 <note><simpara><literal>centos</literal> and <literal>rhel</literal> are less tested than the <literal>debian</literal>, <literal>fedora</literal>,\r
 181 and <literal>ubuntu</literal> options.  Your patches and suggestions for improvement are\r
 182 welcome!</simpara></note>\r
 183 </listitem>\r
 184 <listitem>\r
 185 <simpara>\r
 186 Add the libdbi-libdbd libraries to the system dynamic library path by\r
 187    issuing the following commands as the <emphasis role="strong">root</emphasis> Linux account:\r
 188 </simpara>\r
 189 <formalpara><title>Debian / Ubuntu</title><para>\r
 190 <programlisting language="bash" linenumbering="unnumbered">echo "/usr/local/lib/dbd" &gt; /etc/ld.so.conf.d/eg.conf\r
 191 ldconfig</programlisting>\r
 192 </para></formalpara>\r
 193 <formalpara><title>Fedora</title><para>\r
 194 <programlisting language="bash" linenumbering="unnumbered">echo "/usr/lib64/dbd" &gt; /etc/ld.so.conf.d/eg.conf\r
 195 ldconfig</programlisting>\r
 196 </para></formalpara>\r
 197 </listitem>\r
 198 </orderedlist>\r
 199 </simplesect>\r
 200 <simplesect id="_configuration_and_compilation_instructions">\r
 201 <title>Configuration and compilation instructions</title>\r
 202 <simpara>For the time being, we are still installing everything in the <literal>/openils/</literal>\r
 203 directory. From the Evergreen source directory, issue the following commands as\r
 204 the <emphasis role="strong">user</emphasis> Linux account to configure and build Evergreen:</simpara>\r
 205 <programlisting language="bash" linenumbering="unnumbered">./configure --prefix=/openils --sysconfdir=/openils/conf\r
 206 make</programlisting>\r
 207 </simplesect>\r
 208 <simplesect id="_installation_instructions">\r
 209 <title>Installation instructions</title>\r
 210 <orderedlist numeration="arabic">\r
 211 <listitem>\r
 212 <simpara>\r
 213 Once you have configured and compiled Evergreen, issue the following\r
 214    command as the <emphasis role="strong">root</emphasis> Linux account to install Evergreen, build the server\r
 215    portion of the staff client, and copy example configuration files to\r
 216    <literal>/openils/conf</literal>.\r
 217    Change the value of the <literal>STAFF_CLIENT_STAMP_ID</literal> variable to match the version\r
 218    of the staff client that you will use to connect to the Evergreen server.\r
 219 </simpara>\r
 220 <programlisting language="bash" linenumbering="unnumbered">make STAFF_CLIENT_STAMP_ID=rel_2_1_1 install</programlisting>\r
 221 </listitem>\r
 222 <listitem>\r
 223 <simpara>\r
 224 The server portion of the staff client expects <literal>http://hostname/xul/server</literal>\r
 225    to resolve. Issue the following commands as the <emphasis role="strong">root</emphasis> Linux account to\r
 226    create a symbolic link pointing to the <literal>server</literal> subdirectory of the server\r
 227    portion of the staff client that we just built using the staff client ID\r
 228    <emphasis>rel_name</emphasis>:\r
 229 </simpara>\r
 230 <programlisting language="bash" linenumbering="unnumbered">cd /openils/var/web/xul\r
 231 ln -sf rel_name/server server</programlisting>\r
 232 </listitem>\r
 233 </orderedlist>\r
 234 </simplesect>\r
 235 <simplesect id="_change_ownership_of_the_evergreen_files">\r
 236 <title>Change ownership of the Evergreen files</title>\r
 237 <simpara>All files in the <literal>/openils/</literal> directory and subdirectories must be owned by the\r
 238 <literal>opensrf</literal> user. Issue the following command as the <emphasis role="strong">root</emphasis> Linux account to\r
 239 change the ownership on the files:</simpara>\r
 240 <programlisting language="bash" linenumbering="unnumbered">chown -R opensrf:opensrf /openils</programlisting>\r
 241 </simplesect>\r
 242 <simplesect id="_create_the_oils_web_xml_configuration_file">\r
 243 <title>Create the oils_web.xml configuration file</title>\r
 244 <simpara>Many administration interfaces, such as acquisitions, bookings, and various\r
 245 configuration screens, depend on the correct configuration of HTML templates.\r
 246 Copying the sample configuration file into place should work in most cases:</simpara>\r
 247 <programlisting language="bash" linenumbering="unnumbered">cp /openils/conf/oils_web.xml.example /openils/conf/oils_web.xml</programlisting>\r
 248 </simplesect>\r
 249 <simplesect id="_configure_the_apache_web_server">\r
 250 <title>Configure the Apache Web server</title>\r
 251 <orderedlist numeration="arabic">\r
 252 <listitem>\r
 253 <simpara>\r
 254 Use the example configuration files in <literal>Open-ILS/examples/apache/</literal> to\r
 255 configure your Web server for the Evergreen catalog, staff client, Web\r
 256 services, and administration interfaces. Issue the following commands as the\r
 257 <emphasis role="strong">root</emphasis> Linux account:\r
 258 </simpara>\r
 259 <formalpara><title>Debian and Ubuntu</title><para>\r
 260 <programlisting language="bash" linenumbering="unnumbered">cp Open-ILS/examples/apache/eg.conf       /etc/apache2/sites-available/\r
 261 cp Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/\r
 262 cp Open-ILS/examples/apache/startup.pl    /etc/apache2/\r
 263 # Now set up SSL\r
 264 mkdir /etc/apache2/ssl\r
 265 cd /etc/apache2/ssl</programlisting>\r
 266 </para></formalpara>\r
 267 <formalpara><title>Fedora</title><para>\r
 268 <programlisting language="bash" linenumbering="unnumbered">cp Open-ILS/examples/apache/eg.conf       /etc/httpd/sites-available/\r
 269 cp Open-ILS/examples/apache/eg_vhost.conf /etc/httpd/\r
 270 cp Open-ILS/examples/apache/startup.pl    /etc/httpd/\r
 271 # Now set up SSL\r
 272 mkdir /etc/httpd/ssl\r
 273 cd /etc/httpd/ssl</programlisting>\r
 274 </para></formalpara>\r
 275 </listitem>\r
 276 <listitem>\r
 277 <simpara>\r
 278 The <literal>openssl</literal> command cuts a new SSL key for your Apache server. For a\r
 279 production server, you should purchase a signed SSL certificate, but you can\r
 280 just use a self-signed certificate and accept the warnings in the staff client\r
 281 and browser during testing and development. Create an SSL key for the Apache\r
 282 server by issuing the following command as the <emphasis role="strong">root</emphasis> Linux account:\r
 283 </simpara>\r
 284 <programlisting language="bash" linenumbering="unnumbered">openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key</programlisting>\r
 285 </listitem>\r
 286 <listitem>\r
 287 <simpara>\r
 288 As the <emphasis role="strong">root</emphasis> Linux account, edit the <literal>eg.conf</literal> file that you copied into\r
 289 place.\r
 290 </simpara>\r
 291 <orderedlist numeration="loweralpha">\r
 292 <listitem>\r
 293 <simpara>\r
 294 Replace <literal>Allow from 10.0.0.0/8</literal> with <literal>Allow from all</literal> (to enable\r
 295      access to the offline upload / execute interface from any workstation on\r
 296      any network - note that you must secure this for a production instance)\r
 297 </simpara>\r
 298 </listitem>\r
 299 </orderedlist>\r
 300 </listitem>\r
 301 <listitem>\r
 302 <simpara>\r
 303 Change the user for the Apache server.\r
 304 </simpara>\r
 305 <itemizedlist>\r
 306 <listitem>\r
 307 <simpara>\r
 308 (Debian and Ubuntu): As the <emphasis role="strong">root</emphasis> Linux account, edit\r
 309     <literal>/etc/apache2/envvars</literal>.  Change <literal>export APACHE_RUN_USER=www-data</literal> to\r
 310     <literal>export APACHE_RUN_USER=opensrf</literal>.\r
 311 </simpara>\r
 312 </listitem>\r
 313 <listitem>\r
 314 <simpara>\r
 315 (Fedora): As the <emphasis role="strong">root</emphasis> Linux account , edit <literal>/etc/httpd/conf/httpd.conf</literal>.\r
 316     Change <literal>User apache</literal> to <literal>User opensrf</literal>.\r
 317 </simpara>\r
 318 </listitem>\r
 319 </itemizedlist>\r
 320 </listitem>\r
 321 <listitem>\r
 322 <simpara>\r
 323 Configure Apache with performance settings appropriate for Evergreen:\r
 324 </simpara>\r
 325 <itemizedlist>\r
 326 <listitem>\r
 327 <simpara>\r
 328 (Debian and Ubuntu): As the <emphasis role="strong">root</emphasis> Linux account, edit\r
 329     <literal>/etc/apache2/apache2.conf</literal>:\r
 330 </simpara>\r
 331 </listitem>\r
 332 <listitem>\r
 333 <simpara>\r
 334 (Fedora): As the <emphasis role="strong">root</emphasis> Linux account, edit <literal>/etc/httpd/conf/httpd.conf</literal>:\r
 335 </simpara>\r
 336 <orderedlist numeration="loweralpha">\r
 337 <listitem>\r
 338 <simpara>\r
 339 Change <literal>KeepAliveTimeout</literal> to <literal>1</literal>. Higher values reduce the chance of\r
 340        a request timing out unexpectedly, but increase the risk of using up\r
 341        all available Apache child processes.\r
 342 </simpara>\r
 343 </listitem>\r
 344 <listitem>\r
 345 <simpara>\r
 346 <emphasis>Optional</emphasis>: Change <literal>MaxKeepAliveRequests</literal> to <literal>100</literal>\r
 347 </simpara>\r
 348 </listitem>\r
 349 <listitem>\r
 350 <simpara>\r
 351 Update the prefork configuration simplesect to suit your environment. The\r
 352        following settings apply to a busy system:\r
 353 </simpara>\r
 354 <programlisting language="bash" linenumbering="unnumbered">&lt;IfModule mpm_prefork_module&gt;\r
 355    StartServers           20\r
 356    MinSpareServers         5\r
 357    MaxSpareServers        15\r
 358    MaxClients            150\r
 359    MaxRequestsPerChild 10000\r
 360 &lt;/IfModule&gt;</programlisting>\r
 361 </listitem>\r
 362 </orderedlist>\r
 363 </listitem>\r
 364 </itemizedlist>\r
 365 </listitem>\r
 366 <listitem>\r
 367 <simpara>\r
 368 (Debian and Ubuntu): As the <emphasis role="strong">root</emphasis> Linux account, enable the Evergreen site:\r
 369 </simpara>\r
 370 <programlisting language="bash" linenumbering="unnumbered">a2dissite default  # OPTIONAL: disable the default site (the "It Works" page)\r
 371 a2ensite eg.conf</programlisting>\r
 372 </listitem>\r
 373 </orderedlist>\r
 374 </simplesect>\r
 375 <simplesect id="_configure_opensrf_for_the_evergreen_application">\r
 376 <title>Configure OpenSRF for the Evergreen application</title>\r
 377 <simpara>There are a number of example OpenSRF configuration files in <literal>/openils/conf/</literal>\r
 378 that you can use as a template for your Evergreen installation. Issue the\r
 379 following commands as the <emphasis role="strong">opensrf</emphasis> Linux account:</simpara>\r
 380 <programlisting language="bash" linenumbering="unnumbered">cp -b /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml\r
 381 cp -b /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml</programlisting>\r
 382 <simpara>When you installed OpenSRF, you created four Jabber users on two\r
 383 separate domains and edited the <literal>opensrf_core.xml</literal> file accordingly. Please\r
 384 refer back to the OpenSRF README and, as the <emphasis role="strong">opensrf</emphasis> Linux account, edit the\r
 385 Evergreen version of the <literal>opensrf_core.xml</literal> file using the same Jabber users\r
 386 and domains as you used while installing and testing OpenSRF.</simpara>\r
 387 <note><simpara>The <literal>-b</literal> flag tells the <literal>cp</literal> command to create a backup version of the\r
 388 destination file. The backup version of the destination file has a tilde (<literal>~</literal>)\r
 389 appended to the file name, so if you have forgotten the Jabber users and\r
 390 domains, you can retrieve the settings from the backup version of the files.</simpara></note>\r
 391 <simpara><literal>eg_db_config.pl</literal>, described in the following simplesect, sets the database\r
 392 connection information in <literal>opensrf.xml</literal> for you.</simpara>\r
 393 </simplesect>\r
 394 <simplesect id="_creating_the_evergreen_database">\r
 395 <title>Creating the Evergreen database</title>\r
 396 <simpara>By default, the <literal>Makefile.install</literal> prerequisite installer does not install\r
 397 the PostgreSQL 9.0 database server required by every Evergreen system;\r
 398 for production use, most libraries install the PostgreSQL database server on a\r
 399 dedicated machine. You can install the packages required by Debian, Ubuntu, or\r
 400 Fedora on the machine of your choice using the following commands as the <emphasis role="strong">root</emphasis>\r
 401 Linux account:</simpara>\r
 402 <formalpara><title>(Debian / Ubuntu) Installing PostgreSQL 9.0 server packages</title><para>\r
 403 <programlisting language="bash" linenumbering="unnumbered">make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_90</programlisting>\r
 404 </para></formalpara>\r
 405 <formalpara><title>(Fedora 15) Installing PostgreSQL 9.0 server packages</title><para>\r
 406 <programlisting language="bash" linenumbering="unnumbered">make -f Open-ILS/src/extras/Makefile.install install_fedora_pgsql_server</programlisting>\r
 407 </para></formalpara>\r
 408 <simpara>For a standalone PostgreSQL server, install the following Perl modules as the\r
 409 <emphasis role="strong">root</emphasis> Linux account:</simpara>\r
 410 <formalpara><title>(Debian / Ubuntu) Installing additional Perl modules on a standalone PostgreSQL 9.0 server</title><para>\r
 411 <programlisting language="bash" linenumbering="unnumbered">aptitude install gcc libxml-libxml-perl libxml-libxslt-perl\r
 412 cpan Business::ISBN\r
 413 cpan JSON::XS\r
 414 cpan Library::CallNumber::LC\r
 415 cpan MARC::Record\r
 416 cpan MARC::File::XML\r
 417 cpan UUID::Tiny</programlisting>\r
 418 </para></formalpara>\r
 419 <formalpara><title>(Fedora 15) Installing additional Perl modules on a standalone PostgreSQL 9.0 server</title><para>\r
 420 <programlisting language="bash" linenumbering="unnumbered">yum install gcc perl-XML-LibXML perl-XML-LibXSLT perl-Business-ISBN\r
 421 cpan JSON::XS\r
 422 cpan Library::CallNumber::LC\r
 423 cpan MARC::Record\r
 424 cpan MARC::File::XML\r
 425 cpan UUID::Tiny</programlisting>\r
 426 </para></formalpara>\r
 427 <simpara>You need to create a PostgreSQL superuser to create and access the database.\r
 428 Issue the following command as the <emphasis role="strong">postgres</emphasis> Linux account to create a new\r
 429 PostgreSQL superuser named <literal>evergreen</literal>. When prompted, enter the new user&#8217;s\r
 430 password:</simpara>\r
 431 <programlisting language="bash" linenumbering="unnumbered">createuser -s -P evergreen</programlisting>\r
 432 <simpara>Once you have created the <emphasis role="strong">evergreen</emphasis> PostgreSQL account, you also need to\r
 433 create the database and schema, and configure your configuration files to point\r
 434 at the database server. Issue the following command as the <emphasis role="strong">root</emphasis> Linux account\r
 435 from inside the Evergreen source directory, replacing &lt;user&gt;, &lt;password&gt;,\r
 436 &lt;hostname&gt;, &lt;port&gt;, and &lt;dbname&gt; with the appropriate values for your\r
 437 PostgreSQL database (where &lt;user&gt; and &lt;password&gt; are for the <emphasis role="strong">evergreen</emphasis>\r
 438 PostgreSQL account you just created), and replace &lt;admin-user&gt; and &lt;admin-pass&gt;\r
 439 with the values you want for the <emphasis role="strong">egadmin</emphasis> Evergreen administrator account:</simpara>\r
 440 <programlisting language="bash" linenumbering="unnumbered">perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \\r
 441        --service all --create-database --create-schema --create-offline \\r
 442        --user &lt;user&gt; --password &lt;password&gt; --hostname &lt;hostname&gt; --port &lt;port&gt; \\r
 443        --database &lt;dbname&gt; --admin-user &lt;admin-user&gt; --admin-pass &lt;admin-pass&gt;</programlisting>\r
 444 <simpara>This creates the database and schema and configures all of the services in\r
 445 your <literal>/openils/conf/opensrf.xml</literal> configuration file to point to that database.\r
 446 It also creates the configuration files required by the Evergreen <literal>cgi-bin</literal>\r
 447 administration scripts, and sets the user name and password for the <emphasis role="strong">egadmin</emphasis>\r
 448 Evergreen administrator account to your requested values.</simpara>\r
 449 <simplesect id="_creating_the_database_on_a_remote_server">\r
 450 <title>Creating the database on a remote server</title>\r
 451 <simpara>In a production instance of Evergreen, your PostgreSQL server should be\r
 452 installed on a dedicated server. To create the database in that case, you\r
 453 can either:</simpara>\r
 454 <itemizedlist>\r
 455 <listitem>\r
 456 <simpara>\r
 457 Install the PostgreSQL contrib modules on the machine on which you\r
 458      are installing the Evergreen code, and use the --create-database\r
 459      option from that machine, or\r
 460 </simpara>\r
 461 </listitem>\r
 462 <listitem>\r
 463 <simpara>\r
 464 Copy the <literal>Open-ILS/src/sql/Pg/create_database.sql</literal> script to your\r
 465      PostgreSQL server and invoke it as the <emphasis role="strong">postgres</emphasis> Linux account:\r
 466 </simpara>\r
 467 <programlisting language="bash" linenumbering="unnumbered">psql -vdb_name=&lt;dbname&gt; -vcontrib_dir=`pg_config --sharedir`/contrib -f create_database.sql</programlisting>\r
 468 </listitem>\r
 469 </itemizedlist>\r
 470 <simpara>Then you can issue the <literal>eg_db_config.pl</literal> command as above <emphasis>without</emphasis> the\r
 471 <literal>--create-database</literal> argument to create your schema and configure your\r
 472 configuration files.</simpara>\r
 473 </simplesect>\r
 474 </simplesect>\r
 475 <simplesect id="_starting_evergreen">\r
 476 <title>Starting Evergreen</title>\r
 477 <orderedlist numeration="arabic">\r
 478 <listitem>\r
 479 <simpara>\r
 480 As the <emphasis role="strong">root</emphasis> Linux account, start the <literal>memcached</literal> and <literal>ejabberd</literal> services\r
 481 (if they aren&#8217;t already running):\r
 482 </simpara>\r
 483 <programlisting language="bash" linenumbering="unnumbered">/etc/init.d/ejabberd start\r
 484 /etc/init.d/memcached start</programlisting>\r
 485 </listitem>\r
 486 <listitem>\r
 487 <simpara>\r
 488 As the <emphasis role="strong">opensrf</emphasis> Linux account, start Evergreen. The <literal>-l</literal> flag in the\r
 489 following command is only necessary if you want to force Evergreen to treat the\r
 490 hostname as <literal>localhost</literal>; if you configured <literal>opensrf.xml</literal> using the real\r
 491 hostname of your machine as returned by <literal>perl -ENet::Domain 'print\r
 492 Net::Domain::hostfqdn() . "\n";'</literal>, you should not use the <literal>-l</literal> flag.\r
 493 </simpara>\r
 494 <programlisting language="bash" linenumbering="unnumbered">osrf_ctl.sh -l -a start_all</programlisting>\r
 495 <itemizedlist>\r
 496 <listitem>\r
 497 <simpara>\r
 498 If you receive the error message <literal>bash: osrf_ctl.sh: command not found</literal>,\r
 499      then your environment variable <literal>PATH</literal> does not include the <literal>/openils/bin</literal>\r
 500      directory; this should have been set in the <emphasis role="strong">opensrf</emphasis> Linux account&#8217;s\r
 501      <literal>.bashrc</literal> configuration file. To manually set the <literal>PATH</literal> variable, edit the\r
 502      configuration file <literal>~/.bashrc</literal> as the <emphasis role="strong">opensrf</emphasis> Linux account and add the\r
 503      following line:\r
 504 </simpara>\r
 505 <programlisting language="bash" linenumbering="unnumbered">export PATH=$PATH:/openils/bin</programlisting>\r
 506 </listitem>\r
 507 </itemizedlist>\r
 508 </listitem>\r
 509 <listitem>\r
 510 <simpara>\r
 511 As the <emphasis role="strong">opensrf</emphasis> Linux account, generate the Web files needed by the staff\r
 512    client and catalogue and update the organization unit proximity (you need to do\r
 513    this the first time you start Evergreen, and after that each time you change\r
 514    the library hierarchy in <literal>config.cgi</literal>):\r
 515 </simpara>\r
 516 <programlisting language="bash" linenumbering="unnumbered">autogen.sh -u</programlisting>\r
 517 </listitem>\r
 518 <listitem>\r
 519 <simpara>\r
 520 As the <emphasis role="strong">root</emphasis> Linux account, restart the Apache Web server:\r
 521 </simpara>\r
 522 <programlisting language="bash" linenumbering="unnumbered">/etc/init.d/apache2 restart</programlisting>\r
 523 <simpara>If the Apache Web server was running when you started the OpenSRF services, you\r
 524 might not be able to successfully log in to the OPAC or staff client until the\r
 525 Apache Web server is restarted.</simpara>\r
 526 </listitem>\r
 527 </orderedlist>\r
 528 </simplesect>\r
 529 <simplesect id="_testing_connections_to_evergreen">\r
 530 <title>Testing connections to Evergreen</title>\r
 531 <simpara>Once you have installed and started Evergreen, test your connection to\r
 532 Evergreen via <literal>srfsh</literal>. As the <emphasis role="strong">opensrf</emphasis> Linux account, issue the following\r
 533 commands to start <literal>srfsh</literal> and try to log onto the Evergreen server using the\r
 534 <emphasis role="strong">egadmin</emphasis> Evergreen administrator user name and password that you set using the\r
 535 <literal>eg_db_config.pl</literal> command:</simpara>\r
 536 <programlisting language="bash" linenumbering="unnumbered">/openils/bin/srfsh\r
 537 srfsh% login &lt;admin-user&gt; &lt;admin-pass&gt;</programlisting>\r
 538 <simpara>You should see a result like:</simpara>\r
 539 <literallayout class="monospaced">Received Data: "250bf1518c7527a03249858687714376"\r
 540 ------------------------------------\r
 541 Request Completed Successfully\r
 542 Request Time in seconds: 0.045286\r
 543 ------------------------------------</literallayout>\r
 544 <literallayout class="monospaced">Received Data: {\r
 545    "ilsevent":0,\r
 546    "textcode":"SUCCESS",\r
 547    "desc":" ",\r
 548    "pid":21616,\r
 549    "stacktrace":"oils_auth.c:304",\r
 550    "payload":{\r
 551       "authtoken":"e5f9827cc0f93b503a1cc66bee6bdd1a",\r
 552       "authtime":420\r
 553    }</literallayout>\r
 554 <literallayout class="monospaced">}</literallayout>\r
 555 <literallayout class="monospaced">------------------------------------\r
 556 Request Completed Successfully\r
 557 Request Time in seconds: 1.336568\r
 558 ------------------------------------</literallayout>\r
 559 <simpara>If this does not work, it&#8217;s time to do some troubleshooting.</simpara>\r
 560 <itemizedlist>\r
 561 <listitem>\r
 562 <simpara>\r
 563 As the <emphasis role="strong">opensrf</emphasis> Linux acccount, run the <literal>settings-tester.pl</literal> script to see\r
 564     if it finds any system configuration problems. The script is found at\r
 565     <literal>Open-ILS/src/support-scripts/settings-tester.pl</literal> in the Evergreen source\r
 566     tree.\r
 567 </simpara>\r
 568 </listitem>\r
 569 <listitem>\r
 570 <simpara>\r
 571 Follow the steps in the <ulink url="http://evergreen-ils.org/dokuwiki/doku.php?id=troubleshooting:checking_for_errors">troubleshooting guide</ulink>.\r
 572 </simpara>\r
 573 </listitem>\r
 574 <listitem>\r
 575 <simpara>\r
 576 If you have faithfully followed the entire set of installation steps\r
 577     listed here, you are probably extremely close to a working system.\r
 578     Gather your configuration files and log files and contact the\r
 579     <ulink url="http://open-ils.org/listserv.php">Evergreen development mailing list</ulink>\r
 580     for assistance before making any drastic changes to your system\r
 581     configuration.\r
 582 </simpara>\r
 583 </listitem>\r
 584 </itemizedlist>\r
 585 </simplesect>\r
 586 <simplesect id="_getting_help">\r
 587 <title>Getting help</title>\r
 588 <simpara>Need help installing or using Evergreen? Join the mailing lists at\r
 589 <ulink url="http://evergreen-ils.org/listserv.php">http://evergreen-ils.org/listserv.php</ulink> or contact us on the Freenode\r
 590 IRC network on the #evergreen channel.</simpara>\r
 591 </simplesect>\r
 592 </chapter>\r