docs/installation/server_installation.txt

   1 Installing the Evergreen server
   2 ===============================
   3 :toc:
   4 :numbered:
   5
   6 Preamble: referenced user accounts
   7 ----------------------------------
   8
   9 In subsequent sections, we will refer to a number of different accounts, as
  10 follows:
  11
  12   * Linux user accounts:
  13     ** The *user* Linux account is the account that you use to log onto the
  14        Linux system as a regular user.
  15     ** The *root* Linux account is an account that has system administrator
  16        privileges. On Debian and Fedora you can switch to this account from
  17        your *user* account by issuing the `su -` command and entering the
  18        password for the *root* account when prompted. On Ubuntu you can switch
  19        to this account from your *user* account using the `sudo su -` command
  20        and entering the password for your *user* account when prompted.
  21     ** The *opensrf* Linux account is an account that you create when installing
  22        OpenSRF. You can switch to this account from the *root* account by
  23        issuing the `su - opensrf` command.
  24     ** The *postgres* Linux account is created automatically when you install
  25        the PostgreSQL database server. You can switch to this account from the
  26        *root* account by issuing the `su - postgres` command.
  27   * PostgreSQL user accounts:
  28     ** The *evergreen* PostgreSQL account is a superuser account that you will
  29        create to connect to the PostgreSQL database server.
  30   * Evergreen administrator account:
  31     ** The *egadmin* Evergreen account is an administrator account for
  32        Evergreen that you will use to test connectivity and configure your
  33        Evergreen instance.
  34
  35 Preamble: developer instructions
  36 --------------------------------
  37
  38 [NOTE]
  39 Skip this section if you are using an official release tarball downloaded
  40 from http://evergreen-ils.org/egdownloads
  41
  42 Developers working directly with the source code from the Git repository,
  43 rather than an official release tarball, must perform one step before they
  44 can proceed with the `./configure` step.
  45
  46 As the *user* Linux account, issue the following command in the Evergreen
  47 source directory to generate the configure script and Makefiles:
  48
  49 [source, bash]
  50 ------------------------------------------------------------------------------
  51 autoreconf -i
  52 ------------------------------------------------------------------------------
  53
  54 Installing prerequisites
  55 ------------------------
  56
  57   * **PostgreSQL**: Version 9.3 is recommended. The minimum supported version
  58     is 9.1.
  59   * **Linux**: Evergreen 2.8 has been tested on Debian Jessie (8.0),
  60     Debian Wheezy (7.0), Ubuntu Xenial Xerus (16.04),
  61     Ubuntu Trusty Tahr (14.04), and Fedora.
  62     If you are running an older version of these distributions, you may want
  63     to upgrade before upgrading Evergreen. For instructions on upgrading these
  64     distributions, visit the Debian, Ubuntu or Fedora websites.
  65   * **OpenSRF**: The minimum supported version of OpenSRF is 2.4.0.
  66
  67
  68 Evergreen has a number of prerequisite packages that must be installed
  69 before you can successfully configure, compile, and install Evergreen.
  70
  71 1. Begin by installing the most recent version of OpenSRF (2.4.0 or later).
  72    You can download OpenSRF releases from http://evergreen-ils.org/opensrf-downloads/
  73 2. On some distributions, it is necessary to install PostgreSQL 9.1+ from external
  74    repositories.
  75 +
  76   * Debian (Wheezy and Jessie) and Ubuntu (Trusty and Xenial) comes with
  77     PostgreSQL 9.1+, so no additional steps are required.
  78   * Fedora 19 and 20 come with PostgreSQL 9.2+, so no additional steps are required.
  79 +
  80 3. On Debian and Ubuntu, run `aptitude update` as the *root* Linux account to
  81    retrieve the new packages from the backports repository.
  82 4. Issue the following commands as the *root* Linux account to install
  83    prerequisites using the `Makefile.install` prerequisite installer,
  84    substituting `debian-jessie`, `debian-wheezy`, `fedora`,
  85    `ubuntu-xenial`, or `ubuntu-trusty` for <osname> below:
  86 +
  87 [source, bash]
  88 ------------------------------------------------------------------------------
  89 make -f Open-ILS/src/extras/Makefile.install <osname>
  90 ------------------------------------------------------------------------------
  91 +
  92 5. Add the libdbi-libdbd libraries to the system dynamic library path by
  93    issuing the following commands as the *root* Linux account:
  94 +
  95 [NOTE]
  96 You should skip this step if installing on Ubuntu Trusty, Ubuntu Xenial or Debian Jessie. The Ubuntu
  97 and Debian Jessie targets use libdbd-pgsql from packages.
  98 +
  99 .Debian Wheezy
 100 [source, bash]
 101 ------------------------------------------------------------------------------
 102 echo "/usr/local/lib/dbd" > /etc/ld.so.conf.d/eg.conf
 103 ldconfig
 104 ------------------------------------------------------------------------------
 105 +
 106 .Fedora
 107 [source, bash]
 108 ------------------------------------------------------------------------------
 109 echo "/usr/lib64/dbd" > /etc/ld.so.conf.d/eg.conf
 110 ldconfig
 111 ------------------------------------------------------------------------------
 112
 113 6. OPTIONAL: Developer additions
 114 +
 115 To perform certain developer tasks from a Git source code checkout,
 116 additional packages may be required.  As the *root* Linux account:
 117 +
 118  * To install packages needed for retriving and managing web dependencies,
 119    use the <osname>-developer Makefile.install target.  Currently,
 120    this is only needed for building and installing the (preview) browser
 121    staff client.
 122 +
 123 [source, bash]
 124 ------------------------------------------------------------------------------
 125 make -f Open-ILS/src/extras/Makefile.install <osname>-developer
 126 ------------------------------------------------------------------------------
 127 +
 128  * To install packages required for building Evergreen release bundles, use
 129    the <osname>-packager Makefile.install target.
 130 +
 131 [source, bash]
 132 ------------------------------------------------------------------------------
 133 make -f Open-ILS/src/extras/Makefile.install <osname>-packager
 134 ------------------------------------------------------------------------------
 135
 136 Optional: Extra steps for browser-based staff client
 137 ----------------------------------------------------
 138
 139 [NOTE]
 140 Skip this entire section if you are using an official release tarball downloaded
 141 from http://evergreen-ils.org/downloads
 142
 143 [NOTE]
 144 You make skip the subsection `Install dependencies for browser-based staff client'
 145 if you are installing on either Debian Jessie, Ubuntu Trusty, or Ubuntu Xenial and you have
 146 installed the `Optional: Developer Additions' described above.  You will still
 147 need to do the steps in `Install files for browser-based staff client' below.
 148
 149 Install dependencies for browser-based staff client
 150 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 151
 152 1. Install Node.js.  For more information see also:
 153    https://github.com/joyent/node/wiki/installation[Node.js Installation]
 154 +
 155 [source,sh]
 156 ------------------------------------------------------------------------------
 157 # Go to a temporary directory
 158 cd /tmp
 159
 160 # Clone the code and checkout the necessary version
 161 git clone https://github.com/joyent/node.git
 162 cd node
 163 git checkout -b v0.10.28 v0.10.28
 164
 165 # set -j to the number of CPU cores on the server + 1
 166 ./configure && make -j2 && sudo make install
 167
 168 # update packages
 169 % sudo npm update
 170 ------------------------------------------------------------------------------
 171 +
 172 2. Install Grunt CLI
 173 +
 174 [source,sh]
 175 ------------------------------------------------------------------------------
 176 % sudo npm install -g grunt-cli
 177 ------------------------------------------------------------------------------
 178 +
 179 3. Install Bower
 180 +
 181 [source,sh]
 182 ------------------------------------------------------------------------------
 183 % sudo npm install -g bower
 184 ------------------------------------------------------------------------------
 185
 186 Install files for browser-based staff client
 187 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 188
 189 1. Building, Testing, Minification: The remaining steps all take place within
 190    the staff JS web root:
 191 +
 192 [source,sh]
 193 ------------------------------------------------------------------------------
 194 cd $EVERGREEN_ROOT/Open-ILS/web/js/ui/default/staff/
 195 ------------------------------------------------------------------------------
 196 +
 197 2. Install Project-local Dependencies. npm inspects the 'package.json' file
 198    for dependencies and fetches them from the Node package network.
 199 +
 200 [source,sh]
 201 ------------------------------------------------------------------------------
 202 npm install   # fetch Grunt dependencies
 203 bower install # fetch JS dependencies
 204 ------------------------------------------------------------------------------
 205 +
 206 3. Run the build script.
 207 +
 208 [source,sh]
 209 ------------------------------------------------------------------------------
 210 # build, run tests, concat+minify
 211 grunt all
 212 ------------------------------------------------------------------------------
 213
 214
 215 Configuration and compilation instructions
 216 ------------------------------------------
 217
 218 For the time being, we are still installing everything in the `/openils/`
 219 directory. From the Evergreen source directory, issue the following commands as
 220 the *user* Linux account to configure and build Evergreen:
 221
 222 [source, bash]
 223 ------------------------------------------------------------------------------
 224 PATH=/openils/bin:$PATH ./configure --prefix=/openils --sysconfdir=/openils/conf
 225 make
 226 ------------------------------------------------------------------------------
 227
 228 These instructions assume that you have also installed OpenSRF under `/openils/`.
 229 If not, please adjust PATH as needed so that the Evergreen `configure` script
 230 can find `osrf_config`.
 231
 232 Installation instructions
 233 -------------------------
 234
 235 1. Once you have configured and compiled Evergreen, issue the following
 236    command as the *root* Linux account to install Evergreen, build the server
 237    portion of the staff client, and copy example configuration files to
 238    `/openils/conf`.
 239    Change the value of the `STAFF_CLIENT_STAMP_ID` variable to match the version
 240    of the staff client that you will use to connect to the Evergreen server.
 241 +
 242 [source, bash]
 243 ------------------------------------------------------------------------------
 244 make STAFF_CLIENT_STAMP_ID=rel_name install
 245 ------------------------------------------------------------------------------
 246 +
 247 2. The server portion of the staff client expects `http://hostname/xul/server`
 248    to resolve. Issue the following commands as the *root* Linux account to
 249    create a symbolic link pointing to the `server` subdirectory of the server
 250    portion of the staff client that we just built using the staff client ID
 251    'rel_name':
 252 +
 253 [source, bash]
 254 ------------------------------------------------------------------------------
 255 cd /openils/var/web/xul
 256 ln -sf rel_name/server server
 257 ------------------------------------------------------------------------------
 258
 259 Change ownership of the Evergreen files
 260 ---------------------------------------
 261
 262 All files in the `/openils/` directory and subdirectories must be owned by the
 263 `opensrf` user. Issue the following command as the *root* Linux account to
 264 change the ownership on the files:
 265
 266 [source, bash]
 267 ------------------------------------------------------------------------------
 268 chown -R opensrf:opensrf /openils
 269 ------------------------------------------------------------------------------
 270
 271 Additional Instructions for Developers
 272 --------------------------------------
 273
 274 [NOTE]
 275 Skip this section if you are using an official release tarball downloaded
 276 from http://evergreen-ils.org/egdownloads
 277
 278 Developers working directly with the source code from the Git repository,
 279 rather than an official release tarball, need to install the Dojo Toolkit
 280 set of JavaScript libraries. The appropriate version of Dojo is included in
 281 Evergreen release tarballs. Developers should install the Dojo 1.3.3 version
 282 of Dojo by issuing the following commands as the *opensrf* Linux account:
 283
 284 [source, bash]
 285 ------------------------------------------------------------------------------
 286 wget http://download.dojotoolkit.org/release-1.3.3/dojo-release-1.3.3.tar.gz
 287 tar -C /openils/var/web/js -xzf dojo-release-1.3.3.tar.gz
 288 cp -r /openils/var/web/js/dojo-release-1.3.3/* /openils/var/web/js/dojo/.
 289 ------------------------------------------------------------------------------
 290
 291
 292 Configure the Apache Web server
 293 -------------------------------
 294
 295 . Use the example configuration files in `Open-ILS/examples/apache/` (for
 296 Apache versions below 2.4) or `Open-ILS/examples/apache_24/` (for Apache
 297 versions 2.4 or greater) to configure your Web server for the Evergreen
 298 catalog, staff client, Web services, and administration interfaces. Issue the
 299 following commands as the *root* Linux account:
 300 +
 301 .Debian Wheezy
 302 [source,bash]
 303 ------------------------------------------------------------------------------
 304 cp Open-ILS/examples/apache/eg.conf       /etc/apache2/sites-available/
 305 cp Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/
 306 cp Open-ILS/examples/apache/eg_startup    /etc/apache2/
 307 # Now set up SSL
 308 mkdir /etc/apache2/ssl
 309 cd /etc/apache2/ssl
 310 ------------------------------------------------------------------------------
 311 +
 312 .Ubuntu Trusty, Ubuntu Xenial, and Debian Jessie
 313 [source,bash]
 314 ------------------------------------------------------------------------------------
 315 cp Open-ILS/examples/apache_24/eg_24.conf       /etc/apache2/sites-available/eg.conf
 316 cp Open-ILS/examples/apache_24/eg_vhost_24.conf /etc/apache2/eg_vhost.conf
 317 cp Open-ILS/examples/apache/eg_startup          /etc/apache2/
 318 # Now set up SSL
 319 mkdir /etc/apache2/ssl
 320 cd /etc/apache2/ssl
 321 ------------------------------------------------------------------------------------
 322 +
 323 .Fedora
 324 [source,bash]
 325 ------------------------------------------------------------------------------
 326 cp Open-ILS/examples/apache_24/eg_24.conf       /etc/httpd/conf.d/
 327 cp Open-ILS/examples/apache_24/eg_vhost_24.conf /etc/httpd/eg_vhost.conf
 328 cp Open-ILS/examples/apache/eg_startup          /etc/httpd/
 329 # Now set up SSL
 330 mkdir /etc/httpd/ssl
 331 cd /etc/httpd/ssl
 332 ------------------------------------------------------------------------------
 333 +
 334 . The `openssl` command cuts a new SSL key for your Apache server. For a
 335 production server, you should purchase a signed SSL certificate, but you can
 336 just use a self-signed certificate and accept the warnings in the staff client
 337 and browser during testing and development. Create an SSL key for the Apache
 338 server by issuing the following command as the *root* Linux account:
 339 +
 340 [source,bash]
 341 ------------------------------------------------------------------------------
 342 openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key
 343 ------------------------------------------------------------------------------
 344 +
 345 . As the *root* Linux account, edit the `eg.conf` file that you copied into
 346 place.
 347   a. To enable access to the offline upload / execute interface from any
 348      workstation on any network, make the following change (and note that
 349      you *must* secure this for a production instance):
 350      * (Apache 2.2): Replace `Allow from 10.0.0.0/8` with `Allow from all`
 351      * (Apache 2.4): Replace `Require host 10.0.0.0/8` with `Require all granted`
 352   b. (Fedora): Change references from the non-existent `/etc/apache2/` directory
 353      to `/etc/httpd/`.
 354 . Change the user for the Apache server.
 355   * (Debian and Ubuntu): As the *root* Linux account, edit
 356     `/etc/apache2/envvars`.  Change `export APACHE_RUN_USER=www-data` to
 357     `export APACHE_RUN_USER=opensrf`.
 358   * (Fedora): As the *root* Linux account , edit `/etc/httpd/conf/httpd.conf`.
 359     Change `User apache` to `User opensrf`.
 360 . As the *root* Linux account, configure Apache with KeepAlive settings
 361   appropriate for Evergreen. Higher values can improve the performance of a
 362   single client by allowing multiple requests to be sent over the same TCP
 363   connection, but increase the risk of using up all available Apache child
 364   processes and memory.
 365   * (Debian and Ubuntu): Edit `/etc/apache2/apache2.conf`.
 366     a. Change `KeepAliveTimeout` to `1`.
 367     b. Change `MaxKeepAliveRequests` to `100`.
 368   * (Fedora): Edit `/etc/httpd/conf/httpd.conf`.
 369     a. Change `KeepAliveTimeout` to `1`.
 370     b. Change `MaxKeepAliveRequests` to `100`.
 371 . As the *root* Linux account, configure the prefork module to start and keep
 372   enough Apache servers available to provide quick responses to clients without
 373   running out of memory. The following settings are a good starting point for a
 374   site that exposes the default Evergreen catalogue to the web:
 375 +
 376 .Debian Wheezy (`/etc/apache2/apache2.conf`) and Fedora (`/etc/httpd/conf/httpd.conf`)
 377 [source,bash]
 378 ------------------------------------------------------------------------------
 379 <IfModule mpm_prefork_module>
 380    StartServers         15
 381    MinSpareServers       5
 382    MaxSpareServers      15
 383    MaxClients           75
 384    MaxRequestsPerChild 500
 385 </IfModule>
 386 ------------------------------------------------------------------------------
 387 +
 388 .Ubuntu Trusty, Ubuntu Xenial, Debian Jessie (`/etc/apache2/mods-available/mpm_prefork.conf`)
 389 [source,bash]
 390 ------------------------------------------------------------------------------
 391 <IfModule mpm_prefork_module>
 392    StartServers            15
 393    MinSpareServers          5
 394    MaxSpareServers         15
 395    MaxRequestWorkers       75
 396    MaxConnectionsPerChild 500
 397 </IfModule>
 398 ------------------------------------------------------------------------------
 399 +
 400 . (Ubuntu Trusty, Ubuntu Xenial, Debian Jessie) As the *root* user,
 401     enable the mpm_prefork module:
 402 +
 403 [source,bash]
 404 ------------------------------------------------------------------------------
 405 a2dismod mpm_event
 406 a2enmod mpm_prefork
 407 ------------------------------------------------------------------------------
 408 +
 409 . (Fedora): As the *root* Linux account, edit the `/etc/httpd/eg_vhost.conf`
 410    file to change references from the non-existent `/etc/apache2/` directory
 411    to `/etc/httpd/`.
 412 . (Debian Wheezy): As the *root* Linux account, enable the Evergreen site:
 413 +
 414 [source,bash]
 415 ------------------------------------------------------------------------------
 416 a2dissite default  # OPTIONAL: disable the default site (the "It Works" page)
 417 a2ensite eg.conf
 418 ------------------------------------------------------------------------------
 419 +
 420 (Ubuntu Trusty, Ubuntu Xenial, Debian Jessie):
 421 +
 422 [source,bash]
 423 ------------------------------------------------------------------------------
 424 a2dissite 000-default  # OPTIONAL: disable the default site (the "It Works" page)
 425 a2ensite eg.conf
 426 ------------------------------------------------------------------------------
 427 +
 428 . (Ubuntu): As the *root* Linux account, enable Apache to write
 429    to the lock directory; this is currently necessary because Apache
 430    is running as the `opensrf` user:
 431 +
 432 [source,bash]
 433 ------------------------------------------------------------------------------
 434 chown opensrf /var/lock/apache2
 435 ------------------------------------------------------------------------------
 436
 437 Learn more about additional Apache options in the following sections:
 438
 439   * <<_apache_rewrite_tricks,Apache Rewrite Tricks>>
 440   * <<_apache_access_handler_perl_module,Apache Access Handler Perl Module>>
 441
 442 Configure OpenSRF for the Evergreen application
 443 -----------------------------------------------
 444 There are a number of example OpenSRF configuration files in `/openils/conf/`
 445 that you can use as a template for your Evergreen installation. Issue the
 446 following commands as the *opensrf* Linux account:
 447
 448 [source, bash]
 449 ------------------------------------------------------------------------------
 450 cp -b /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml
 451 cp -b /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml
 452 ------------------------------------------------------------------------------
 453
 454 When you installed OpenSRF, you created four Jabber users on two
 455 separate domains and edited the `opensrf_core.xml` file accordingly. Please
 456 refer back to the OpenSRF README and, as the *opensrf* Linux account, edit the
 457 Evergreen version of the `opensrf_core.xml` file using the same Jabber users
 458 and domains as you used while installing and testing OpenSRF.
 459
 460 [NOTE]
 461 The `-b` flag tells the `cp` command to create a backup version of the
 462 destination file. The backup version of the destination file has a tilde (`~`)
 463 appended to the file name, so if you have forgotten the Jabber users and
 464 domains, you can retrieve the settings from the backup version of the files.
 465
 466 `eg_db_config`, described in <<_creating_the_evergreen_database,Creating the Evergreen
 467 database>>, sets the database connection information in `opensrf.xml` for you.
 468
 469 Configure action triggers for the Evergreen application
 470 -------------------------------------------------------
 471 _Action Triggers_ provide hooks for the system to perform actions when a given
 472 event occurs; for example, to generate reminder or overdue notices, the
 473 `checkout.due` hook is processed and events are triggered for potential actions
 474 if there is no checkin time.
 475
 476 To enable the default set of hooks, issue the following command as the
 477 *opensrf* Linux account:
 478
 479 [source, bash]
 480 ------------------------------------------------------------------------------
 481 cp -b /openils/conf/action_trigger_filters.json.example /openils/conf/action_trigger_filters.json
 482 ------------------------------------------------------------------------------
 483
 484 For more information about configuring and using action triggers, see
 485 <<_notifications_action_triggers,Notifications / Action Triggers>>.
 486
 487 Creating the Evergreen database
 488 -------------------------------
 489
 490 Setting up the PostgreSQL server
 491 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 492
 493 For production use, most libraries install the PostgreSQL database server on a
 494 dedicated machine. Therefore, by default, the `Makefile.install` prerequisite
 495 installer does *not* install the PostgreSQL 9 database server that is required
 496 by every Evergreen system. You can install the packages required by Debian or
 497 Ubuntu on the machine of your choice using the following commands as the
 498 *root* Linux account:
 499
 500 .(Debian / Ubuntu / Fedora) Installing PostgreSQL server packages
 501
 502 Each OS build target provides the postgres server installation packages
 503 required for each operating system.  To install Postgres server packages,
 504 use the make target 'postgres-server-<OSTYPE>'.  Choose the most appropriate
 505 command below based on your operating system.
 506
 507 [source, bash]
 508 ------------------------------------------------------------------------------
 509 make -f Open-ILS/src/extras/Makefile.install postgres-server-debian-jessie
 510 make -f Open-ILS/src/extras/Makefile.install postgres-server-debian-wheezy
 511 make -f Open-ILS/src/extras/Makefile.install postgres-server-ubuntu-trusty
 512 make -f Open-ILS/src/extras/Makefile.install postgres-server-ubuntu-xenial
 513 make -f Open-ILS/src/extras/Makefile.install postgres-server-fedora
 514 ------------------------------------------------------------------------------
 515
 516 .(Fedora) Postgres initialization
 517
 518 Installing Postgres on Fedora also requires you to initialize the PostgreSQL
 519 cluster and start the service. Issue the following commands as the *root* user:
 520
 521 [source, bash]
 522 ------------------------------------------------------------------------------
 523 postgresql-setup initdb
 524 systemctl start postgresql
 525 ------------------------------------------------------------------------------
 526
 527 For a standalone PostgreSQL server, install the following Perl modules for your
 528 distribution as the *root* Linux account:
 529
 530 .(Debian Wheezy, Ubuntu Trusty, and Ubuntu Xenial)
 531 No extra modules required for these distributions.
 532
 533 .(Fedora)
 534 [source, bash]
 535 ------------------------------------------------------------------------------
 536 cpan Rose::URI
 537 ------------------------------------------------------------------------------
 538
 539 You need to create a PostgreSQL superuser to create and access the database.
 540 Issue the following command as the *postgres* Linux account to create a new
 541 PostgreSQL superuser named `evergreen`. When prompted, enter the new user's
 542 password:
 543
 544 [source, bash]
 545 ------------------------------------------------------------------------------
 546 createuser -s -P evergreen
 547 ------------------------------------------------------------------------------
 548
 549 .Enabling connections to the PostgreSQL database
 550
 551 Your PostgreSQL database may be configured by default to prevent connections,
 552 for example, it might reject attempts to connect via TCP/IP or from other
 553 servers. To enable TCP/IP connections from localhost, check your `pg_hba.conf`
 554 file, found in the `/etc/postgresql/` directory on Debian and Ubuntu, and in
 555 the `/var/lib/pgsql/data/` directory on Fedora. A simple way to enable TCP/IP
 556 connections from localhost to all databases with password authentication, which
 557 would be suitable for a test install of Evergreen on a single server, is to
 558 ensure the file contains the following entries _before_ any "host ... ident"
 559 entries:
 560
 561 ------------------------------------------------------------------------------
 562 host    all             all             ::1/128                 md5
 563 host    all             all             127.0.0.1/32            md5
 564 ------------------------------------------------------------------------------
 565
 566 When you change the `pg_hba.conf` file, you will need to reload PostgreSQL to
 567 make the changes take effect.  For more information on configuring connectivity
 568 to PostgreSQL, see
 569 http://www.postgresql.org/docs/devel/static/auth-pg-hba-conf.html
 570
 571 Creating the Evergreen database and schema
 572 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 573
 574 Once you have created the *evergreen* PostgreSQL account, you also need to
 575 create the database and schema, and configure your configuration files to point
 576 at the database server. Issue the following command as the *root* Linux account
 577 from inside the Evergreen source directory, replacing <user>, <password>,
 578 <hostname>, <port>, and <dbname> with the appropriate values for your
 579 PostgreSQL database (where <user> and <password> are for the *evergreen*
 580 PostgreSQL account you just created), and replace <admin-user> and <admin-pass>
 581 with the values you want for the *egadmin* Evergreen administrator account:
 582
 583 [source, bash]
 584 ------------------------------------------------------------------------------
 585 perl Open-ILS/src/support-scripts/eg_db_config --update-config \
 586        --service all --create-database --create-schema --create-offline \
 587        --user <user> --password <password> --hostname <hostname> --port <port> \
 588        --database <dbname> --admin-user <admin-user> --admin-pass <admin-pass>
 589 ------------------------------------------------------------------------------
 590
 591 This creates the database and schema and configures all of the services in
 592 your `/openils/conf/opensrf.xml` configuration file to point to that database.
 593 It also creates the configuration files required by the Evergreen `cgi-bin`
 594 administration scripts, and sets the user name and password for the *egadmin*
 595 Evergreen administrator account to your requested values.
 596
 597 You can get a complete set of options for `eg_db_config` by passing the
 598 `--help` parameter.
 599
 600 Loading sample data
 601 ~~~~~~~~~~~~~~~~~~~
 602 If you add the `--load-all-sample` parameter to the `eg_db_config` command,
 603 a set of authority and bibliographic records, call numbers, copies, staff
 604 and regular users, and transactions will be loaded into your target
 605 database. This sample dataset is commonly referred to as the _concerto_
 606 sample data, and can be useful for testing out Evergreen functionality and
 607 for creating problem reports that developers can easily recreate with their
 608 own copy of the _concerto_ sample data.
 609
 610 Creating the database on a remote server
 611 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 612 In a production instance of Evergreen, your PostgreSQL server should be
 613 installed on a dedicated server.
 614
 615 PostgreSQL 9.1 and later
 616 ^^^^^^^^^^^^^^^^^^^^^^^^
 617 To create the database instance on a remote database server running PostgreSQL
 618 9.1 or later, simply use the `--create-database` flag on `eg_db_config`.
 619
 620 Starting Evergreen
 621 ------------------
 622 1. As the *root* Linux account, start the `memcached` and `ejabberd` services
 623 (if they aren't already running):
 624 +
 625 [source, bash]
 626 ------------------------------------------------------------------------------
 627 /etc/init.d/ejabberd start
 628 /etc/init.d/memcached start
 629 ------------------------------------------------------------------------------
 630 +
 631 2. As the *opensrf* Linux account, start Evergreen. The `-l` flag in the
 632 following command is only necessary if you want to force Evergreen to treat the
 633 hostname as `localhost`; if you configured `opensrf.xml` using the real
 634 hostname of your machine as returned by `perl -ENet::Domain 'print
 635 Net::Domain::hostfqdn() . "\n";'`, you should not use the `-l` flag.
 636 +
 637 [source, bash]
 638 ------------------------------------------------------------------------------
 639 osrf_control -l --start-all
 640 ------------------------------------------------------------------------------
 641 +
 642   ** If you receive the error message `bash: osrf_control: command not found`,
 643      then your environment variable `PATH` does not include the `/openils/bin`
 644      directory; this should have been set in the *opensrf* Linux account's
 645      `.bashrc` configuration file. To manually set the `PATH` variable, edit the
 646      configuration file `~/.bashrc` as the *opensrf* Linux account and add the
 647      following line:
 648 +
 649 [source, bash]
 650 ------------------------------------------------------------------------------
 651 export PATH=$PATH:/openils/bin
 652 ------------------------------------------------------------------------------
 653 +
 654 3. As the *opensrf* Linux account, generate the Web files needed by the staff
 655    client and catalogue and update the organization unit proximity (you need to do
 656    this the first time you start Evergreen, and after that each time you change the library org unit configuration.
 657 ):
 658 +
 659 [source, bash]
 660 ------------------------------------------------------------------------------
 661 autogen.sh
 662 ------------------------------------------------------------------------------
 663 +
 664 4. As the *root* Linux account, restart the Apache Web server:
 665 +
 666 [source, bash]
 667 ------------------------------------------------------------------------------
 668 /etc/init.d/apache2 restart
 669 ------------------------------------------------------------------------------
 670 +
 671 If the Apache Web server was running when you started the OpenSRF services, you
 672 might not be able to successfully log in to the OPAC or staff client until the
 673 Apache Web server is restarted.
 674
 675 Testing connections to Evergreen
 676 --------------------------------
 677
 678 Once you have installed and started Evergreen, test your connection to
 679 Evergreen via `srfsh`. As the *opensrf* Linux account, issue the following
 680 commands to start `srfsh` and try to log onto the Evergreen server using the
 681 *egadmin* Evergreen administrator user name and password that you set using the
 682 `eg_db_config` command:
 683
 684 [source, bash]
 685 ------------------------------------------------------------------------------
 686 /openils/bin/srfsh
 687 srfsh% login <admin-user> <admin-pass>
 688 ------------------------------------------------------------------------------
 689
 690 You should see a result like:
 691
 692     Received Data: "250bf1518c7527a03249858687714376"
 693     ------------------------------------
 694     Request Completed Successfully
 695     Request Time in seconds: 0.045286
 696     ------------------------------------
 697
 698     Received Data: {
 699        "ilsevent":0,
 700        "textcode":"SUCCESS",
 701        "desc":" ",
 702        "pid":21616,
 703        "stacktrace":"oils_auth.c:304",
 704        "payload":{
 705           "authtoken":"e5f9827cc0f93b503a1cc66bee6bdd1a",
 706           "authtime":420
 707        }
 708
 709     }
 710
 711     ------------------------------------
 712     Request Completed Successfully
 713     Request Time in seconds: 1.336568
 714     ------------------------------------
 715 [[install-troubleshooting-1]]
 716 If this does not work, it's time to do some troubleshooting.
 717
 718   * As the *opensrf* Linux account, run the `settings-tester.pl` script to see
 719     if it finds any system configuration problems. The script is found at
 720     `Open-ILS/src/support-scripts/settings-tester.pl` in the Evergreen source
 721     tree.
 722   * Follow the steps in the http://evergreen-ils.org/dokuwiki/doku.php?id=troubleshooting:checking_for_errors[troubleshooting guide].
 723   * If you have faithfully followed the entire set of installation steps
 724     listed here, you are probably extremely close to a working system.
 725     Gather your configuration files and log files and contact the
 726     http://evergreen-ils.org/communicate/mailing-lists/[Evergreen development
 727 mailing list] for assistance before making any drastic changes to your system
 728     configuration.
 729
 730 Getting help
 731 ------------
 732
 733 Need help installing or using Evergreen? Join the mailing lists at
 734 http://evergreen-ils.org/communicate/mailing-lists/ or contact us on the Freenode
 735 IRC network on the #evergreen channel.
 736
 737 License
 738 -------
 739 This work is licensed under the Creative Commons Attribution-ShareAlike 3.0
 740 Unported License. To view a copy of this license, visit
 741 http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative
 742 Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA.