{"id":13463312,"url":"https://github.com/trinidad/trinidad","last_synced_at":"2025-03-25T06:31:49.494Z","repository":{"id":56897118,"uuid":"1497283","full_name":"trinidad/trinidad","owner":"trinidad","description":"Web server for Rails/Rack applications built upon JRuby::Rack and Apache Tomcat","archived":true,"fork":false,"pushed_at":"2016-07-14T11:45:12.000Z","size":93175,"stargazers_count":442,"open_issues_count":22,"forks_count":33,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-02-24T12:07:06.711Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trinidad.png","metadata":{"files":{"readme":"README.md","changelog":"History.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-03-18T17:58:12.000Z","updated_at":"2025-02-23T12:19:55.000Z","dependencies_parsed_at":"2022-08-21T01:50:53.302Z","dependency_job_id":null,"html_url":"https://github.com/trinidad/trinidad","commit_stats":null,"previous_names":[],"tags_count":74,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trinidad%2Ftrinidad","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trinidad%2Ftrinidad/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trinidad%2Ftrinidad/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trinidad%2Ftrinidad/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trinidad","download_url":"https://codeload.github.com/trinidad/trinidad/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245339032,"owners_count":20599139,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T13:00:50.537Z","updated_at":"2025-03-25T06:31:48.493Z","avatar_url":"https://github.com/trinidad.png","language":"Ruby","funding_links":[],"categories":["Provision, Deploy \u0026 Host","Web Servers"],"sub_categories":["Web servers"],"readme":"# Trinidad\n\nTrinidad allows you to run Rails and/or Rack applications within an embedded\nTomcat container. Apache Tomcat (formerly also Jakarta Tomcat) is an open source\nweb server and Servlet container with a long history that dates back to the\nprevious millenia.\n\nTrinidad's goals with bringing Tomcat into JRuby land are mostly the following :\n\n- **flexibility** especially in terms of configuration it allows you to tune\n  (almost) everything from a simple *trinidad.yml* (or .rb) configuration file\n- **portability** there's no vendor lock-in as we use `JRuby::Rack`, thus even\n  if you do some Java integration or use it's Rack Servlet extensions you're\n  still able to migrate to a standalone Tomcat or any other Servlet container\n- easy Java integration (just in-case you need it, it's there)\n- **extensions** such as connection pooling (sharing pools between deployed\n  Rails apps) and (threaded) worker adapters for `Resque` and `Delayed::Job`\n\n## Installation\n\n[![gem version](https://badge.fury.io/rb/trinidad.png)](http://rubygems.org/gems/trinidad)\n[![dependency status](https://gemnasium.com/trinidad/trinidad.png)][1]\n\n```\n$ jruby -S gem install trinidad\n```\n\n**NOTE:** please use **1.5.0.B2** `gem install trinidad --pre`, esp. on JRuby 9K,\nas Trinidad 1.4 will no longer receive Tomcat (7.0.x) security updates.\n\nTrinidad 1.4 requires (and supports) JRuby 1.6.8 or later (latest 1.7.x recommended).\n\n## Quick Start\n\n```\n$ cd a-rails-app\n$ jruby -S trinidad\n```\n\n## Setup\n\nIf you use Bundler, you might want to add Trinidad to your *Gemfile* :\n\n```\ngem 'trinidad', :require =\u003e nil\n```\n\nHowever this is not absolutely necessary, you might simply `gem install trinidad`\nand than run `trinidad` - keep in mind a server is not an application dependency.\n\n### Rails\n\nTrinidad supports the same Rails version as the JRuby-Rack it founds on (or is\nspecified/locked in your *Gemfile*), which are **4.x**, **3.x** and even **2.3**\nfor JRuby-Rack 1.1.x (and the up coming 1.2). Merb is not supported.\n\n```\n$ trinidad\n```\n\nor if you prefer to use the Rack handler (e.g. for development) use :\n\n```\n$ rails s trinidad\n```\n\nPlease note all configuration options will work using the Rack handler mode, you\nshould usually only use it for development/tests and run `trinidad` on production.\n\n### Sinatra\n\n```\n$ ruby app.rb -s Trinidad\n```\n\nor configure your application to always use Trinidad :\n\n```ruby\nrequire 'sinatra'\nrequire 'trinidad'\n\nconfigure do\n  set :server, :trinidad\nend\n```\n\n### Rack\n\nTrinidad auto-detects a plain-old Rack application (if there's a *config.ru*) :\n\n```\n$ trinidad\n```\n\nYou can as well pass the server name to `rackup` to start the Rack handler :\n\n```\n$ rackup -s trinidad\n```\n\nOr you can set Trinidad as the default server in your *config.ru* file :\n\n```\n#\\ -s trinidad\n```\n\nTrinidad solves the Rack \"chicken-egg\" problem when booting from a *rackup* file\nthe same way as JRuby-Rack (since it boots all applications), that is :\n- if a Bundler *Gemfile* is detected, it first does a *bundle/setup* to load rack\n- otherwise the rack (gem) version might be specified using a magic comment in\n  *config.ru* as `# rack.version: ~\u003e1.4.0` (or the latest installed gem is used)\n\n**NOTE:** We recommend to use the plain `trinidad` mode for running apps\n(in production), since it supports runtime pooling while the \"rackup\" mode does\nnot, it also provides you with better Java integration possibilities.\n\nAlso note that Trinidad does not mimic JRuby-Rack's (1.1.x) backwards compatible\nbehavior of starting a pool for Rails but booting a thread-safe runtime for\nplain Rack applications by default. Runtime pooling is the default with Trinidad\n**1.4** and stays the same no matter the type of the application. This has\n**changed in Trinidad 1.5** and it assumes thread-safe applications by default.\n\nAll major rack versions (\u003c 2.0) are expected to be working fine with Trinidad.\n\n## Configuration\n\nTrinidad allows you to configure parameters from the command line, the following\nis a list of the currently supported options (try `trinidad -h`):\n\n```\n  * -d, --dir ROOT_DIR            =\u003e  web application root directory\n  * -e, --env ENVIRONMENT         =\u003e  rack (rails) environment\n  * --rackup [RACKUP_FILE]        =\u003e  rackup configuration file\n  * --public PUBLIC_DIR           =\u003e  web application public root\n  * -c, --context CONTEXT         =\u003e  application context path\n  * --monitor MONITOR_FILE        =\u003e  monitor for application re-deploys\n  * -t, --threadsafe              =\u003e  force thread-safe mode (use single runtime)\n  * --runtimes MIN:MAX            =\u003e  use given number of min/max jruby runtimes\n  * -f, --config [CONFIG_FILE]    =\u003e  configuration file\n  * --address ADDRESS             =\u003e  host address\n  * -p, --port PORT               =\u003e  port to bind to\n  * -s, --ssl [SSL_PORT]          =\u003e  enable secure socket layout\n  * -a, --ajp [AJP_PORT]          =\u003e  enable the AJP web protocol\n  * --java_lib LIB_DIR            =\u003e  contains .jar files used by the app\n  * --java_classes CLASSES_DIR    =\u003e  contains java classes used by the app\n  * -l, --load EXTENSION_NAMES    =\u003e  load options for extensions\n  * --apps_base APPS_BASE_DIR     =\u003e  set applications base directory\n  * -g, --log LEVEL               =\u003e  set logging level\n```\n\nYou can also specify a default *web.xml* to configure your web application.\nBy default the server tries to load the file *config/web.xml* but you can change\nthe path by adding the option `default_web_xml` within your configuration file.\n\n### YAML Configuration\n\nThe server can be configured from a .yml file. By default, if a file is\nnot specified, the server tries to load **config/trinidad.yml**.\nWithin this file you can specify options available on the command line and tune\nserver settings or configure multiple applications to be hosted on the server.\n\nAdvanced configuration options are explained in the wiki:\nhttp://wiki.github.com/trinidad/trinidad/advanced-configuration\n\n\n```\n$ jruby -S trinidad --config my_trinidad.yml\n```\n\n```yml\n---\n  port: 4242\n  address: 0.0.0.0\n```\n\n### Ruby Configuration\n\nAs an alternative to the *config/trinidad.yml* file, a .rb configuration file\nmight be used to setup Trinidad. It follows the same convention as the YAML\nconfiguration - the file **config/trinidad.rb** is loaded by default if exists.\n\n```ruby\nTrinidad.configure do |config|\n  config.port = 4242\n  config.address = '0.0.0.0'\n  #config[:custom] = 'custom'\nend\n```\n\n### Logging\n\nAs you might notice on your first `trinidad` the server uses standard output :\n\n```\nkares@theborg:~/workspace/trinidad/MegaUpload$ trinidad -p 8000 -e staging\nInitializing ProtocolHandler [\"http-bio-8000\"]\nStarting Servlet Engine: Apache Tomcat/7.0.28\nStarting ProtocolHandler [\"http-bio-8000\"]\nContext with name [/] has started rolling\nContext with name [/] has completed rolling\n```\n\nIt also prints warnings and error messages on error output, while application\nspecific log messages (e.g. logs from `Rails.logger`) always go into the expected\nfile location at *log/{environment}.log*.\n\nApplication logging performs daily file rolling out of the box and only prints\nmessages to the console while it runs in development mode, that means you won't\nsee any application specific output on the console say in production !\n\nPlease note that these logging details as well as the logging format will be\nconfigurable with *trinidad.yml/.rb* within the next **1.4.x** release.\n\nIf you plan to use a slice of Java with your JRuby and require a logger, consider\nusing `ServletContext#log`. By default it is setup in a way that logging with\n`ServletContext` ends up in the same location as the Rails log.\nIf this is not enough you can still configure a Java logging library e.g. SLF4J,\njust make sure you tell Trinidad to use it as well, if needed, using the\n**jruby.rack.logging** context parameter in *web.xml*.\n\n### Context Configuration\n\nFor slightly advanced (and \"dirty\" XML :)) application configuration Trinidad\nalso supports the exact same *context.xml* format as Tomcat. Each web app is\nrepresented as a context instance and might be configured as such. You do not\nneed to repeat configuring the same parameters you have already setup with the\nTrinidad configuration. This is meant to be mostly for those familiar with\nTomcat internals.\nCurrently the application's *context.xml* is expected to be located on the\nclass-path under your *[classes]/META-INF* directory.\n\nContext Doc: http://tomcat.apache.org/tomcat-7.0-doc/config/context.html\n\n### Serving Assets\n\nTrinidad uses Tomcat's built-in capabilities to server your public files.\nWe do recommend compiling assets up front and disabling the asset server (in\nproduction) if you're using the asset pipeline in a Rails application.\nIf you do not put a web-server such as Apache in front of Trinidad you might\nwant to configure the resource caching (on by default for env != development)\nfor maximum performance e.g. by default it's configured as follows :\n\n```yml\n---\n  public:\n    root: public # same as the above \"public: public\" setting\n    cached: true # enable (in-memory) asset caching on for env != 'development'\n    cache_ttl: 5000 # cache TTL in millis (might want to increase this)\n    cache_max_size: 10240 # the maximum cache size in kB\n    cache_object_max_size: 512 # max size for a cached object (asset) in kB\n    #aliases: # allows to \"link\" other directories into the public root e.g. :\n      #/home: /var/local/www\n```\n\nNote that this configuration applies to (server-side) resource caching on top\nof the \"public\" file-system. You do not need to worry about client side caching,\nit is handled out of the box with *ETag* and *Last-Modified* headers being set.\n\nYou might also \"mount\" file-system directories as aliases to your resources\nroot to be served by your application (as if they were in the public folder).\n\n**NOTE:** In development mode if you ever happen to `rake assets:precompile`\nmake sure to remove your *public/assets* directory later, otherwise requests\nsuch as **/assets/application.js?body=1.0** might not hit the Rails runtime.\n\n## Hot Deployment\n\nTrinidad supports monitoring a file to reload applications, when the file\n*tmp/restart.txt* is updated (e.g. `touch tmp/restart.txt` on Unix or\n`type nul \u003e\u003etmp\\restart.txt \u0026 copy /b tmp\\restart.txt +,,` on Windows),\nthe server reloads the application the monitor file belongs to.\nThis monitor file can be customized with the `monitor` configuration option.\n\nSince version **1.4.0** Trinidad supports 2 reload strategies :\n\n* **restart** (default) synchronous reloading. This strategy pauses incoming\n  requests while it reloads the application and then serves them once ready\n  (or timeouts if it takes too long). It is the default strategy since **1.4.0**\n  due it's more predictable memory requirements.\n\n* **rolling** a.k.a. \"zero-downtime\" (asynchronous) reloading strategy similar to\n  Passenger's rolling reloads. This has been the default since **1.1.0** up till\n  the **1.3.x** line. If you use this you should account that your JVM memory\n  requirements might increase quite a lot (esp. if you reload under heavy loads)\n  since requests are being served while there's another version of the\n  application being loaded.\n\n**NOTE:** due the way class-loaders where setup internally, Trinidad might have\nfailed releasing memory with reloads. This has been fixed in **1.5.0** please\nconsider updating, it is meant to be backwards compatible.\n\nIf you're on Java 6 you will likely need to tune your JAVA_OPTS / JRUBY_OPTS\nfor the JVM to do class unloading (consult the [wiki][6] for more information) :\n```\nJRUBY_OPTS=\"$JRUBY_OPTS -J-XX:+UseConcMarkSweepGC -J-XX:+CMSClassUnloadingEnabled\"\n```\n\nConfigure the reload strategy per web application or globally e.g. :\n\n```yml\n---\n  port: 8080\n  environment: production\n  reload_strategy: rolling\n```\n\n## Virtual Hosts\n\nIt's possible to use Trinidad with multiple hosts and load the applications under\nthem automatically. A (virtual) host represents an association of a network name\n(such as \"www.example.com\" with the particular server on which Tomcat is running.\nPlease remember that each host must have its applications in a different directory.\nYou can find out more at Tomcat's [documentation][4].\n\n```ruby\nTrinidad.configure do |config|\n  config.hosts = {\n    # applications path (host app base directory) =\u003e host names\n    # (first one is the \"main\" host name, other ones are aliases)\n    '/var/www/local/apps' =\u003e ['localhost', '127.0.0.1'],\n    '/home/trinidad/apps' =\u003e 'appshost'\n    # NOTE: by default a (default) 'localhost' host is setup\n  }\nend\n```\n\nDetailed host configuration is also possible using supported [host options][4] :\n\n```yaml\n---\n  port: 8080\n  hosts:\n    localhost:\n      app_base: /home/trinidad/apps\n      auto_deploy: false\n      unpackWARs: true\n```\n\nIf applications are configured via the `web_apps` section, the host for each\napplication can be added with the `host` (or `hosts`) key, if a specified host\ndoes not exists (e.g. not configured or not \"localhost\") it will be created.\nIf several applications belong to the same host, they are expected to reside\nunder the same parent directory e.g. :\n\n```ruby\nTrinidad.configure do |config|\n  config.web_apps = {\n    :mock1 =\u003e {\n      :root_dir =\u003e 'rails_apps/mock1',\n      :host     =\u003e ['rails.virtual.host', 'rails.host']\n    },\n    :mock2 =\u003e {\n      :root_dir =\u003e 'rails_apps/mock2',\n      :host     =\u003e 'rails.virtual.host'\n    },\n    :mock3 =\u003e {\n      :root_dir =\u003e 'rack_apps/mock3',\n      :host     =\u003e ['rack.virtual.host', 'rack.host']\n    }\n  }\nend\n```\n\n## Extensions\n\nTrinidad allows to extend itself with more (not just Tomcat) features using\nextensions, they're essentially components hooked into Tomcat's life-cycle.\nHere is a list of the available extensions that are \"officially supported\" :\n\n* Database Connection Pooling :\n  http://github.com/trinidad/trinidad_dbpool_extension\n* Daemonize Trinidad, based on Akuma (Unix only) :\n  http://github.com/trinidad/trinidad_daemon_extension\n* Init Services (for Unix and Windows), based on Commons Daemon :\n  http://github.com/trinidad/trinidad_init_services\n* Scheduler, based on Quartz :\n  http://github.com/trinidad/trinidad_scheduler_extension\n* Worker, threaded workers (supports Resque, Delayed::Job) :\n  http://github.com/trinidad/trinidad_worker_extension\n* Logging, enhance Trinidad's logging system :\n  http://github.com/trinidad/trinidad_logging_extension\n* Application and Server Lifecycle Management :\n  http://github.com/trinidad/trinidad_lifecycle_extension\n* Valves - components inserted into the request pipeline (e.g. Access Log) :\n  http://github.com/trinidad/trinidad_valve_extension\n* Application/Deployment Monitoring based on PSI-Probe :\n  http://github.com/trinidad/trinidad_probe_extension\n* Enable remote JMX monitoring capabilities for Trinidad :\n  http://github.com/trinidad/trinidad_jmx_remote_extension\n\nYou can find further information on how to write extensions in the [wiki][5].\n\n## Support\n\n* ask us for help on [gitter][2] or use [SO][3] ... we shall get notified\n* we're also on the JRuby mailing List: http://wiki.jruby.org/MailingLists\n* and the #jruby IRC [channel](http://webchat.freenode.net/?channels=jruby)\n* please report issues at: https://github.com/trinidad/trinidad/issues\n\n## Copyright\n\nCopyright (c) 2016 [Team Trinidad](https://github.com/trinidad).\nSee LICENSE (http://en.wikipedia.org/wiki/MIT_License) for details.\n\n[1]: https://gemnasium.com/trinidad/trinidad\n[2]: https://gitter.im/trinidad\n[3]: http://stackoverflow.com/questions/tagged/jruby\n[4]: http://tomcat.apache.org/tomcat-7.0-doc/config/host.html\n[5]: https://github.com/trinidad/trinidad/wiki/extensions\n[6]: https://github.com/trinidad/trinidad/wiki/JOPTS","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrinidad%2Ftrinidad","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrinidad%2Ftrinidad","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrinidad%2Ftrinidad/lists"}