Sync up README with rel_1_0 - cover multidomain configuration

git-svn-id: svn://svn.open-ils.org/OpenSRF/trunk@1565 9efc2488-bf62-4759-914b-345cdb29e865

diff --git a/README b/README
index a118ebc..fe3cebe 100644 (file)
--- a/README
+++ b/README
@@ -1,4 +1,4 @@
-README for OpenSRF 1.0 RC
+README for OpenSRF
 
 Installing prerequisites:
 ========================
@@ -43,10 +43,12 @@ See "Developer instructions" at the bottom of the file.
 Configuration and compilation instructions:
 ==========================================
 
-For the time being, we are still installing everything in the /openils/
-directory (with the exception of the Perl modules, which are installed
-into system directories). Issue the following commands to configure and
-build OpenSRF:
+Use the "configure" command to configure OpenSRF, and the "make" command to
+build OpenSRF. The default installation prefix (PREFIX) for OpenSRF is
+"/opensrf/".
+
+If you are building OpenSRF for Evergreen, pass the --prefix and --sysconfdir
+options as follows:
 
 ./configure --prefix=/openils --sysconfdir=/openils/conf
 make
@@ -63,8 +65,9 @@ command as the root user to install OpenSRF:
 
 make install
 
-This will install OpenSRF, including example configuration files in
-/openils/conf/ that you can use as templates for your own configuration files.
+This will install OpenSRF in the prefix directory that you specified in the
+configuration step. This will also install example configuration files that
+you can use as templates for your own configuration files.
 
 Create and set up the opensrf Unix user environment:
 ===================================================
@@ -75,21 +78,35 @@ commands as root to create the "opensrf" user and set up its environment,
 substituting <PREFIX> with the value you passed to --prefix in your
 configure command:
 
-$ useradd -m -s /bin/bash opensrf
-$ echo "export PERL5LIB=\$PERL5LIB:/<PREFIX>/lib" > /home/opensrf/.bashrc
-$ echo "export PATH=\$PATH:/<PREFIX>/bin" > /home/opensrf/.bashrc
-$ passwd opensrf
+# useradd -m -s /bin/bash opensrf
+# echo "export PATH=\$PATH:/<PREFIX>/bin" >> /home/opensrf/.bashrc
+# passwd opensrf
+
+Define your public and private OpenSRF domains:
+==============================================
+
+For security purposes, OpenSRF uses Jabber domains to separate services
+into public and private realms. Throughout these instructions, we will use
+the example domains "public.localhost" and "private.localhost". 
+
+On a single-server system, the easiest way to define public and private
+domains is to define separate hostnames by adding entries to the
+/etc/hosts file. Here are entries that you could make to a stock /etc/hosts
+file for our example domains:
+
+127.0.1.2      public.localhost        public
+127.0.1.3      private.localhost       private
 
 Adjust the system dynamic library path:
 ======================================
 
-Add /openils/lib/ to the system's dynamic library path, and then run "ldconfig"
+Add <PREFIX>/lib/ to the system's dynamic library path, and then run "ldconfig"
 as root.
 
 On Debian and Ubuntu systems, run the following commands as root:
 
-$ echo /openils/lib > /etc/ld.so.conf.d/opensrf.conf
-$ ldconfig
+# echo <PREFIX>/lib > /etc/ld.so.conf.d/opensrf.conf
+# ldconfig
 
 On most other systems, you can add these entries to a /etc/ld.so.conf, or create
 a file within the /etc/ld.so.conf.d/ directory, and then run "ldconfig" as root.
@@ -100,20 +117,34 @@ Configure the ejabberd server:
 OpenSRF requires an XMPP (Jabber) server. For performance reasons, ejabberd is
 the Jabber server of choice for the OpenSRF project. In most cases, you only
 have to make a few changes to the default ejabberd.cfg file to make ejabberd
-work for OpenSRF. Open /etc/ejabberd/ejabberd.cfg and make the following
+work for OpenSRF. 
+
+1. Stop ejabberd before making any changes to its configuration by issuing the
+following command as root:
+
+# /etc/init.d/ejabberd stop
+
+2. Open /etc/ejabberd/ejabberd.cfg and make the following
 changes:
 
