(doc) 'debian-wheezy' was left out of the OS options
[working/Evergreen.git] / docs / installation / server_installation.txt
index 5888c1c..d974425 100644 (file)
@@ -1,5 +1,5 @@
-README for Evergreen master
-===========================
+Installing the Evergreen server
+===============================
 :toc:
 :numbered:
 
 :toc:
 :numbered:
 
@@ -32,7 +32,7 @@ follows:
        Evergreen that you will use to test connectivity and configure your
        Evergreen instance.
 
        Evergreen that you will use to test connectivity and configure your
        Evergreen instance.
 
-Preamble: Developer instructions
+Preamble: developer instructions
 --------------------------------
 
 [NOTE]
 --------------------------------
 
 [NOTE]
@@ -57,27 +57,14 @@ source directory to generate the configure script and Makefiles:
 autoreconf -i
 ------------------------------------------------------------------------------
 
 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.
 
 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.0 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.
 +
 2. On many distributions, it is necessary to install PostgreSQL 9 from external
    repositories.
 +
@@ -103,13 +90,13 @@ add-apt-repository ppa:pitti/postgresql
 +
   * Ubuntu Precise comes with PostgreSQL 9, so no additional steps are required.
 +
 +
   * Ubuntu Precise comes with PostgreSQL 9, so no additional steps are required.
 +
