To run Rails on JRuby under Apache Tomcat, package the application as a WAR with Warbler, let JRuby-Rack bridge Rack and Rails to the Servlet API, then deploy that WAR to Tomcat. The reliable sequence is to align JRuby, Java, Rails, Rack, JRuby-Rack and the Servlet API first; configure the Rails environment and JRuby runtime pool in the servlet deployment; build and inspect the WAR; and only then deploy it to Tomcat.
Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.
How the deployment works
A normal MRI Rails deployment starts a Ruby web server directly. This arrangement is different: Tomcat owns the Java process and servlet lifecycle, while JRuby runs the Rails code inside that process.
As an Amazon Associate I earn from qualifying purchases.
- JRuby executes Ruby and Rails on the JVM.
- Warbler packages the Rails or Rack application and its runtime files into a Java WAR archive.
- JRuby-Rack adapts the Rack interface to the Java Servlet API, allowing the application to run in a servlet container.
- Apache Tomcat deploys and manages the resulting WAR as a web application.
Warbler describes itself as “a gem to make a Java jar or war file out of any Ruby, Rails or Rack application.” JRuby-Rack describes itself as “a lightweight adapter for the Java Servlet environment that allows any (Ruby) Rack-based application to run unmodified in a Java Servlet container.” Those roles are complementary: Warbler creates the deployment artifact, and JRuby-Rack supplies the servlet bridge.
Check compatibility before changing the application
Compatibility is a matrix, not a single version number. A working deployment must satisfy the constraints of the selected JRuby, Java runtime, Rails and Rack versions, JRuby-Rack release, and Tomcat servlet level.
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
| Project or release line | JRuby | Java | Rails | Rack | JRuby-Rack | Servlet API |
|---|---|---|---|---|---|---|
| JRuby-Rack 1.2 compatibility row | 9.3–10.1 | 8 or newer | 5.0–8.0 | 2.2 | 1.2 | 3.0 |
| Warbler 2.1 compatibility row | 9.4–10.1 | 8 or newer | 5.0–8.0 | not stated | 1.2–2.0 | not stated |
The rows describe project compatibility ranges, not a guarantee that every combination inside them behaves identically. For example, the JRuby-Rack 1.2 row identifies Rack 2.2 and Servlet API 3.0, while Warbler 2.1 allows JRuby-Rack 1.2 through 2.0. Select one combination that satisfies both rows and the Rails application’s own dependency constraints.
What to decide
- Which JRuby release the application and its native or Java extensions support.
- Which Java runtime is installed on the Tomcat host; the cited matrices require Java 8 or newer.
- Whether the Rails version can use Rack 2.2 or requires a different supported Rack line.
- Which JRuby-Rack release supports that JRuby, Rack, Rails and servlet API combination.
- Which Tomcat installation exposes the servlet level expected by the selected JRuby-Rack series.
Do not copy a historical tutorial’s gem versions without checking the current compatibility tables for the project releases you intend to install.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsPrepare the Rails application under JRuby
Run Bundler and all build commands with JRuby, not MRI Ruby. The application should boot in its intended Rails environment before you package it. Confirm that the database adapter, Java integrations, asset pipeline and any other runtime dependencies resolve in the JRuby bundle.
Add Warbler to development tooling
Add Warbler to the application’s development dependencies so the packaging tool is locked with the application. A Gemfile entry can be expressed as:
group :development do
gem 'warbler'
endResolve the bundle with the chosen JRuby and commit the resulting lockfile. If Bundler selects an incompatible JRuby-Rack release, constrain JRuby-Rack explicitly to a release supported by the selected JRuby, Rack, Rails and servlet API versions.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
Keep Rack in the deployed bundle
JRuby-Rack does not necessarily vendor the Rack gem for you. Rack must therefore be present in the application’s bundle and available at runtime. A missing Rack dependency can produce a WAR that builds successfully but fails while Tomcat initializes the application.
Build the WAR with Warbler
Run Warbler from the Rails application’s root directory:
warbleWarbler detects Rails applications and, unless you change the setting, defaults the Rails environment to production. Treat that default as a deployment decision: production database credentials, secret configuration, logging and asset behavior must all be available to the Tomcat process.
Generate and review the configuration
Warbler can generate config/warble.rb for application-specific customization. Use that file to review what is packaged, how the application is detected, and which runtime settings are appropriate for the target server. Keep configuration in source control when it is part of the repeatable build, but keep credentials and other secrets outside the repository.
Inspect the package before deployment
Use Warbler’s debug task to inspect the build and verify that framework detection and packaged gems are what you expect:
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
warble war:debugCheck the generated WAR for the Rails application, bundled gems, JRuby-Rack integration and configuration files. Debugging the archive before Tomcat starts avoids confusing packaging errors with servlet errors.
Configure Rails and the JRuby runtime pool
Servlet context parameters control deployment details that are not simply Rails defaults. JRuby-Rack’s Rails example uses a context parameter for the Rails environment and parameters for the minimum and maximum number of JRuby runtimes.
Set the Rails environment explicitly
Set rails.env to the environment you intend to run. Warbler’s default is production, but an explicit value in the servlet deployment makes the choice visible and prevents an accidental mismatch between local assumptions and Tomcat.
Size the runtime pool deliberately
The minimum and maximum runtime settings determine how many JRuby runtimes JRuby-Rack can maintain for requests. For a thread-safe Rails application that is intentionally run with one runtime, set both bounds to 1. Otherwise, choose bounds based on request concurrency, application behavior and the memory budget of the Tomcat JVM.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
A representative web.xml context-parameter section is:
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
<context-param>
<param-name>rails.env</param-name>
<param-value>production</param-value>
</context-param>
<context-param>
<param-name>jruby.min.runtimes</param-name>
<param-value>1</param-value>
</context-param>
<context-param>
<param-name>jruby.max.runtimes</param-name>
<param-value>1</param-value>
</context-param>Use the parameter names and semantics documented for the JRuby-Rack release in your bundle. A larger pool is not automatically faster: every additional runtime increases memory use, and a non-thread-safe application may require a different concurrency strategy than a thread-safe one.
Deploy the WAR to Apache Tomcat
- Install a Java runtime that satisfies the selected compatibility matrix and make sure Tomcat uses that runtime.
- Place the generated WAR in Tomcat’s application deployment area, commonly the
$CATALINA_BASE/webapps/directory. - Start Tomcat or reload the host so it detects the new archive. Tomcat will expand and initialize the application according to its deployment configuration.
- Read the Tomcat and application logs during startup. Dependency resolution, Rails initialization, database configuration and servlet compatibility failures usually appear there before a browser request is made.
- Call a health endpoint or other harmless route and confirm that the request reaches Rails through JRuby-Rack.
The JRuby project identifies Tomcat as a standard Java server for WAR files built with Warbler. The external-server model leaves process supervision, connectors, TLS termination, deployment policy and log collection with the Tomcat operations team.
Validate the application after startup
A successful WAR deployment only proves that Tomcat could initialize the web application. Exercise the parts that commonly differ between a development machine and the server.
Recommended Free Tools
- Health endpoint: verify routing and a normal Rails response.
- Database connectivity: run a read-only check using the production configuration and confirm the expected connection pool behavior.
- Assets: load a page that references compiled assets and inspect the response paths and cache behavior.
- Sessions and uploads: verify that the configured storage and secret settings are available to the Tomcat process.
- Background jobs: confirm that workers are launched separately if the application needs them; a WAR request process does not automatically provide a job system.
- Shutdown: stop or reload Tomcat and confirm that requests drain cleanly and the application closes resources.
There is no universal performance benchmark for this stack. Measure the deployed application with its actual Rails code, database, traffic pattern and runtime-pool settings rather than applying a number from another installation.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.External Tomcat or Trinidad?
Both approaches run Rails and Rack on JRuby, but they assign ownership differently.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
| Decision axis | External Apache Tomcat with a WAR | Trinidad |
|---|---|---|
| Server model | Tomcat is installed and operated as the external Java application server. | Tomcat is embedded and started as part of the JRuby application process. |
| Packaging | Warbler produces a deployable WAR archive. | The application runs through Trinidad configuration rather than a separately managed external Tomcat installation. |
| Operations | Fits organizations with established Tomcat deployment, connector, monitoring and restart procedures. | Can simplify a self-contained process and local development. |
| Configuration | Servlet context, Tomcat connectors and deployment policy are managed in the Java server environment. | Rails/Rack server settings are configured through trinidad.yml or Ruby configuration. |
| Best fit | Teams standardizing several applications on an existing Java application-server platform. | Teams wanting an embedded-Tomcat process without operating a separate Tomcat installation. |
Choose based on servlet-version compatibility, who owns process and connector configuration, Java integration needs, deployment packaging, observability and local-development ergonomics. Trinidad is not a drop-in fix for an incompatible JRuby-Rack or Rack dependency; the same version discipline still applies.
Troubleshooting common failures
JRuby-Rack will not resolve or the application fails during initialization
Compare the selected JRuby-Rack release with the JRuby, Rails, Rack and Servlet API versions. Use Bundler to pin a release supported by that combination, then rebuild the WAR. Also verify that Tomcat exposes the servlet level expected by the JRuby-Rack series.
Rack 3 causes a startup or dependency error
Warbler documents failures when Rack 3 is used with a JRuby-Rack release that does not support Rack 3. Upgrade JRuby-Rack to a release that supports the application’s Rack version, or constrain Rack to a compatible 2.2 line when the Rails version permits that choice. Regenerate the lockfile and WAR after changing the constraint.
The WAR builds but Rack is missing at runtime
Inspect the bundle and WAR contents. Ensure the rack gem is declared in the application bundle rather than assuming JRuby-Rack supplies it. Rebuild after Bundler resolves the dependency.
Warbler does not recognize the Rails application
Generate config/warble.rb, inspect the framework and gem packaging settings, and run warble war:debug. Confirm that you executed Warbler from the Rails root with the intended JRuby and bundle.
Tomcat starts, but Rails uses the wrong environment
Check the deployed servlet context for rails.env and verify that the Tomcat process receives the configuration and secrets required by that environment. Do not assume the environment used by a local Rails command is the one used inside the WAR.
Requests fail under load or memory use is unexpectedly high
Review the minimum and maximum JRuby runtime parameters. A pool that is too small can limit concurrent work; a pool that is too large consumes additional memory. Re-evaluate thread safety, request concurrency and the JVM memory budget, then change the bounds deliberately and retest.
Deployment checklist
- JRuby and Java versions are selected from a compatible project matrix.
- Rails and Rack versions are supported by the chosen JRuby-Rack release.
- The Tomcat servlet level matches JRuby-Rack’s expectations.
- Warbler is locked in the application’s development bundle.
- The
rackgem is available in the runtime bundle. config/warble.rbhas been reviewed where customization is needed.warble war:debugshows the expected framework and packaged gems.- The Rails environment and JRuby runtime-pool bounds are set in servlet configuration.
- The WAR has been tested for startup, database access, assets, jobs and graceful shutdown.
- Tomcat logs and application logs are collected for future diagnosis.
The dependable external-server path is therefore straightforward but version-sensitive: run Rails with JRuby, package it with Warbler, use JRuby-Rack as the servlet adapter, configure the Rails environment and runtime pool, and deploy the resulting WAR to a compatible Tomcat installation.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
