Using Gentoo 2007.0, single-core x86 32-bit processor, emerge synced and world updated 2007/09/21.

Development with Evergreen SVN 1.2.0-rc4 and OpenSRF 0.9 last successfully tested 2007/09/21.

If you just want to test out Evergreen on Gentoo, you may be interested in the Gentoo VMWare image instructions.

As the root user, add the following USE flags to /etc/make.conf:

USE="-ldap apache2 mpm-prefork perl postgres gif jpeg png urandom web"

The opensrf user is required to start the OpenSRF services that constitute Evergreen.

1. As the root user, issue the following command to create the user and set the password (substitute your preferred password for password):

   useradd -m -p password opensrf

2. As the opensrf user, issue the following command to ensure that the Evergreen libraries will be able to be found:

   echo "export LD_LIBRARY_PATH=/openils/lib:/usr/local/lib/dbd" >> /home/opensrf/.bashrc

Note: As of 2007-10-11, the second step will no longer be required for the trunk version of Evergreen. Side note: this needs to be updated when a stable release incorporates the fix.

Gentoo relies on files in /etc/env.d/ to set the system environment. We will create our own file with settings required for Evergreen. Perform the following steps as the root user.

1. Open a new file (/etc/env.d/88evergreen) in a text editor. The name is actually rather arbitrary, but should start with two digits and must not conflict with any other files in the same directory.
2. Add the following lines to the file:

   LDPATH="/openils/lib"
   PATH="/openils/bin"
   PERL5LIB="/openils/lib/perl5:/usr/lib/perl5/site_perl/5.8.8/i686-linux:/usr/lib/perl5/vendor_perl/5.8.8/i686-linux/Bundle

   You might need to adjust the PERL5LIB variable to reflect your own architecture, and eventually a newer version of Perl.

3. Open another new file (/etc/env.d/89libdbi) in a text editor. Add the following line to the file:

   LDPATH="/usr/local/lib/dbd"

4. Run env-update to commit the corresponding changes to the system environment.

Perform the following steps as the root user:

1. Install the memcached package:

   emerge memcached

2. Restrict memcached to only listen to this machines' IP address (might only be necessary for a single-machine instance?) by editing the LISTENON variable in /etc/conf.d/memcached:

   LISTENON="127.0.0.1"

3. Start memcached at system boot:

   rc-update add memcached default

libmemcache provides a C API for putting and getting cached values from memcached. The current stable version of libmemcache in Gentoo (1.2.0) is subject to memory corruption problems; therefore, we install the pre-release unstable version of libmemcache (1.4.0-rc2). Perform the following steps as a root user:

echo "dev-libs/libmemcache ~x86" >> /etc/portage/package.keywords
emerge libmemcache

I installed PostgreSQL 8.2.4 on the advice of Mike Rylander. As PostgreSQL 8.0.13 is currently the "stable" version on Gentoo, I had to tell Gentoo to use the unstable version. Perform the following steps as the root user:

echo "dev-db/postgresql ~x86" >> /etc/portage/package.keywords
echo "dev-db/libpq ~x86" >> /etc/portage/package.keywords
emerge postgresql
emerge postgresql --config
rc-update add postgresql default
/etc/init.d/postgresql start

We need to create the database that Open-ILS will use:

createdb -U postgres -E UNICODE evergreen

We need to add tsearch2, table functions, and the plpgsql language to the Open-ILS database:

psql -U postgres evergreen
pg# \i /usr/share/postgresql/contrib/tsearch2.sql
pg# \i /usr/share/postgresql/contrib/tablefunc.sql
pg# \q
createlang -U postgres plpgsql evergreen
createlang -U postgres plperl evergreen
createlang -U postgres plperlu evergreen

You might as well change the password for the postgres user in the PostgreSQL database now. Note that this is not the system password stored in /etc/passwd; this is PostgreSQL's internal user authentication mechanism.

psql -U postgres evergreen
pg# alter user postgres password 'postgres';
pg# \q

Check the revision history of this page if you want instructions for using Wildfire as an alternative Jabber server.

Perform the following steps as the root user:

emerge ejabberd
rc-update add ejabberd default

Despite the emerge log, at least for ejabberd-1.1.3, there is no /etc/jabber/self-cert.sh script that gets installed. Instead, a certificate /etc/jabber/ssl.pem is created.

Change the /etc/jabber/ejabberd.cfg file to mostly correspond with the generic Open-ILS configuration instructions for ejabberd. Here's the configuration used on the Gentoo VMWare image: ejabberd.txt

Perform the following steps as the root user:

1. We'll emerge mod_perl and let that take care of all of the dependencies, including Apache 2 itself:

   emerge mod_perl

