Advanced configuration - trinidad/trinidad GitHub Wiki

Trinidad can be configured through a trinidad.yml (or trinidad.rb) file passed using the --config option when you run the server, if you don't specify the --config option name it will look for config/trinidad.{yml|rb} by default.

$ jruby --1.9 -S trinidad --config /etc/default/trinidad/config.yml

This page tries to describe supported configuration options in a detail.

## Server Options
  • port - port where Trinidad will run
  • http - options to configure the HTTP connector, see HTTP Connector
  • ssl - options to configure SSL, see Secure Socket Layer
  • ajp - options to configure the AJP connector, see AJP Configuration
  • address - server's host name (localhost by default)
  • apps_base - directory where several applications to be run live (in sub-directories)
## Application Options
  • environment - global environment that every deployed Rack (Rails) application will use (unless overiden by the concrete app configuration)
  • jruby_min_runtimes - minimum (J)Ruby runtimes to create, runtimes will be pooled as requests come in (for more predictable request times consider setting the min to the same value as max - ensuring multiple application runtimes are booted up front when the server starts)
  • jruby_max_runtimes - maximum Ruby runtimes allowed to be created (set to min and max to 1 if your application is thread-safe, for a Rails app setting config.threadsafe! is detected)
  • jruby_compat_version - "1.8", "1.9" or "2.0" (depending on JRuby version used) NOTE that you might set different values for applications deployed on a single server
  • context_path - server URL path where the application is located e.g. "/app1"
  • root_dir - directory where the application is located (assuming a single application to be run)
  • rackup - system path to the rackup (config.ru) file, assumed to be relative to root_dir
  • public - system path the the public directory, might be specified relative to root_dir
  • web_apps - option to configure multiple web applications located in the same parent directory
  • java_lib - directory where Trinidad will look for Java .jar archives (lib/java by default)
  • java_classes - directory where Trinidad will look for compiled Java classes (lib/java/classes by default)
  • default_web_xml - default web.xml JavaEE deployment descriptor that every application will use
  • reload_strategy - reload strategy to use (the default strategy "restarts" the application context)
  • logging - application specific trinidad logging

How to load Java libraries with the application

By default, Trinidad loads any Java library packed as a .jar file if placed in the lib/java directory along with your application. In the same way, it loads any Java .class files from the lib/java/classes directory. These options can be changed in the configuration or from the command line with --java_lib and --java_classes.

How to run a applications as thread-safe

A Rails 4.x application is assumed to be thread-safe when the following options are set :

  # Code is not reloaded between requests.
  config.cache_classes = true
  # Eager load code on boot.
  config.eager_load = true

Rails (framework) code itself is thread-safe, but you might need to understand the gist of the gems you're using whether there aren't any non-thread-safe assumptions being made, same goes for your application code if you've shared state across requests.

NOTE that MRI "thread-safe" code does not necessary imply (real) JRuby thread-safe-ty since MRI uses a GIL.

To run a Rails 3.x / 2.3 application in a thread-safe manner you need to configure the appropriate environment.rb as threadsafe!, i.e. in config/production.rb set :

config.threadsafe!

Then run Trinidad with that proper environment set (trinidad -e production or use the environment: configuration option).

NOTE the thread-safe detection is performed by parsing environment files since the decision needs to be made before your application starts booting - thus can not be 100% accurate e.g. if you use conditional logic to decide whether to enable config.threadsafe!. In most cases it's best to override the detection and turn it on/off in Trinidad's configuration :

---
  address: localhost
  # ...
  threadsafe: true # or set per web-app
  # alternatively setting :
  #jruby_min_runtimes: 1
  #jruby_max_runtimes: 1
  # has the same effect ...

JRuby-Rack assumes (non-Rails) Rack applications to be thread-safe by default, if you're application is not thread-safe and you'd like to use runtime pooling specify the jruby_min_runtime and jruby_max_runtimes options (as >= 1).

How to run multiple applications within the same Trinidad process

The web_apps option allows us to configure several Rails applications within the same Tomcat container. One creates a section under this option for each application - the "global" application configuration gets sensibly inherited and one might override options as needed.

If the context_path option is not present it takes the key of the section as the context path (but if the key of that section is default the context path with be "/").

Following is an example of how to configure 3 applications running side by side:

