Ruby Enterprise Edition Features Guide

To install REE, download either the source tarball or the Debian package from the REE website. The source tarball contains a cross-platform installer. Installation instructions are available on the download page.

Note that this installer is written in Ruby, and thus requires a Ruby interpreter to run. Because not all systems come with a Ruby interpreter by default, the source tarball also contains a number of precompiled Ruby interpreters for various platforms, with the purpose of running the installer. The installer script will automatically use a precompiled Ruby binary for the current platform, if available. Precompiled Ruby interpreters for the following platforms are included:

MacOS X and most FreeBSD systems already come with a Ruby interpreter by default.

So if you notice that the installer fails to start, please install Ruby first, then re-run the installer.

If you wish to install REE from source, but do not wish to use the included installer, or if the installer doesn’t work, then you can install REE manually. Please follow the instructions below.

Note that these instructions do not cover installing RubyGems.

In order to use RubyCocoa, the Ruby interpreter must be compiled with --enable-shared. By default, Ruby Enterprise Edition’s interpreter is not compiled with --enable-shared. You can compile the Ruby Enterprise Edition interpreter with this flag by passing -c --enable-shared to its installer, like this:

Please note that enabling --enable-shared will make the Ruby interpreter about 20% slower. It is for this reason that we don’t recommend enabling --enable-shared on server environments, although it’s fine for desktop environments.

In order to use Tcl/Tk with threading support, the Ruby interpreter must be compiled with --enable-pthread. By default, Ruby Enterprise Edition’s interpreter is not compiled with --enable-pthread. You can compile the Ruby Enterprise Edition interpreter with this flag by passing -c --enable-pthread to its installer, like this:

Please note that enabling --enable-pthread will make the Ruby interpreter about 50% slower. It is for this reason that we don’t recommend enabling --enable-shared on server environments, although it’s fine for desktop environments.

By default, REE installs itself into a directory in /opt. If you already had a Ruby interpreter installed (typically in /usr; let’s call this the system Ruby interpreter), then REE will have no effect on it: REE lives in isolation and in parallel to the system Ruby interpreter. This also means that:

To upgrade REE through the Debian package, just install the Debian package.

To upgrade REE through the source tarball, run the installer in the source tarball and specify the same destination prefix directory that REE is currently installed in. For example, if REE is currently installed in /opt/ruby-enterprise-20081215, then specify /opt/ruby-enterprise-20081215 in the upgrade source tarball’s installer.

If you installed REE through a Debian package, then uninstall the Debian package with dpkg or with apt-get.

If you installed REE through the source tarball, then you can uninstall it by deleting the directory in which REE is installed. For example, if REE was installed to /opt/ruby-enterprise-X.X.X (the default), then just delete that directory. It is for this reason why we recommend installing REE into its own directory.

Normally one would run a Ruby program by invoking the Ruby interpreter with a source file as its first argument:

To run the same program in REE, invoke the equivalent command in REE’s bin folder:

The same applies to other Ruby commands such as gem, irb and rake. For example, if you want to install Ruby on Rails for REE, invoke:

To use REE in combination with Phusion Passenger, you must run the Passenger Apache 2 module installer that’s associated with REE. The REE installer installs the Passenger gem by default, so you just have to run the Passenger Apache 2 module installer:

Then follow the instructions that the installer gives you.

It is possible to configure REE as the default Ruby interpreter, so that when you type ruby, gem, irb, rake or other Ruby commands, REE’s version is invoked instead of the system Ruby’s version.

To do this, you must add REE’s bin directory to the beginning of the PATH environment variable. This environment variable specifies the command shell’s command search path. For example, you can do this on the command-line:

Invoking export PATH=... on the command-line has no permanent effect: its effects disappear as soon as you exit the shell. To make the effect permanent, add an entry to the file /etc/environment instead. On Ubuntu Linux, /etc/environment looks like this:

Add REE’s bin directory to the PATH environment variable, like this:

By default, REE’s garbage collector is not copy-on-write-friendly, just like a stock Ruby interpreter. Copy-on-write-friendliness can be turned on during runtime by calling:

Note that Phusion Passenger automatically turns on the copy-on-write-friendly mode whenever it detects that it’s running in REE.

With the following method, one can check whether the garbage collector is in copy-on-write-friendly mode:

Ruby’s garbage collector tries to adapt memory usage to the amount of memory used by the program by dynamically growing or shrinking the allocated heap as it sees fit. For long running server applications, this approach isn’t always the most efficient one. The performance very much depends on the ratio heap_size / program_size. It behaves somewhat erratic: adding code can actually make your program run faster.

With REE, one can tune the garbage collector’s behavior for better server performance. It is possible to specify the initial heap size to start with. The heap size will never drop below the initial size. By carefully selecting the initial heap size one can decrease startup time and increase throughput of server applications.

Garbage collector behavior is controlled through the following environment variables. These environment variables must be set prior to invoking the Ruby interpreter.

The best settings varies from application to application. You should try experimenting with the values.

37signals uses the following settings in production:

Twitter uses the following settings in production:

Twitter’s settings mean:

Twitter claims that these settings give them about 20% to 40% average performance improvement, at the cost of slightly higher peak memory usage.

One can inspect various garbage collector statistics by calling certain methods. Statistics collection is disabled by default, so before one can obtain the statistics, statistics collection must be enabled by calling:

There’s a very minor performance penalty when statistics collection is enabled. Statistics collection can be disabled by calling:

The following methods are available for obtaining the collected statistics information:

The collected statistics information can be cleared by calling:

One can obtain various statistics about object allocation. Some of the statistics methods listed here require one to explicitly enable statistics collection, just like the garbage collection statistics methods.

The following methods are available:

caller_for_all_threads support is integrated into Phusion Passenger version 2.1 (which at the time of writing hasn’t been released yet). Upon sending a SIGQUIT signal to a Phusion Passenger backend process, it will print the backtrace of all threads to the Apache error log. This feature is also documented in the Phusion Passenger users guide.