From: Jason Stephenson Date: Wed, 28 Mar 2012 01:28:22 +0000 (-0400) Subject: Update docs/eg_freebsd.txt to include all instructions for FreeBSD. X-Git-Url: https://old-git.evergreen-ils.org/?a=commitdiff_plain;h=e8783c6f95514d5702adc4965b713e55c5aef625;p=working%2FEvergreen.git Update docs/eg_freebsd.txt to include all instructions for FreeBSD. Signed-off-by: Jason Stephenson --- diff --git a/docs/eg_freebsd.txt b/docs/eg_freebsd.txt index 199a4b50f6..2d90faba72 100644 --- a/docs/eg_freebsd.txt +++ b/docs/eg_freebsd.txt @@ -1,40 +1,74 @@ -= 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] ------------------------------------------------------------------------------ @@ -44,16 +78,12 @@ portinstall --batch \ 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 \ @@ -64,17 +94,16 @@ portinstall --batch \ 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 \ @@ -91,23 +120,23 @@ portinstall --batch \ 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 \ @@ -131,10 +160,8 @@ portinstall --batch \ 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 \ @@ -142,8 +169,8 @@ portinstall --batch \ 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/ @@ -165,11 +192,15 @@ cpan \ 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 @@ -178,8 +209,6 @@ 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" @@ -190,24 +219,132 @@ Create the opensrf user [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 @@ -222,19 +359,15 @@ Start Memcached /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 ------------------------------------------------------------------------------ @@ -250,7 +383,6 @@ su opensrf 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 ------------------------------------------------------------------------------ @@ -285,11 +417,8 @@ CFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib" ./configure \ --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 @@ -297,10 +426,37 @@ su opensrf 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. `` = use the private Jabber `opensrf` user + 2. `` = use the public Jabber `opensrf` user + 3. `` = use the public Jabber `router` user + 4. `` = 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/. @@ -308,51 +464,33 @@ 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 ~~~~~~~~~~~~~~~ @@ -456,107 +594,40 @@ Start rsyslogd /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.