2. Enable mod_perl and SSL by editing /etc/conf.d/apache2:

   APACHE2_OPTS="-D PERL -D SSL -D PROXY -D CACHE"

3. Create a symbolic link from /etc/apache2/httpd.conf to /etc/apache2/apache2.conf to enable the Evergreen Apache modules to be installed and configured correctly:

   ln -sf /etc/apache2/httpd.conf /etc/apache2/apache2.conf

4. Enable the Apache process to read the /openils/var/web and /openils/var/cgi-bin files by editing /etc/apache2/httpd.conf to start the Apache process as the opensrf user:

   User opensrf
   Group opensrf

5. Copy eg.conf and eg_vhost.conf from ILS/Open-ILS/examples/apache/ into the /etc/apache2/vhosts.d/ directory.
6. Modify eg.conf to set the appropriate ServerName, ServerAlias, and Allow from settings. Here is the eg.conf file used in the Gentoo VMWare image: eg.conf.txt
7. Modify the eg_vhost.conf file SSLCertificateFile and SSLCertificateKeyFile settings to point to /etc/apache2/ssl/server.crt and /etc/apache2/ssl/server.key respectively. Modify CustomLog to point to a file location to which the apache user can write.
8. Here is the eg_vhost.conf file used in the Gentoo VMWare image: eg_vhost.conf.txt
9. Add startup.pl to /etc/apache2/vhosts.d/eg.conf: Here is the startup.pl file used in the Gentoo VMWare image: startup.pl.txt

Gentoo doesn't provide all of the modules available in CPAN, and certainly not the most interesting ones used by Open-ILS.

We'll use Gentoo's Perl build, but go with CPAN for the rest of the modules.

1. The Net::ZOOM Perl module requires yaz version 2.1.50 or higher. At the moment, the ebuild for yaz is 2.1.42 - so we have to build yaz from source. Perform these steps as a regular user, such as opensrf:

   wget http://ftp.indexdata.dk/pub/yaz/yaz-2.1.56.tar.gz
   tar xzf yaz-2.1.56.tar.gz
   cd yaz-2.1.56
   ./configure
   make

2. Perform the following step as the root user:

   make install

3. We depend on the aspell-en ebuild for the Text::Aspell Perl module. If you are starting from Gentoo 2007.0, you might run into a blocking ebuild that requires you to first unmerge aspell-en, then re-emerge it as the root user:

   emerge --unmerge aspell-en
   emerge aspell-en

4. We depend on the spidermonkey (1.6 or higher) ebuild for the JavaScript::SpiderMonkey Perl module. spidermonkey-1.6 is the stable ebuild on the ~x86 architecture; other architectures may have to use an unstable ebuild or build spidermonkey from source. On ~x86, perform the following step as the root user:

   emerge spidermonkey

5. Now we can install the CPAN modules as the opensrf user. We set the makepl_arg parameter in CPAN to install all of these modules into the /openils/ directory structure, so that we can avoid conflicting with the core versions of the Perl modules that we might have installed via ebuilds. Perform the following steps as the root user:

   mkdir -p /openils/lib/perl5
   chown -R opensrf:opensrf /openils

6. Perform the following steps as the opensrf user:

export PERL5LIB=/openils/lib/perl5
perl -MCPAN -e shell
shell> o conf makepl_arg 'PREFIX=/openils LIB=/openils/lib/perl5'
shell> o conf commit
shell> install Bundle::CPAN
shell> reload cpan
shell> install Cache::Memcached Class::DBI::AbstractSearch
shell> install DateTime DateTime::Format::ISO8601 DateTime::TimeZone
shell> install DBI DBD::Pg Email::Send GD::Graph3d Log::Log4perl
shell> install JavaScript::SpiderMonkey JSON::XS
shell> install XML::LibXML XML::LibXSLT XML::Simple
shell> install MARC::Record MARC::Charset MARC::File::XML
shell> install Net::Server::PreFork Net::Z3950::ZOOM
shell> install Template Text::Aspell UNIVERSAL::require Unix::Syslog
shell> install Text::CSV Text::CSV_XS Spreadsheet::WriteExcel Tie::IxHash

We need Net::Jabber to register users with ejabberd. The gsasl ebuild is required for authentication. I found that I had to select no when asked if I wanted to install the optional GSSAPI module for XML::Stream, one of its underlying modules, to avoid severe test failure. I stopped ejabberd before installing this module to avoid any port conflicts during the Net::Jabber tests. Finally, a few Net::Jabber tests failed anyways, so I forced the install of that module.

If the Net::Jabber install fails for you as well:

1. Perform the following steps as the root user:

   /etc/init.d/ejabberd stop
   emerge gsasl