---
  environment: production # environment gets inherited for each application
  web_apps:
    default: # context path is '/' (running at http://localhost:3000/)
      root_dir: 'web_apps/mock'
    mock1:   # context path is '/mock1' (root at http://localhost:3000/mock1)
      root_dir: 'web_apps/mock1'
    mock2:
      root_dir: 'web_apps/mock2'
      context_path: /mock22 # serving at http://localhost:3000/mock22

Alternatively when apps_base is set (defaults to a directory named "webapps") every directory under this base directory is assumed to be an application and gets deployed using the configured defaults.

Following the previous example - all applications located in the same directory and assuming no other (non-application) directories are present, we can run those on Trinidad by running :

jruby -S trinidad --apps web_apps

and Trinidad will load those three applications using the directory names as context paths following the same rules as before:

## Configuration Template

this configuration file contains all options that can be set, you can use it as a template but it will likely need to be edited/reviewed for your setup:

---
  address: localhost # set to '*' to bind to all interfaces
  port: 3000 # port where Trinidad is running
  http: # HTTP connector setup
    acceptCount: 100
    maxThreads: 200
    maxKeepAliveRequests: 100
    # @see https://github.com/trinidad/trinidad/wiki/HTTP-Connector
  #ssl: # SSL configuration
    #port: 3443
    # @see https://github.com/trinidad/trinidad/wiki/Secure-Socket-Layer
  #ajp: # AJP configuration
    #port: 8009
    # @see https://github.com/trinidad/trinidad/wiki/AJP-Configuration
  #apps_base: # directory where several applications are located
  #
  # Begin: Configuration options that can be overrided per web-application
  #
  #environment: production # specify with `trinidad -e production`
  threadsafe: true # overrides config.threadsafe! detection
  #jruby_min_runtimes: 1 # min number of JRuby runtimes to use
  #jruby_max_runtimes: 1 # max number of JRuby runtimes to use
  #jruby_compat_version: 1.9 # or 1.8 by default uses the same as trinidad is running
  context_path: / # default context path
  root_dir: "." # system path where the application is located, by default is PWD
  rackup: config.ru # rackup script if you are running a (non-Rails) Rack application
  public: public # system path (relative to root) where your public files are located
  # If you do not put a web-server in front of Trinidad you might tune asset caching :
  #public: 
  #  root: public # same as the above "public: public" setting
  #  aliases: # allows to "link" other directories into the public root e.g. :
  #    /home: /var/local/www
  #  cached: true # enable (in-memory) asset caching on for env != 'development'
  #  cache_ttl: 5000 # cache TTL in millis (might want to increase this)
  #  cache_max_size: 10240 # the maximum cache size in kB
  #  cache_object_max_size: 512 # max size for a cached object (asset) in kB
  java_lib: lib/java # directory where libraries packed as jars can be found
  java_classes: lib/java/classes # directory where compiled java classes can be found
  default_web_xml: config/trinidad-web.xml # if you are using a custom web.xml
  reload_strategy: default # alternatively you might use "rolling"
  #
  # End: Configuration options that can be overrided per web-application
  #
  extensions: # if you are using any Trinidad extension
    #daemon: # sample daemon extension
      #pid_file: # pid file
      #jvm_args: # additional arguments for the thread that runs the daemon
  #
  web_apps: # if running more than one application or using web apps extensions
    default: # by default the name is used as the context path, 'default' means the root path '/'
       # here you can override any already configured options or add new ones e.g. :
       extensions:
          mysql_dbpool:
            jndi: 'jdbc/BarDB'
            url: 'localhost:3306/bar'
            username: root
            password: pass
            maxActive:  100 # maximum number of connections managed by the pool
            initialSize: 10 # initial number of connections created in the pool
            maxWait:  10000 # ms the pool waits for a connection to be returned
    # configuring another application :
    foo_app:
      context_path: /foo # this will be the path rather than '/foo_app'
      web_app_dir: /var/www/foo_app # system path where this application is located
    # configure logging for another application
    logging_app:
      logging:
        use_parent_handlers: true # use std out/err
        file: nil # no file

The template is not complete e.g. there's a few more options available on Java Integration.

More Configuration

HTTP Connector

AJP-Configuration

Secure-Socket-Layer

Java Integration

Performance-Tuning

⚠️ **GitHub.com Fallback** ⚠️