-= Evergreen on FreeBSD Install Notes =
-======================================
-:Author: Bill Erickson
+Installing Evergreen on FreeBSD
+===============================
+:Author: Bill Erickson and Jason Stephenson
About this document
-------------------
+This file is meant to serve as a complete set of installation
+instructions for Evergreen on a single computer running FreeBSD. You
+should have already read the README files for both OpenSRF and
+Evergreen as they provide some insight into the installation process
+that is omitted here. However, the only instructions that you need to
+install OpenSRF and Evergreen on FreeBSD are in this file.
+
+.Caveats
* Each chunk of commands should be run as root, unless it starts with 'su'
* All ports were installed with the default configurations selected (batch mode)
- * Install was tested on FreeBSD-9.0-RC2-i386
- * I am not a FreeBSD expert.
+ * Installation was tested on FreeBSD-9.0-p0-i386
-Basic Setup and PreReqs
------------------------
+Basic Setup and Prerequisites
+-----------------------------
FreeBSD first steps
~~~~~~~~~~~~~~~~~~~
+If this is a freshly installed copy of FreeBSD, then you will want to
+make sure your ports are up to date. If you have not done so before,
+you should run portsnap to fetch and extract the latest ports.
+
[source, sh]
------------------------------------------------------------------------------
portsnap fetch
# 'portstap extract' is only needed the first time portsnap is fetched
portsnap extract
+------------------------------------------------------------------------------
+
+If you have previously fetched and extracted the ports on this system,
+then you can update them with the following:
+
+[source, sh]
+-----------------------------------------------------------------------------
+portsnap fetch
+# 'portstap update' only needed when updating previously extracted ports
portsnap update
+-----------------------------------------------------------------------------
+
+Install Portupgrade
+^^^^^^^^^^^^^^^^^^^
+
+[source, sh]
+-----------------------------------------------------------------------------
cd /usr/ports/ports-mgmt/portupgrade
make -DBATCH install clean
rehash
+portsdb -u
+pkgdb -aF
+-----------------------------------------------------------------------------
+
+Install Bash, Git and Wget
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+[source, sh]
+------------------------------------------------------------------------------
portinstall --batch shells/bash shells/bash-completion devel/git ftp/wget
rehash
-echo ". /usr/local/etc/bash_completion" >> ~/.bash_profile
-bash
------------------------------------------------------------------------------
Utilities, etc. (OPTIONAL)
~~~~~~~~~~~~~~~~~~~~~~~~~~
-Stuff I regularly use.
+Stuff we regularly use.
[source, sh]
------------------------------------------------------------------------------
editors/vim
------------------------------------------------------------------------------
-OpenSRF PreReqs
-~~~~~~~~~~~~~~~
+OpenSRF Prerequisites
+~~~~~~~~~~~~~~~~~~~~~
[source, sh]
------------------------------------------------------------------------------
portinstall --batch \
- devel/autoconf \
- devel/automake \
- devel/libtool \
- devel/pkg-config \
www/apache22 \
net-im/ejabberd \
textproc/libxml2 \
databases/p5-Cache-Memcached \
databases/p5-Class-DBI-AbstractSearch \
databases/p5-Class-DBI-SQLite \
+ databases/p5-GDBM \
devel/p5-DateTime \
devel/p5-DateTime-Format-Builder \
devel/p5-DateTime-Format-Mail \
devel/p5-DateTime-TimeZone \
- lang/p5-Error \
devel/p5-File-Find-Rule \
- textproc/expat2 \
security/libgcrypt \
- databases/gdbm \
devel/p5-Log-Log4perl \
devel/readline \
+ dns/p5-Net-DNS \
net/p5-RPC-XML \
devel/p5-Module-Build \
www/p5-Template-Toolkit \
converters/p5-JSON-XS
------------------------------------------------------------------------------
-Evergreen PreReqs
-~~~~~~~~~~~~~~~~~
+Evergreen Prerequisites
+~~~~~~~~~~~~~~~~~~~~~~~
-Install Postgres 9 first so any ports that rely on postgres will know to
-use version 9.
+Install PostgreSQL 9.1 first so any ports that rely on PostgreSQL will know to
+use version 9.1.
[source, sh]
------------------------------------------------------------------------------
portinstall --batch \
databases/postgresql91-server \
- databases/postgresql91-contrib
+ databases/postgresql91-contrib \
+ databases/postgresql91-plperl
------------------------------------------------------------------------------
[source, sh]
------------------------------------------------------------------------------
portinstall --batch \
- databases/p5-postgresql-plperl \
databases/libdbi \
databases/libdbi-drivers \
databases/p5-DBD-Pg \
textproc/p5-Text-CSV \
textproc/p5-XML-Simple\
textproc/p5-Spreadsheet-WriteExcel \
- devel/p5-UNIVERSAL-require \
net-mgmt/p5-Net-IP \
devel/p5-Locale-Maketext-Lexicon \
- sysutils/p5-Unix-Syslog \
net/p5-Net-Z3950-ZOOM \
net/yaz \
devel/p5-UUID-Tiny \
lang/p5-JavaScript-SpiderMonkey
------------------------------------------------------------------------------
-Evergreen CPAN Mods
-~~~~~~~~~~~~~~~~~~~
+Evergreen CPAN Modules
+~~~~~~~~~~~~~~~~~~~~~~
*Note* : Install all MARC Perl mods from CPAN to get the latest version of
MARC::Record and to ensure MARC::Charset is correctly installed (prob w/
Business::CreditCard::Object \
RPC::XML::Method \
SRU
+cpan -f -i Class::DBI::Frozen::301
------------------------------------------------------------------------------
+Update the Package Database
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
[source, sh]
------------------------------------------------------------------------------
-cpan -f -i Class::DBI::Frozen::301
+pkgdb -aF
------------------------------------------------------------------------------
Add the following to /etc/rc.conf
[source, sh]
------------------------------------------------------------------------------
postgresql_enable="YES"
-postgresql_data="/usr/local/postgres/data"
-postgresql_user="postgres"
memcached_enable="YES"
apache22_enable="YES"
ejabberd_enable="YES"
[source, sh]
------------------------------------------------------------------------------
-pw useradd -m -n opensrf -s /usr/local/bin/bash
+pw useradd -m -n opensrf -s /usr/local/bin/bash -G wheel
echo 'export PATH=/openils/bin:$PATH' >> /home/opensrf/.bashrc
+echo '. /usr/local/etc/bash_completion' > /home/opensrf/.bash_profile
echo '. /home/opensrf/.bashrc' >> /home/opensrf/.bash_profile
chown opensrf:opensrf /home/opensrf/.bash*
------------------------------------------------------------------------------
-Ejabberd Config
+Edit /etc/hosts
~~~~~~~~~~~~~~~
+Add the following lines to `/etc/hosts`
+
+[source, sh]
+------------------------------------------------------------------------------
+# Note the IPs..., result of ejabberd's inetrc
+127.0.0.1 public.localhost public
+127.0.0.1 private.localhost private
+------------------------------------------------------------------------------
+
+Ejabberd Configuration
+~~~~~~~~~~~~~~~~~~~~~~
+
[source, sh]
------------------------------------------------------------------------------
cd /usr/local/etc/ejabberd/
-cp ejabberd.cfg.example ejabberd.cfg
-cp inetrc.example inetrc; # TODO: investigate adding 127.0.1.* to match default /etc/hosts
-# XXX edit ejabberd.cfg per Evergreen instructions (see patch under Reference below)
-chown ejabberd:ejabberd ejabberd.cfg;
-ejabberdctl start
-sleep 2
+cp -p ejabberd.cfg.example ejabberd.cfg
+cp -p inetrc.example inetrc
+------------------------------------------------------------------------------
+
+Open `ejabberd.cfg` and make the following changes:
+
+ 1. Define your public and private domains in the `hosts` directive. For
+ example:
++
+---------------------------------------------------------------------------
+{hosts, ["private.localhost", "public.localhost"]}.
+---------------------------------------------------------------------------
++
+ 2. Change all `max_stanza_size` values to 2000000
+ 3. Change all `maxrate` values to 500000
+ 4. Increase the `max_user_sessions` value to 10000
+ 5. Comment out the `mod_offline` directive
+
+.ejabberd.cfg.patch
+[source, diff]
+------------------------------------------------------------------------------
+--- ejabberd.cfg.example 2012-03-27 15:09:14.000000000 -0400
++++ ejabberd.cfg 2012-03-27 19:52:00.000000000 -0400
+@@ -88,7 +88,7 @@
+ %% You can define one or several, for example:
+ %% {hosts, ["example.net", "example.com", "example.org"]}.
+ %%
+-{hosts, ["localhost"]}.
++{hosts, ["private.localhost", "public.localhost"]}.
+
+ %%
+ %% route_subdomains: Delegate subdomains to other XMPP servers.
+@@ -119,7 +119,7 @@
+
+ {access, c2s},
+ {shaper, c2s_shaper},
+- {max_stanza_size, 65536}
++ {max_stanza_size, 2000000}
+ ]},
+
+ %%
+@@ -134,7 +134,7 @@
+
+ {5269, ejabberd_s2s_in, [
+ {shaper, s2s_shaper},
+- {max_stanza_size, 131072}
++ {max_stanza_size, 2000000}
+ ]},
+
+ %%
+@@ -341,12 +341,12 @@
+ %%
+ %% The "normal" shaper limits traffic speed to 1000 B/s
+ %%
+-{shaper, normal, {maxrate, 1000}}.
++{shaper, normal, {maxrate, 500000}}.
+
+ %%
+ %% The "fast" shaper limits traffic speed to 50000 B/s
+ %%
+-{shaper, fast, {maxrate, 50000}}.
++{shaper, fast, {maxrate, 500000}}.
+
+ %%
+ %% This option specifies the maximum number of elements in the queue
+@@ -398,7 +398,7 @@
+ %%%' ACCESS RULES
+
+ %% Maximum number of simultaneous sessions allowed for a single user:
+-{access, max_user_sessions, [{10, all}]}.
++{access, max_user_sessions, [{10000, all}]}.
+
+ %% Maximum number of offline messages that users can have:
+ {access, max_user_offline_messages, [{5000, admin}, {100, all}]}.
+@@ -518,7 +518,7 @@
+ {access_admin, muc_admin}
+ ]},
+ %%{mod_muc_log,[]},
+- {mod_offline, [{access_max_user_messages, max_user_offline_messages}]},
++ %%{mod_offline, [{access_max_user_messages, max_user_offline_messages}]},
+ {mod_ping, []},
+ %%{mod_pres_counter,[{count, 5}, {interval, 60}]},
+ {mod_privacy, []},
+------------------------------------------------------------------------------
+
+.Start the ejabberd server
+[source, sh]
+------------------------------------------------------------------------------
+/usr/local/etc/rc.d/ejabberd start
+------------------------------------------------------------------------------
+
+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`
+ * an `opensrf` user, which clients use to connect to OpenSRF services; this
+ user can be named anything you like
+
+.Creating the OpenSRF Jabber users
+[source, sh]
+------------------------------------------------------------------------------
ejabberdctl register router private.localhost password
ejabberdctl register opensrf private.localhost password
ejabberdctl register router public.localhost password
/usr/local/etc/rc.d/memcached start
------------------------------------------------------------------------------
-Postgres Setup
-~~~~~~~~~~~~~~
-
-*Note* : The postgres user on FreeBSD is 'pgsql' by default. Use 'postgres'
-instead for consistency w/ Evergreen docs.
+PostgreSQL Setup
+~~~~~~~~~~~~~~~~
[source, sh]
------------------------------------------------------------------------------
-pw useradd -m -n postgres -s /usr/local/bin/bash -d /usr/local/postgres
-su postgres
-mkdir /usr/local/postgres/data
-initdb --encoding=utf-8 --lc-collate=C -D /usr/local/postgres/data
-exit # su postgres
+su pgsql
+mkdir /usr/local/pgsql/data
+initdb --encoding=utf-8 --lc-collate=C -D /usr/local/pgsql/data
+exit # su pgsql
/usr/local/etc/rc.d/postgresql start
------------------------------------------------------------------------------
cd /home/opensrf
git clone git://git.evergreen-ils.org/OpenSRF.git
git clone git://git.evergreen-ils.org/Evergreen.git
-# XXX Add "working" remote for both repos and checkout the collab/berick/bsd-compat branch
exit # su opensrf
------------------------------------------------------------------------------
--with-apxs=/usr/local/sbin/apxs --with-libxml2=/usr/local/include/libxml2
gmake
exit # su opensrf
-------------------------------------------------------------------------------
-
-[source, sh]
-------------------------------------------------------------------------------
gmake install
+ldconfig -m /openils/lib
chown -R opensrf:opensrf /openils
# copy some files into place
cp /openils/conf/opensrf.xml.example /openils/conf/opensrf.xml
cp /openils/conf/opensrf_core.xml.example /openils/conf/opensrf_core.xml
-cp /openils/conf/srfsh.xml.example /home/opensrf/.srfsh.xml;
+cp /openils/conf/srfsh.xml.example /home/opensrf/.srfsh.xml
+exit # su opensrf
+------------------------------------------------------------------------------
+
+Edit opensrf_core.xml
+~~~~~~~~~~~~~~~~~~~~~
+
+As the `opensrf` user, edit the `/openils/conf/opensrf_core.xml` file
+to update the four username / password pairs to match the Jabber user
+accounts you just created:
+
+ 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
+
+Edit .srfsh.xml
+~~~~~~~~~~~~~~~
+
+As the `opensrf` user, edit `~/.srfsh.xml` and update the password to
+match the password you set for the Jabber `opensrf` user at the
+`private.localhost` domain.
-# dojo
-cd /tmp
+
+Install Dojo
+~~~~~~~~~~~~
+
+[source, sh]
+------------------------------------------------------------------------------
+su opensrf
+cd /home/opensrf
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/.
exit # su opensrf
------------------------------------------------------------------------------
-Create the EG DB
-~~~~~~~~~~~~~~~~
+Create the Evergreen DB User
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
[source, sh]
------------------------------------------------------------------------------
-su postgres
-createdb -T template0 --lc-ctype=C --lc-collate=C --encoding=utf-8 evergreen
-createlang plperl evergreen
-createlang plperlu evergreen
-psql -d evergreen -c "CREATE EXTENSION tablefunc"
-psql -d evergreen -c "CREATE EXTENSION tsearch2"
-psql -d evergreen -c "CREATE EXTENSION hstore"
-createuser -P -s evergreen
-exit # su postgres
+su pgsql
+createuser -P -s opensrf
+exit # su pgsql
------------------------------------------------------------------------------
Install the EG Schema
~~~~~~~~~~~~~~~~~~~~~
-*alert* : First, apply the GDBM_File patch from below ("GDBM_File.pm Patch" below)
-
[source, sh]
------------------------------------------------------------------------------
ADMIN_USER=admin # change to suit
ADMIN_PASS=demo123 # change to suit
-DB_USER=evergreen # change to suit
-DB_PASS=evergreen # change to suit
+DB_USER=opensrf # change to suit
+DB_PASS=opensrf # change to suit
cd /home/opensrf/Evergreen;
perl Open-ILS/src/support-scripts/eg_db_config.pl \
- --update-config --service all --create-schema \
- --create-bootstrap --create-offline --user $DB_USER \
+ --update-config --service all --create-database \
+ --create-schema --create-offline --user $DB_USER \
--password $DB_PASS --hostname localhost --database evergreen \
--admin-user $ADMIN_USER --admin-pass $ADMIN_PASS
------------------------------------------------------------------------------
-Edit /etc/hosts
-~~~~~~~~~~~~~~~
-
-[source, sh]
-------------------------------------------------------------------------------
-# Note the IPs..., result of ejabberd's inetrc
-127.0.0.1 public.localhost public
-127.0.0.1 private.localhost private
-------------------------------------------------------------------------------
-
Start Evergreen
~~~~~~~~~~~~~~~
/usr/local/etc/rc.d/rsyslogd start
------------------------------------------------------------------------------
-Reference
----------
-
-OpenSRF Patches
-~~~~~~~~~~~~~~~
-
-http://git.evergreen-ils.org/?p=working/OpenSRF.git;a=shortlog;h=refs/heads/collab/berick/bsd-compat
-
-Evergreen Patches
-~~~~~~~~~~~~~~~~~
-
-http://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/collab/berick/bsd-compat
-
-GDBM_File.pm Patch
-~~~~~~~~~~~~~~~~~
-
-There is currently a version incompatibility with GDBM_File.pm and XSLoader.pm.
-This will fix it.
-
-[source, diff]
-------------------------------------------------------------------------------
---- /tmp/GDBM_File.pm 2011-11-15 22:46:43.000000000 -0500
-+++ /usr/local/lib/perl5/site_perl/5.12.4/mach/GDBM_File.pm 2011-11-15 17:16:15.000000000 -0500
-@@ -71,6 +71,6 @@
- # This module isn't dual life, so no need for dev version numbers.
- $VERSION = '1.14';
-
--XSLoader::load;
-+XSLoader::load('GDBM_File', $VERSION);
-
- 1;
-------------------------------------------------------------------------------
-
-Ejabberd Config Patch
-~~~~~~~~~~~~~~~~~~~~~
-
-Nothing special here. Just adding it for reference.
-
-[source, diff]
-------------------------------------------------------------------------------
---- ejabberd.cfg.example 2011-11-13 11:06:39.000000000 -0500
-+++ ejabberd.cfg 2011-11-13 22:11:26.000000000 -0500
-@@ -88,7 +88,7 @@
- %% You can define one or several, for example:
- %% {hosts, ["example.net", "example.com", "example.org"]}.
- %%
--{hosts, ["localhost"]}.
-+{hosts, ["public.localhost", "private.localhost"]}.
-
- %%
- %% route_subdomains: Delegate subdomains to other XMPP servers.
-@@ -119,7 +119,7 @@
-
- {access, c2s},
- {shaper, c2s_shaper},
-- {max_stanza_size, 65536}
-+ {max_stanza_size, 200000}
- ]},
-
- %%
-@@ -134,7 +134,7 @@
-
- {5269, ejabberd_s2s_in, [
- {shaper, s2s_shaper},
-- {max_stanza_size, 131072}
-+ {max_stanza_size, 200000}
- ]},
-
- %%
-@@ -341,12 +341,12 @@
- %%
- %% The "normal" shaper limits traffic speed to 1000 B/s
- %%
--{shaper, normal, {maxrate, 1000}}.
-+{shaper, normal, {maxrate, 500000}}.
-
- %%
- %% The "fast" shaper limits traffic speed to 50000 B/s
- %%
--{shaper, fast, {maxrate, 50000}}.
-+{shaper, fast, {maxrate, 500000}}.
-
- %%
- %% This option specifies the maximum number of elements in the queue
-@@ -398,7 +398,7 @@
- %%%' ACCESS RULES
-
- %% Maximum number of simultaneous sessions allowed for a single user:
--{access, max_user_sessions, [{10, all}]}.
-+{access, max_user_sessions, [{5000, all}]}.
-
- %% Maximum number of offline messages that users can have:
- {access, max_user_offline_messages, [{5000, admin}, {100, all}]}.
-@@ -518,7 +518,7 @@
- {access_admin, muc_admin}
- ]},
- %%{mod_muc_log,[]},
-- {mod_offline, [{access_max_user_messages, max_user_offline_messages}]},
-+ %%{mod_offline, [{access_max_user_messages, max_user_offline_messages}]},
- {mod_ping, []},
- %%{mod_pres_counter,[{count, 5}, {interval, 60}]},
- {mod_privacy, []},
-------------------------------------------------------------------------------
-
+A Note About Installing on Multiple Machines
+--------------------------------------------
+
+The instructions above assume that you are installing everything on 1
+machine for testing, development, or demonstration purposes. If you
+wish to install for production on multiple FreeBSD machines, then you
+will need to make some adjustments to the above instructions.
+
+A typical production installation has the database server on dedicated
+hardware. This means you should only install the PostgreSQL server,
+contrib, and plperl ports on that one machine. You will need to
+install the PostgreSQL client ports (databases/postgresql91-client) on
+your other machines so that they have the necessary tools to
+communicate with the database server.
+
+(*TODO:* Elaborate on exactly what packages the database server needs.)
+
+If you plan on setting up a set of bricks of servers on machines of
+the same architecture, then we'd recommend that you use 1 computer to
+prebuild all of the ports as packages. You can then share the package
+directory from this build machine with the others and install the
+packages from pre-built binaries. This will save you a lot of time
+over compiling everything from source on each machine.
+
+Creating packages from the above instructions is very simple. Where
+the instructions say to `cd` to a port directory and do a `make
+install clean`, simply replace the word `install` with
+`package-recursive`. When running the `portinstall` command simply
+add the `-p` (lower-case p) option before or after `--batch` to also
+have a package created.
+
+License
+-------
+This work is licensed under the Creative Commons Attribution-ShareAlike 3.0
+Unported License. To view a copy of this license, visit
+http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative
+Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA.
projects / working / Evergreen.git / commitdiff