2. Perform the following steps as the opensrf user:

   perl -MCPAN -e shell
   shell> install Authen::SASL XML::Stream Net::XMPP
   shell> force install Net::Jabber

The generic instructions worked well using libdbi-0.8.2 and libdbi-drivers-0.8.2-1 releases. You do not need to specify a directory for the –with-pgsql option because we're using the ebuild version of PostgreSQL, so the libdbi-drivers step looks like:

./configure --with-pgsql-dir --disable-docs --with-pgsql --enable-libdbi && make all install

As of Evergreen 1.2.0, you have to download and install OpenSRF separately from Evergreen. Perform the following steps as the opensrf user:

1. Download OpenSRF:

   wget http://open-ils.org/downloads/OpenSRF-0.9.tar.gz

2. Extract OpenSRF:

   tar xzf OpenSRF-0.9.tar.gz

3. Change directories into the OpenSRF directory:

   cd OpenSRF-0.9

4. Open install.conf in a text editor and set the default Gentoo settings for make configuration:

   export APXS2=/usr/sbin/apxs2
   export APACHE2_HEADERS=/usr/include/apache2
   export APR_HEADERS=/usr/include/apr-1/
   export LIBXML2_HEADERS=/usr/include/libxml2/

5. Build OpenSRF:

   CFLAGS=-D_LARGEFILE64_SOURCE make

6. Install OpenSRF by performing the following step as the root user:

   make install

We have to register the users listed in opensrf_core.xml with our Jabber server. OpenSRF includes a simple script to do this based on Net::Jabber. In our case, we will register two users, "osrf" and "router", each of which uses the password "osrf":

# starting in the OpenSRF directory
cd examples
perl register.pl localhost 5222 osrf osrf
perl register.pl localhost 5222 router osrf

Perform the following steps as the opensrf user:

1. Download Evergreen:

   wget http://open-ils.org/downloads/Evergreen-ILS-1.2.0-rc4.tar.gz

2. Extract Evergreen:

   tar xzf Evergreen-ILS-1.2.0-rc4.tar.gz

3. Change directories into the Evergreen directory:

   cd Evergreen-ILS-1.2.0-rc4

4. Set the configuration for your system; aside from the database name, username, and password, you should only have to change the following settings on Gentoo:

   Apache2 apxs binary           = /usr/sbin/apxs2
   Apache2 headers directory     = /usr/include/apache2
   Apache2 APR headers directory = /usr/include/apr-1
   Libxml2 headers directory     = /usr/include/libxml2

5. Due to some confusion caused by apxs, make install will fail if it cannot find /etc/apache2/apache2.conf. Perform the following hack as the root user to fix that problem:

   ln -sf /etc/apache2/httpd.conf /etc/apache2/apache2.conf

6. Build Evergreen as the opensrf user:

   CFLAGS=-D_LARGEFILE64_SOURCE make

7. Install Evergreen as the root user:

   make install

8. Change permissions on the Evergreen directories to enable the system to run as the root user:

   chown -R opensrf:opensrf /openils
   chmod -R +x /openils/var/cgi-bin

9. Edit the /etc/apache2/httpd.conf file to correct the LoadModule directives that were added for the mod_xmlent and osrf_json_gateway modules. apxs2 mistakenly tells Apache to load the modules from the lib/apache2/modules/ directory, when (as of Apache 2.2.4 on Gentoo) the prefix should just be modules/. As the root user, adjust the lines to read as follows:

   LoadModule osrf_json_gateway_module modules/osrf_json_gateway.so
   LoadModule xmlent_module      modules/mod_xmlent.so

10. Create symbolic links to support Windows staff clients and versionless staff clients as the opensrf user:

    cd /openils/var/web/xul/
    rm HEAD
    ln -sf /root/Evergreen-ILS-1.2.0-rc4/Open-ILS/xul/staff_client/build/ HEAD
    ln -sf HEAD sc_v100_rc2
    ln -sf HEAD rel_1_2_0_rc4

1. Become the opensrf user:

   su - opensrf

2. Run the osrf_ctl.sh script to start up all of the services. We start the services individually because there is a race condition that can affect the C services if the Perl services have not completely finished initializing:

   /openils/bin/osrf_ctl.sh -c /openils/conf/opensrf_core.xml -a start_router
   /openils/bin/osrf_ctl.sh -c /openils/conf/opensrf_core.xml -a start_perl
   /openils/bin/osrf_ctl.sh -c /openils/conf/opensrf_core.xml -a start_c

3. (Required only once): Run the autogen.sh script to generate the JavaScript and OrgTree HTML files:

   cd /openils/bin
   autogen.sh /openils/conf/opensrf_core.xml

4. Become the root user and start Apache (which now depends on the open-ils services before it can start successfully):

   exit
   su -
   /etc/init.d/apache2 start