-  * Fedora 16 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,
 +
 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`, `fedora16`, `ubuntu-lucid`, or
+   substituting `debian-squeeze`, `debian-wheezy`, `fedora`, `ubuntu-lucid`, or
    `ubuntu-precise` for <osname> below:
 +
 [source, bash]
    `ubuntu-precise` for <osname> below:
 +
 [source, bash]
@@ -147,10 +134,14 @@ the *user* Linux account to configure and build Evergreen:
 
 [source, bash]
 ------------------------------------------------------------------------------
 
 [source, bash]
 ------------------------------------------------------------------------------
-./configure --prefix=/openils --sysconfdir=/openils/conf
+PATH=/openils/bin:$PATH ./configure --prefix=/openils --sysconfdir=/openils/conf
 make
 ------------------------------------------------------------------------------
 
 make
 ------------------------------------------------------------------------------
 
+These instructions assume that you have also installed OpenSRF under `/openils/`.
+If not, please adjust PATH as needed so that the Evergreen `configure` script
+can find `osrf_config`.
+
 Installation instructions
 -------------------------
 
 Installation instructions
 -------------------------
 
@@ -190,20 +181,42 @@ change the ownership on the files:
 chown -R opensrf:opensrf /openils
 ------------------------------------------------------------------------------
 
 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
 -------------------------------
 
 Configure the Apache Web server
 -------------------------------
 
-1. Use the example configuration files in `Open-ILS/examples/apache/` 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:
+1. Use the example configuration files in `Open-ILS/examples/apache/` (for
+Apache versions below 2.4) or `Open-ILS/examples/apache_24/` (for Apache
+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
 [source,bash]
 ------------------------------------------------------------------------------
 cp Open-ILS/examples/apache/eg.conf       /etc/apache2/sites-available/
 cp Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/
 +
 .Debian and Ubuntu
 [source,bash]
 ------------------------------------------------------------------------------
 cp Open-ILS/examples/apache/eg.conf       /etc/apache2/sites-available/
 cp Open-ILS/examples/apache/eg_vhost.conf /etc/apache2/
-cp Open-ILS/examples/apache/startup.pl    /etc/apache2/
+cp Open-ILS/examples/apache/eg_startup    /etc/apache2/
 # Now set up SSL
 mkdir /etc/apache2/ssl
 cd /etc/apache2/ssl
 # Now set up SSL
 mkdir /etc/apache2/ssl
 cd /etc/apache2/ssl
@@ -212,9 +225,9 @@ cd /etc/apache2/ssl
 .Fedora
 [source,bash]
 ------------------------------------------------------------------------------
 .Fedora
 [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/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
 # Now set up SSL
 mkdir /etc/httpd/ssl
 cd /etc/httpd/ssl
@@ -233,9 +246,11 @@ openssl req -new -x509 -days 365 -nodes -out server.crt -keyout server.key
 +
 3. As the *root* Linux account, edit the `eg.conf` file that you copied into
 place.
 +
 3. As the *root* Linux account, edit the `eg.conf` file that you copied into
 place.
-  a. Replace `Allow from 10.0.0.0/8` with `Allow from all` (to enable
-     access to the offline upload / execute interface from any workstation on
-     any network - note that you must secure this for a production instance)
+  a. To enable access to the offline upload / execute interface from any
+     workstation on any network, make the following change (and note that
+     you *must* secure this for a production instance):
+     * (Apache 2.2): Replace `Allow from 10.0.0.0/8` with `Allow from all`
+     * (Apache 2.4): Replace `Require host 10.0.0.0/8` with `Require all granted`
   b. (Fedora): Change references from the non-existent `/etc/apache2/` directory
      to `/etc/httpd/`.
 4. Change the user for the Apache server.
   b. (Fedora): Change references from the non-existent `/etc/apache2/` directory
      to `/etc/httpd/`.
 4. Change the user for the Apache server.
@@ -276,6 +291,14 @@ place.
 a2dissite default  # OPTIONAL: disable the default site (the "It Works" page)
 a2ensite eg.conf
 ------------------------------------------------------------------------------
 a2dissite 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
 -----------------------------------------------
 
 Configure OpenSRF for the Evergreen application
 -----------------------------------------------
@@ -301,39 +324,47 @@ destination file. The backup version of the destination file has a tilde (`~`)
 appended to the file name, so if you have forgotten the Jabber users and
 domains, you can retrieve the settings from the backup version of the files.
 
 appended to the file name, so if you have forgotten the Jabber users and
 domains, you can retrieve the settings from the backup version of the files.
 
-`eg_db_config.pl`, described in the following section, sets the database
+`eg_db_config`, described in the following section, sets the database
 connection information in `opensrf.xml` for you.
 
 Creating the Evergreen database
 -------------------------------
 
 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 Lucid 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]
 ------------------------------------------------------------------------------
 [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-lucid
+make -f Open-ILS/src/extras/Makefile.install postgres-server-ubuntu-precise
+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 16) Installing PostgreSQL server packages
 [source, bash]
 ------------------------------------------------------------------------------
 [source, bash]
 ------------------------------------------------------------------------------
-make -f Open-ILS/src/extras/Makefile.install install_fedora_pgsql_server
 postgresql-setup initdb
 postgresql-setup initdb
+systemctl start postgresql
 ------------------------------------------------------------------------------
 
 For a standalone PostgreSQL server, install the following Perl modules as the
 ------------------------------------------------------------------------------
 
 For a standalone PostgreSQL server, install the following Perl modules as the
@@ -349,16 +380,15 @@ cpan Library::CallNumber::LC
 cpan MARC::Record
 cpan MARC::File::XML
 cpan UUID::Tiny
 cpan MARC::Record
 cpan MARC::File::XML
 cpan UUID::Tiny
+cpan Rose::URI
 ------------------------------------------------------------------------------
 
 ------------------------------------------------------------------------------
 
-.(Fedora 16) Installing additional Perl modules on a standalone PostgreSQL 9 server
+.(Fedora) Installing additional Perl modules on a standalone PostgreSQL 9 server
 [source, bash]
 ------------------------------------------------------------------------------
 yum install gcc perl-XML-LibXML perl-XML-LibXSLT perl-Business-ISBN
 [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
+yum install perl-Library-CallNumber-LC perl-MARC-Record perl-MARC-Charset
+yum install perl-MARC-File-XML perl-UUID-Tiny
 ------------------------------------------------------------------------------
 
 You need to create a PostgreSQL superuser to create and access the database.
 ------------------------------------------------------------------------------
 
 You need to create a PostgreSQL superuser to create and access the database.
@@ -371,6 +401,31 @@ password:
 createuser -s -P evergreen
 ------------------------------------------------------------------------------
 
 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
 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
@@ -382,7 +437,7 @@ with the values you want for the *egadmin* Evergreen administrator account:
 
 [source, bash]
 ------------------------------------------------------------------------------
 
 [source, bash]
 ------------------------------------------------------------------------------
-perl Open-ILS/src/support-scripts/eg_db_config.pl --update-config \
+perl Open-ILS/src/support-scripts/eg_db_config --update-config \
        --service all --create-database --create-schema --create-offline \
        --user <user> --password <password> --hostname <hostname> --port <port> \
        --database <dbname> --admin-user <admin-user> --admin-pass <admin-pass>
        --service all --create-database --create-schema --create-offline \
        --user <user> --password <password> --hostname <hostname> --port <port> \
        --database <dbname> --admin-user <admin-user> --admin-pass <admin-pass>
@@ -394,6 +449,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.
 
 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.pl` 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
 Creating the database on a remote server
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 In a production instance of Evergreen, your PostgreSQL server should be
@@ -402,27 +470,7 @@ installed on a dedicated server.
 PostgreSQL 9.1 and later
 ^^^^^^^^^^^^^^^^^^^^^^^^
 To create the database instance on a remote database server running PostgreSQL
 PostgreSQL 9.1 and later
 ^^^^^^^^^^^^^^^^^^^^^^^^
 To create the database instance on a remote database server running PostgreSQL
