Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Web server for Rails/Rack applications built upon JRuby::Rack and Apache Tomcat
Fetching latest commit...
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Trinidad allows you to run Rails or Rack applications within an embedded Apache Tomcat container.


$ jruby -S gem install trinidad

Quick Start

$ cd myapp
$ jruby -S trinidad


If you use Bundler, you might want to add Trinidad to your Gemfile:

gem 'trinidad', :require => nil


If you have Trinidad in your Gemfile you can start it with rails server:

$ rails s trinidad

or simply, if you prefer not to use the Rack handler, use:

$ trinidad


$ ruby app.rb -s Trinidad

or configure your application to always use Trinidad:

require 'sinatra'
require 'trinidad'

configure do
  set :server, :trinidad


You can pass the server name as an option to rackup:

$ rackup -s trinidad

Or you can set Trinidad by default in your file:

#\ -s trinidad


Trinidad allows you to configure parameters from the command line, the following is a list of the currently supported options (try trinidad -h):

  * -p, --port PORT               =>  port to bind to.
  * -e, --env ENVIRONMENT         =>  rails environment.
  * -c, --context CONTEXT         =>  application context path.
  * --lib, --jars LIBS_DIR        =>  directory containing jars.
  * --classes CLASSES_DIR         =>  directory containing classes.
  * -r, --rackup [RACKUP_FILE]    =>  run a provided rackup file instead of a rails application, by default it's
  * --public PUBLIC_DIR           =>  specify the public directory for your application, by default it's 'public'.
  * -t, --threadsafe              =>  shortcut to work in threadsafe mode. Setting jruby_min_runtimes and jruby_max_runtimes to 1 in the configuration file the server behaves as the same way.
  * -l, --load EXTENSION_NAMES    =>  load extensions to use their command line options.
  * --address HOST                =>  set the server host.
  * -g, --log LEVEL               =>  set the log level, default INFO.
  * --apps APPS_BASE_DIRECTORY    =>  set the applications base directory.

You can also specify a default web.xml to configure your web application. By default the server tries to load the file config/web.xml but you can change the path by adding the option default_web_xml within your configuration file.

YAML Configuration

The server can also be configured from a .yml file. By default, if a file is not specified, the server tries to load config/trinidad.yml. Within this file you can specify options available on the command line and tune server settings or configure multiple applications to be hosted on the server.

Advanced configuration options are explained in the wiki:

$ jruby -S trinidad --config my_trinidad.yml
  port: 4242

Ruby Configuration

As an alternative to the config/trinidad.yml file, a .rb configuration file might be used to setup Trinidad. It follows the same convention as the yaml configuration - the file config/trinidad.rb is loaded by default if exists.

Trinidad.configure do |config|
  config.port = 4242
  config.address = ''


As you might notice on your first trinidad the server uses standard output :

kares@theborg:~/workspace/trinidad/MegaUpload$ trinidad -p 8000 -e staging
Initializing ProtocolHandler ["http-bio-8000"]
Starting Servlet Engine: Apache Tomcat/7.0.28
Starting ProtocolHandler ["http-bio-8000"]
Context with name [/] has started rolling
Context with name [/] has completed rolling

It also prints warnings and error messages on error output, while application specific log messages (e.g. logs from Rails.logger) go into the expected file location at log/{environment}.log.

Application logging performs daily rolling out of the box and only prints messages from an application to the console while it runs in development mode.

Please note that these logging details as well as the logging format will be configurable with trinidad.yml/.rb within the next 1.4.x release.

Hot Deployment

Trinidad supports monitoring a file to reload applications, when the file tmp/restart.txt is updated (e.g. touch tmp/restart.txt), the server reloads the application the file belongs. The file monitor can be customized with the monitor configuration option.

Since version 1.4.0 Trinidad supports 2 reload strategies :

  • restart (default) synchronous reloading (exposed by Tomcat). This strategy pauses incoming requests while it reloads the application and than serves them once ready (or timeouts if it takes too long). It has been chosen as the default strategy since 1.4.0 due it's more predictable memory requirements.

  • rolling "zero-downtime" (asynchronous) reloading strategy similar to Passenger's rolling reloads. This has been the default since 1.1.0 up till Trinidad version 1.3.0. If you use this you should account that while rolling memory requirements for the JVM might increase quite a lot since requests are being served and there's 2 versions of your application loaded at the same time.

Configure the reload strategy per web application or globally e.g. :

  port: 8080
  environment: production
  reload_strategy: rolling

Virtual Hosts

It's possible to use Trinidad with multiple hosts and load the applications under them automatically. Please remember that each host must have its applications in a different directory.

Trinidad.configure do |config|
  config.hosts = {
    # applications_path => host_name_list 
    # (first one is the real host name, the other ones are aliases)
    'app_local' => ['localhost', ''],
    'apps_lol'  => ['lolhost', 'lol'],
    'apps_foo'  => 'foo'

If applications are configured via the web_apps section, the host for each app can be added with the hosts key under each application. If several applications belong to the same host put them under the same directory and specify the name of the host for each one e.g. :

Trinidad.configure do |config|
  config.web_apps = {
    :mock1 => {
      :web_app_dir => 'rails_apps/mock1',
      :hosts       => ['', '']
    :mock2 => {
      :web_app_dir => 'rails_apps/mock2',
      :hosts       => ''
    :mock3 => {
      :web_app_dir => 'rack_apps/mock3',
      :hosts       => ['', '']


Trinidad allows to extend itself with more (not just Tomcat) features, here is a list of the available extensions that are "officially supported":

You can find further information on how to write extensions in the wiki:


Copyright (c) 2011-2012 David Calavera. See LICENSE for details.

Something went wrong with that request. Please try again.