-1. Comment out the "mod_offline" directive
-2. Increase the "max_user_sessions" value to 1000
-3. Change all "max_stanza_size" values to 200000
-4. Change all "maxrate values" to 500000 
+a. Define your public and private domains in the "hosts" directive. For
+   example:
+
+{hosts, ["private.localhost", "public.localhost"]}
+
+b. Comment out the "mod_offline" directive
+c. Increase the "max_user_sessions" value to 1000
+d. Change all "max_stanza_size" values to 200000
+e. Change all "maxrate values" to 500000 
+
+3. Restart the ejabberd server to make the changes take effect:
 
-Restart the ejabberd server to make the changes take effect.
+# /etc/init.d/ejabberd start
 
 Create the OpenSRF Jabber users:
 ===============================
 
-You need two Jabber users to manage the OpenSRF communications:
+On each domain, you need two Jabber users to manage the OpenSRF communications:
 
   * a "router" user, to whom all requests to connect to an OpenSRF service
     will be routed; this Jabber user must be named "router"
@@ -123,15 +154,17 @@ You need two Jabber users to manage the OpenSRF communications:
 Create the Jabber users by issuing the following commands as root. Substitute
 <password> for your chosen passwords for each user respectively:
 
-$ ejabberdctl register router localhost <password>
-$ ejabberdctl register opensrf localhost <password>
+# ejabberdctl register router private.localhost <password>
+# ejabberdctl register opensrf private.localhost <password>
+# ejabberdctl register router public.localhost <password>
+# ejabberdctl register opensrf public.localhost <password>
 
 Update the OpenSRF configuration files:
 ======================================
 
 There are two critical files that you must update to make OpenSRF work.
-"SYSCONFDIR" will be /openils/conf/ if you followed the configuration
-suggestion above:
+"SYSCONFDIR" is "/opensrf/etc" by default, or the value that you passed to
+--sysconfdir during the configuration phase:
 
   * SYSCONFDIR/opensrf.xml - this file lists the services that this
     OpenSRF installation supports; if you create a new OpenSRF service,
@@ -148,16 +181,17 @@ suggestion above:
   * SYSCONFDIR/opensrf_core.xml - this file lists the Jabber connection
     information that will be used for the system, as well as determining
     logging verbosity and defining which services will be exposed on the
-    HTTP gateway. There are three username/password pairs to update in this
+    HTTP gateway. There are four username/password pairs to update in this
     file:
-      1. <config><opensrf> = use the Jabber "opensrf" user
-      2. <config><gateway> = use the Jabber "opensrf" user
-      3. <config><routers><router> = use the Jabber "router" user
+      1. <config><opensrf> = use the private Jabber "opensrf" user
+      2. <config><gateway> = use the public Jabber "opensrf" user
+      3. <config><routers><router> = use the public Jabber "router" user
+      4. <config><routers><router> = use the private Jabber "router" user
 
 You should also create a .srfsh.xml file in the home directory of each user
 that you want to enable to use the srfsh to communicate with OpenSRF services.
 
-Copy /openils/conf/srfsh.xml to ~/.srfsh.xml and update the username and
+Copy <SYSCONFDIR>/srfsh.xml to ~/.srfsh.xml and update the username and
 password values with the Jabber "opensrf" user credentials.
 
 Starting and stopping OpenSRF services:
@@ -194,9 +228,9 @@ you need to install the dnsmasq package, configure it to serve up a DNS
 entry for localhost, and point your local DNS resolver to dnsmasq. For example,
 on Ubuntu you can issue the following commands as root:
 
-$ aptitude install dnsmasq
-$ echo "webserver=/localhost/127.0.0.1/" >> /etc/dnsmasq.conf
-$ /etc/init.d/dnsmasq restart
+# aptitude install dnsmasq
+# echo "webserver=/localhost/127.0.0.1/" >> /etc/dnsmasq.conf
+# /etc/init.d/dnsmasq restart
 
 Then edit /etc/resolv.conf and ensure that "nameserver 127.0.0.1" is the first
 entry in the file.