-9.1 or later, simply use the `--create-database` flag on `eg_db_config.pl`.
-
-For PostgreSQL 9.0
-^^^^^^^^^^^^^^^^^^
-To create the database instance on a remote database server running PostgreSQL
-9.0, you can either:
-
-  *  Install the PostgreSQL contrib modules on the machine on which you
-     are installing the Evergreen code, and use the `--create-database`
-     option from that machine, or
-  *  Copy the `Open-ILS/src/sql/Pg/create_database.sql` script to your
-     PostgreSQL server and invoke it as the *postgres* Linux account:
-+
-[source, bash]
-------------------------------------------------------------------------------
-psql -vdb_name=<dbname> -vcontrib_dir=`pg_config --sharedir`/contrib -f create_database.sql
-------------------------------------------------------------------------------
-
-Then you can issue the `eg_db_config.pl` command as above _without_ the
-`--create-database` argument to create your schema and configure your
-configuration files.
+9.1 or later, simply use the `--create-database` flag on `eg_db_config`.
 
 Starting Evergreen
 ------------------
 
 Starting Evergreen
 ------------------
@@ -443,10 +491,10 @@ Net::Domain::hostfqdn() . "\n";'`, you should not use the `-l` flag.
 +
 [source, bash]
 ------------------------------------------------------------------------------
 +
 [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
      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
@@ -486,7 +534,7 @@ Once you have installed and started Evergreen, test your connection to
 Evergreen via `srfsh`. As the *opensrf* Linux account, issue the following
 commands to start `srfsh` and try to log onto the Evergreen server using the
 *egadmin* Evergreen administrator user name and password that you set using the
 Evergreen via `srfsh`. As the *opensrf* Linux account, issue the following
 commands to start `srfsh` and try to log onto the Evergreen server using the
 *egadmin* Evergreen administrator user name and password that you set using the
-`eg_db_config.pl` command:
+`eg_db_config` command:
 
 [source, bash]
 ------------------------------------------------------------------------------
 
 [source, bash]
 ------------------------------------------------------------------------------
@@ -522,7 +570,7 @@ You should see a result like:
 
 If this does not work, it's time to do some troubleshooting.
 
 
 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.
     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.
@@ -530,15 +578,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
   * 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
     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
 IRC network on the #evergreen channel.
 
 License