Docs: Updated usage of autogen.sh to not use param 'u'
[working/Evergreen.git] / docs / installation / server_installation.txt
index 53dcfb6..138b1b6 100644 (file)
@@ -57,27 +57,14 @@ source directory to generate the configure script and Makefiles:
 autoreconf -i
 ------------------------------------------------------------------------------
 
-After running `make install`, developers also need to install the Dojo Toolkit
-set of JavaScript libraries. The appropriate version of Dojo is included
-in Evergreen release tarballs. Developers should install the Dojo 1.3.3
-version of Dojo by issuing the following commands as the *opensrf* Linux
-account:
-
-[source, bash]
-------------------------------------------------------------------------------
-wget http://download.dojotoolkit.org/release-1.3.3/dojo-release-1.3.3.tar.gz
-tar -C /openils/var/web/js -xzf dojo-release-1.3.3.tar.gz
-cp -r /openils/var/web/js/dojo-release-1.3.3/* /openils/var/web/js/dojo/.
-------------------------------------------------------------------------------
-
 Installing prerequisites
 ------------------------
 
 Evergreen has a number of prerequisite packages that must be installed
 before you can successfully configure, compile, and install Evergreen.
 
-1. Begin by installing the most recent version of OpenSRF (2.2 or later).
-   You can download OpenSRF releases from http://evergreen-ils.org/opensrf.php
+1. Begin by installing the most recent version of OpenSRF (2.3.0 or later).
+   You can download OpenSRF releases from http://evergreen-ils.org/opensrf-downloads/
 2. On many distributions, it is necessary to install PostgreSQL 9 from external
    repositories.
 +
@@ -89,28 +76,15 @@ before you can successfully configure, compile, and install Evergreen.
 deb http://backports.debian.org/debian-backports squeeze-backports main contrib
 ------------------------------------------------------------------------------
 +
-  * On Ubuntu Lucid, you can use a PPA (personal package archive), which are 
-    package sources hosted on Launchpad. The one most commonly used by Evergreen
-    Community members is maintained by Martin Pitt, who also maintains the
-    official PostgreSQL packages for Ubuntu. As the *root* Linux account, issue
-    the following commands to add the PPA source:
-+
-[source, bash]
-------------------------------------------------------------------------------
-apt-get install python-software-properties
-add-apt-repository ppa:pitti/postgresql
-------------------------------------------------------------------------------
-+
-  * Ubuntu Precise comes with PostgreSQL 9, so no additional steps are required.
-+
+  * Ubuntu Precise and Trusty comes with PostgreSQL 9+, so no additional steps are required.
   * Fedora comes with PostgreSQL 9, so no additional steps are required.
 +
 3. On Debian and Ubuntu, run `aptitude update` as the *root* Linux account to
    retrieve the new packages from the backports repository.
 4. Issue the following commands as the *root* Linux account to install
    prerequisites using the `Makefile.install` prerequisite installer,
-   substituting `debian-squeeze`, `fedora`, `ubuntu-lucid`, or
-   `ubuntu-precise` for <osname> below:
+   substituting `debian-jessie`, `debian-wheezy`, `debian-squeeze`, `fedora`, 
+   `ubuntu-trusty`, or `ubuntu-precise` for <osname> below:
 +
 [source, bash]
 ------------------------------------------------------------------------------
@@ -121,10 +95,10 @@ make -f Open-ILS/src/extras/Makefile.install <osname>
    issuing the following commands as the *root* Linux account:
 +
 [NOTE]
-You should skip this step if installing on Ubuntu Precise. The ubuntu-precise
-target uses libdbd-pgsql from packages.
+You should skip this step if installing on Ubuntu Precise or Trusty. The ubuntu
+targets use libdbd-pgsql from packages.
 +
-.Debian / Ubuntu Lucid
+.Debian
 [source, bash]
 ------------------------------------------------------------------------------
 echo "/usr/local/lib/dbd" > /etc/ld.so.conf.d/eg.conf
@@ -194,6 +168,27 @@ change the ownership on the files:
 chown -R opensrf:opensrf /openils
 ------------------------------------------------------------------------------
 
+Additional Instructions for Developers
+--------------------------------------
+
+[NOTE]
+Skip this section if you are using an official release tarball downloaded
+from http://evergreen-ils.org/downloads
+
+Developers working directly with the source code from the Git repository,
+rather than an official release tarball, need to install the Dojo Toolkit
+set of JavaScript libraries. The appropriate version of Dojo is included in
+Evergreen release tarballs. Developers should install the Dojo 1.3.3 version
+of Dojo by issuing the following commands as the *opensrf* Linux account:
+
+[source, bash]
+------------------------------------------------------------------------------
+wget http://download.dojotoolkit.org/release-1.3.3/dojo-release-1.3.3.tar.gz
+tar -C /openils/var/web/js -xzf dojo-release-1.3.3.tar.gz
+cp -r /openils/var/web/js/dojo-release-1.3.3/* /openils/var/web/js/dojo/.
+------------------------------------------------------------------------------
+
+
 Configure the Apache Web server
 -------------------------------
 
@@ -203,7 +198,7 @@ versions 2.4 or greater) to configure your Web server for the Evergreen
 catalog, staff client, Web services, and administration interfaces. Issue the
 following commands as the *root* Linux account:
 +
-.Debian and Ubuntu
+.Debian and Ubuntu Precise
 [source,bash]
 ------------------------------------------------------------------------------
 cp Open-ILS/examples/apache/eg.conf       /etc/apache2/sites-available/
@@ -214,23 +209,23 @@ mkdir /etc/apache2/ssl
 cd /etc/apache2/ssl
 ------------------------------------------------------------------------------
 +
-.Fedora 17
+.Ubuntu Trusty
 [source,bash]
-------------------------------------------------------------------------------
-cp Open-ILS/examples/apache/eg.conf       /etc/httpd/conf.d/
-cp Open-ILS/examples/apache/eg_vhost.conf /etc/httpd/
-cp Open-ILS/examples/apache/eg_startup    /etc/httpd/
+------------------------------------------------------------------------------------
+cp Open-ILS/examples/apache_24/eg_24.conf       /etc/apache2/sites-available/eg.conf
+cp Open-ILS/examples/apache_24/eg_vhost_24.conf /etc/apache2/eg_vhost.conf
+cp Open-ILS/examples/apache/eg_startup         /etc/apache2/
 # Now set up SSL
-mkdir /etc/httpd/ssl
-cd /etc/httpd/ssl
-------------------------------------------------------------------------------
+mkdir /etc/apache2/ssl
+cd /etc/apache2/ssl
+------------------------------------------------------------------------------------
 +
-.Fedora 18
+.Fedora
 [source,bash]
 ------------------------------------------------------------------------------
-cp Open-ILS/examples/apache_24/eg.conf       /etc/httpd/conf.d/
-cp Open-ILS/examples/apache_24/eg_vhost.conf /etc/httpd/
-cp Open-ILS/examples/apache/startup.pl       /etc/httpd/
+cp Open-ILS/examples/apache_24/eg_24.conf       /etc/httpd/conf.d/
+cp Open-ILS/examples/apache_24/eg_vhost_24.conf /etc/httpd/eg_vhost.conf
+cp Open-ILS/examples/apache/eg_startup          /etc/httpd/
 # Now set up SSL
 mkdir /etc/httpd/ssl
 cd /etc/httpd/ssl
@@ -270,8 +265,9 @@ place.
        a request timing out unexpectedly, but increase the risk of using up
        all available Apache child processes.
     b. 'Optional': Change `MaxKeepAliveRequests` to `100`
-    c. Update the prefork configuration section to suit your environment. The
-       following settings apply to a busy system:
+    c. (Debian, Ubuntu Precise, and Fedora) Update the prefork configuration 
+       section to suit your environment. The following settings apply to a busy 
+       system:
 +
 [source,bash]
 ------------------------------------------------------------------------------
@@ -283,17 +279,43 @@ place.
    MaxRequestsPerChild 10000
 </IfModule>
 ------------------------------------------------------------------------------
+    d. (Ubuntu Trusty) As the *root* user, edit 
+       /etc/apache2/mods-available/mpm_prefork.conf to match the above values.  
+       Then, also as the *root* user, enable the mpm_prefork module by doing:
++
+[source,bash]
+------------------------------------------------------------------------------
+a2dismod mpm_event
+a2enmod mpm_prefork
+------------------------------------------------------------------------------
 +
 6. (Fedora): As the *root* Linux account, edit the `/etc/httpd/eg_vhost.conf`
    file to change references from the non-existent `/etc/apache2/` directory
    to `/etc/httpd/`.
-7. (Debian and Ubuntu): As the *root* Linux account, enable the Evergreen site:
+7. (Debian and Ubuntu Precise): As the *root* Linux account, enable the Evergreen site:
 +
 [source,bash]
 ------------------------------------------------------------------------------
 a2dissite default  # OPTIONAL: disable the default site (the "It Works" page)
 a2ensite eg.conf
 ------------------------------------------------------------------------------
++
+(Ubuntu Trusty):
++
+[source,bash]
+------------------------------------------------------------------------------
+a2dissite 000-default  # OPTIONAL: disable the default site (the "It Works" page)
+a2ensite eg.conf
+------------------------------------------------------------------------------
++
+8. (Ubuntu): As the *root* Linux account, enable Apache to write
+   to the lock directory; this is currently necessary because Apache
+   is running as the `opensrf` user:
++
+[source,bash]
+------------------------------------------------------------------------------
+chown opensrf /var/lock/apache2
+------------------------------------------------------------------------------
 
 Configure OpenSRF for the Evergreen application
 -----------------------------------------------
@@ -325,59 +347,59 @@ connection information in `opensrf.xml` for you.
 Creating the Evergreen database
 -------------------------------
 
-By default, the `Makefile.install` prerequisite installer does not install
-the PostgreSQL 9 database server required by every Evergreen system;
-for production use, most libraries install the PostgreSQL database server on a
-dedicated machine. You can install the packages required by Debian or Ubuntu Lucid
-on the machine of your choice using the following commands as the *root*
-Linux account:
+Setting up the PostgreSQL server
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.(Debian and Ubuntu Lucid) Installing PostgreSQL 9.1 server packages
-[source, bash]
-------------------------------------------------------------------------------
-make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_backport_debs_91
-------------------------------------------------------------------------------
+For production use, most libraries install the PostgreSQL database server on a
+dedicated machine. Therefore, by default, the `Makefile.install` prerequisite
+installer does *not* install the PostgreSQL 9 database server that is required
+by every Evergreen system. You can install the packages required by Debian or
+Ubuntu on the machine of your choice using the following commands as the
+*root* Linux account:
+
+.(Debian / Ubuntu / Fedora) Installing PostgreSQL server packages
+
+Each OS build target provides the postgres server installation packages
+required for each operating system.  To install Postgres server packages, 
+use the make target 'postgres-server-<OSTYPE>'.  Choose the most appropriate 
+command below based on your operating system.
 
-.(Ubuntu Precise) Installing PostgreSQL 9.1 server packages
 [source, bash]
 ------------------------------------------------------------------------------
-make -f Open-ILS/src/extras/Makefile.install install_pgsql_server_debs_91
+make -f Open-ILS/src/extras/Makefile.install postgres-server-debian-wheezy
+make -f Open-ILS/src/extras/Makefile.install postgres-server-debian-squeeze
+make -f Open-ILS/src/extras/Makefile.install postgres-server-ubuntu-precise
+make -f Open-ILS/src/extras/Makefile.install postgres-server-ubuntu-trusty
+make -f Open-ILS/src/extras/Makefile.install postgres-server-fedora
 ------------------------------------------------------------------------------
 
-You can install the packages required by Fedora on the machine of your choice
-using the following commands as the *root* Linux account:
+.(Fedora) Postgres initialization
+
+Installing Postgres on Fedora also requires you to initialize the PostgreSQL
+cluster and start the service. Issue the following commands as the *root* user:
 
-.(Fedora) Installing PostgreSQL server packages
 [source, bash]
 ------------------------------------------------------------------------------
-make -f Open-ILS/src/extras/Makefile.install install_fedora_pgsql_server
 postgresql-setup initdb
+systemctl start postgresql
 ------------------------------------------------------------------------------
 
-For a standalone PostgreSQL server, install the following Perl modules as the
-*root* Linux account:
+For a standalone PostgreSQL server, install the following Perl modules for your
+distribution as the *root* Linux account:
 
-.(Debian / Ubuntu) Installing additional Perl modules on a standalone PostgreSQL 9 server
-[source, bash]
-------------------------------------------------------------------------------
-aptitude install gcc libxml-libxml-perl libxml-libxslt-perl
-cpan Business::ISBN
-cpan JSON::XS
-cpan Library::CallNumber::LC
-cpan MARC::Record
-cpan MARC::File::XML
-cpan UUID::Tiny
+.(Ubuntu Precise)
+[source,bash]
+---------------------------------------------------------------------------------
 cpan Rose::URI
-------------------------------------------------------------------------------
+---------------------------------------------------------------------------------
 
-.(Fedora) Installing additional Perl modules on a standalone PostgreSQL 9 server
+.(Debian "wheezy" and Ubuntu Trusty) 
+No extra modules required for these distributions.
+
+.(Fedora)
 [source, bash]
 ------------------------------------------------------------------------------
-yum install gcc perl-XML-LibXML perl-XML-LibXSLT perl-Business-ISBN
-cpan Library::CallNumber::LC
-cpan MARC::Record
-cpan MARC::File::XML
-cpan UUID::Tiny
+cpan Rose::URI
 ------------------------------------------------------------------------------
 
 You need to create a PostgreSQL superuser to create and access the database.
@@ -390,6 +412,31 @@ password:
 createuser -s -P evergreen
 ------------------------------------------------------------------------------
 
+.Enabling connections to the PostgreSQL database
+
+Your PostgreSQL database may be configured by default to prevent connections,
+for example, it might reject attempts to connect via TCP/IP or from other
+servers. To enable TCP/IP connections from localhost, check your `pg_hba.conf`
+file, found in the `/etc/postgresql/` directory on Debian and Ubuntu, and in
+the `/var/lib/pgsql/data/` directory on Fedora. A simple way to enable TCP/IP
+connections from localhost to all databases with password authentication, which
+would be suitable for a test install of Evergreen on a single server, is to
+ensure the file contains the following entries _before_ any "host ... ident"
+entries:
+
+------------------------------------------------------------------------------
+host    all             all             ::1/128                 md5
+host    all             all             127.0.0.1/32            md5
+------------------------------------------------------------------------------
+
+When you change the `pg_hba.conf` file, you will need to reload PostgreSQL to
+make the changes take effect.  For more information on configuring connectivity
+to PostgreSQL, see
+http://www.postgresql.org/docs/devel/static/auth-pg-hba-conf.html
+
+Creating the Evergreen database and schema
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Once you have created the *evergreen* PostgreSQL account, you also need to
 create the database and schema, and configure your configuration files to point
 at the database server. Issue the following command as the *root* Linux account
@@ -413,6 +460,19 @@ It also creates the configuration files required by the Evergreen `cgi-bin`
 administration scripts, and sets the user name and password for the *egadmin*
 Evergreen administrator account to your requested values.
 
+You can get a complete set of options for `eg_db_config` by passing the
+`--help` parameter.
+
+Loading sample data
+~~~~~~~~~~~~~~~~~~~
+If you add the `--load-all-sample` parameter to the `eg_db_config` command,
+a set of authority and bibliographic records, call numbers, copies, staff
+and regular users, and transactions will be loaded into your target
+database. This sample dataset is commonly referred to as the _concerto_
+sample data, and can be useful for testing out Evergreen functionality and
+for creating problem reports that developers can easily recreate with their
+own copy of the _concerto_ sample data.
+
 Creating the database on a remote server
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 In a production instance of Evergreen, your PostgreSQL server should be
@@ -442,10 +502,10 @@ Net::Domain::hostfqdn() . "\n";'`, you should not use the `-l` flag.
 +
 [source, bash]
 ------------------------------------------------------------------------------
-osrf_ctl.sh -l -a start_all
+osrf_control -l --start-all
 ------------------------------------------------------------------------------
 +
-  ** If you receive the error message `bash: osrf_ctl.sh: command not found`,
+  ** If you receive the error message `bash: osrf_control: command not found`,
      then your environment variable `PATH` does not include the `/openils/bin`
      directory; this should have been set in the *opensrf* Linux account's
      `.bashrc` configuration file. To manually set the `PATH` variable, edit the
@@ -459,12 +519,12 @@ export PATH=$PATH:/openils/bin
 +
 3. As the *opensrf* Linux account, generate the Web files needed by the staff
    client and catalogue and update the organization unit proximity (you need to do
-   this the first time you start Evergreen, and after that each time you change
-   the library hierarchy in `config.cgi`):
+   this the first time you start Evergreen, and after that each time you change the library org unit configuration.
+):
 +
 [source, bash]
 ------------------------------------------------------------------------------
-autogen.sh -u
+autogen.sh
 ------------------------------------------------------------------------------
 +
 4. As the *root* Linux account, restart the Apache Web server:
@@ -521,7 +581,7 @@ You should see a result like:
 
 If this does not work, it's time to do some troubleshooting.
 
-  * As the *opensrf* Linux acccount, run the `settings-tester.pl` script to see
+  * As the *opensrf* Linux account, run the `settings-tester.pl` script to see
     if it finds any system configuration problems. The script is found at
     `Open-ILS/src/support-scripts/settings-tester.pl` in the Evergreen source
     tree.
@@ -529,15 +589,15 @@ If this does not work, it's time to do some troubleshooting.
   * If you have faithfully followed the entire set of installation steps
     listed here, you are probably extremely close to a working system.
     Gather your configuration files and log files and contact the
-    http://open-ils.org/listserv.php[Evergreen development mailing list]
-    for assistance before making any drastic changes to your system
+    http://evergreen-ils.org/communicate/mailing-lists/[Evergreen development 
+mailing list] for assistance before making any drastic changes to your system
     configuration.
 
 Getting help
 ------------
 
 Need help installing or using Evergreen? Join the mailing lists at
-http://evergreen-ils.org/listserv.php or contact us on the Freenode
+http://evergreen-ils.org/communicate/mailing-lists/ or contact us on the Freenode
 IRC network on the #evergreen channel.
 
 License