Building
From Open Siddur Project Development Wiki
This page contains notes about the installation process for eXist XML db containing Open Siddur code:
Contents |
Obtaining the source code
The Open Siddur source code is stored in a repository on Github. To obtain the source:
$ git clone git://github.com/opensiddur/opensiddur.git
Non-committers are given read-only access to the repository. Commit access is granted to those who make code contributions to the project via the discussion list or through contact with the developers. To make local changes, you may fork the project. To push back features, set up a pull request.
Compiling the full source code assumes you have the following programming tools:
- Basic UNIX utilities that are usually in the binutils package (cp, rm, a shell)
- rsync incremental file transfer application
- git distributed revision control system
- Subversion source code management system (svn). Some of our dependencies use subversion.
- GNU make
- A Java Development Kit from Sun or OpenJDK, version 1.6, or above.
- ant build tool for Java
- Installing a copy of the database using our installer requires Python 2.6 or higher.
- libxml2 (for xmllint and xsltproc); and a Perl programming environment are expected to be on most development systems, or are easily downloadable. You will also need the lxml Python library.
Under most (all?) GNU/Linux distributions, the required utilities that we don't ship are installable as packages from the standard software repositories.
Under Apple OS X, the XCode development kit includes the required utilities. XCode 4 and above includes git.
Under Microsoft Windows, you can get a Unix-like development environment from Cygwin. Note that the build process is not yet working on Cygwin. Unless you want to struggle (and if you do, tell us how you did it!), a real Unix or Linux environment (even a Linux VM) is much preferred.
Additional setup
Some development does not require these additional steps. You must only follow these steps if you want to compile the schema or schema documentation on your own, or you want to validate JLPTEI against the schema.
Symbolic link (do not copy) the following files to somewhere in the path (note: all paths are relative to trunk). These files must be in the same directory as their jar.
- lib/jing
- lib/trang
- lib/saxon
- lib/absolutize
For example, assuming your OpenSiddur code is in the directory $SRC:
$ ln -s $SRC/lib/trang /usr/local/bin/trang
You may need to have root access (or use sudo to gain root access) to write to /usr/local.
Installation
We assume that you have downloaded our sources from our git repository (see Intro to hacking). Unless otherwise noted, all commands should be run from the root of the source code branch in your working copy (trunk). All active development is taking place in the master branch.
By default, the database will install to /usr/local/eXist. To change the destination directory, edit Makefile.local and add a line:
EXIST_INSTALL_DIR = <your choice of directory>
It is recommended that you change the default administrative password in Makefile.local, by adding the line:
ADMINPASSWORD = <your choice of password>
(note: this setting will only work in v0.4.5 under development, other versions will prompt for the admin password)
To begin the installation, type:
make db-install
The installer will ask for an administrative user password, which you will need to remember!
To install the Westminster Leningrad Codex Tanach into your database, use
make db-install-wlc
Running a server (Debian and derivatives)
These instructions should work for Debian, Ubuntu, and other Debian derivatives. For other Linux systems and Windows, there are other procedures.
To start eXist at bootup:
- Make a new user/group for eXist to run as:
/sbin/adduser exist exist
- Change ownership of exist to that user (note: changing ownership should be done before you start the database the first time)
chown -R exist:exist /usr/local/eXist
- Make the exist group able to read and write all files in eXist:
chmod -R g+rw /usr/local/eXist
- Edit the wrapper script /usr/local/eXist/tools/wrapper/bin/exist.sh to set your RUN_AS_USER
- Edit the wrapper configuration to set appropriate memory settings. To /usr/local/eXist/tools/wrapper/conf/wrapper.conf, add the following line (in the "Java additional parameters" section)
wrapper.java.additional.6=-Xss16m
- and edit the line
# Maximum Java Heap Size (in MB) wrapper.java.maxmemory=128
to use a higher value, such as
wrapper.java.maxmemory=512
- Symbolic link the wrapper script into /etc/init.d
ln -s /usr/local/eXist/tools/wrapper/bin/exist.sh /etc/init.d/exist
- Add the wrapper script to /etc/rc?.d using /usr/sbin/update-rc.d
/usr/sbin/update-rc.d exist start 20 2 3 4 5 . stop 80 0 1 6 .
- If you want your user login to be able to modify eXist's configuration, add yourself to the exist group
Testing and use
Once the installer is complete, the database can be started by running (assuming it's installed at /usr/local/eXist):
/usr/local/eXist/bin/startup.sh
(or, if you use the startup wrapper:
/etc/init.d/exist start
)
If you can go to:
- http://localhost:8080/ and see a directory listing from eXist, eXist is installed correctly and running.
- http://localhost:8080/code/apps/compiler and see a listing of Tanach books and chapters, the database has the WLC installed the correctly.
- http://localhost:8080/code/apps/builder and see a welcome screen, the applications are working correctly.
- http://localhost:8080/code/api and see an HTML list with API functions, the API is working correctly.
Database shutdown
The database should always be shut down properly!
The database can be shut down by running:
/usr/local/eXist/bin/shutdown.sh -p Your admin password -l xmldb:exist://localhost:8080/xmlrpc/db
The database should be shutdown properly using this command; otherwise, database corruption may result.
If you use the service wrapper, you may shutdown the database using:
/etc/init.d/exist stop
Uninstalling
To remove the installed database, use:
make db-uninstall
Troubleshooting
Stack space
If your server runs out of stack space (you get errors while trying to compile), edit /usr/local/eXist/bin/functions.d/eXist-settings.sh and change
JAVA_OPTIONS="-Xms128m -Xmx512m -Dfile.encoding=UTF-8";
to:
JAVA_OPTIONS="-Xms128m -Xmx512m -Xss64m -Dfile.encoding=UTF-8";
in the set_java_options() function (around line 83 in r768).
If you're running out of memory, try -Xmx1024m
After changing any of these settings, restart your server.
Unexplained errors during run in the web browser
Turn off any Safari Extensions or Greasemonkey scripts that might be injecting code into the app's web pages.
Reinstalling
In order to do a clean reinstall, you have to remove the entire installation of the database. If you installed your database to /usr/local/eXist, use
$ rm -fr /usr/local/eXist
before re-running
$ make db-install
make clean will not uninstall an installed copy of the database.
