Dependency Management

Ruby Dependency Management

All Ruby application servers based on Apache or NGINX include Bundler by default. Bundler reads the application Gemfile, resolves required gems, and installs any missing dependencies automatically.

In this article

Bundler Dependency Management

Bundler tracks the gems required by a Ruby application. Add the required gems and version rules to the project Gemfile, and Bundler resolves the complete dependency tree.

When a required gem is not already installed, Bundler searches RubyGems.org and installs it. By default, the managed Ruby application-server images include only the gems required by the example application.

When Dependencies Are Resolved

Application deploymentBundler resolves and installs the dependencies after the Ruby application is deployed.
Ruby version changeDependencies are checked again when the container is switched to another Ruby version.
Deployment-type changeDependencies are resolved when the application is changed between development, production, or test deployment modes.

Configure the Gemfile

The Gemfile can define exact versions or flexible version ranges for application gems.

source "https://rubygems.org"

gem "rails", "~> 7.1"
gem "jquery-rails", "~> 2.0.2"
gem "pg", ">= 1.5"

With a non-strict declaration, Bundler installs the latest compatible version during each dependency-resolution action.

Ruby Gemfile dependencies
List required Ruby gems and compatible versions in the application Gemfile.
✓

Flexible version rules

Use compatible version operators where appropriate so dependency installation is not interrupted unnecessarily when a newer compatible gem release becomes available.

Use Private Dependencies

When an application depends on a gem that is not publicly available through RubyGems.org, specify its repository URL in the Gemfile.

gem "custom_gem",
  git: "https://example.com/repository/custom_gem.git",
  branch: "main"

Bundler then downloads and installs the gem from the specified source.

Declare the Ruby Version

When redeploying a Ruby environment to another engine version, ensure that the new version is covered by the Gemfile. Otherwise, Bundler can report a Ruby-version discrepancy.

ruby "~> 3.3.0"
i

Recommended declaration

Use a non-strict Ruby version requirement, such as ruby "~> 3.3.0", when compatible upgrades should remain possible without interrupting deployment or continuous-integration workflows.

Expected Result

Bundler reads the project Gemfile after supported deployment or environment changes, resolves the required dependency versions, and installs missing gems from RubyGems.org or the configured private repositories.

Important Notes

  • Bundler is preinstalled on Apache Ruby and NGINX Ruby application servers.
  • Keep the Gemfile in the application project root.
  • Use compatible version ranges when strict pinning is not required.
  • Specify repository URLs for non-public gems.
  • Update the Ruby version declaration before redeploying to another engine version.
  • Review deployment logs when dependency resolution fails.

Common Issues and Solutions

Gem is not installedConfirm that it is listed correctly in the Gemfile and that the source repository is reachable.
Ruby version discrepancyUpdate the Gemfile Ruby declaration so it includes the engine version selected during redeployment.
Private gem cannot be downloadedCheck the repository URL, branch, credentials, and network access.
Unexpected gem version is installedUse a stricter version rule or review the compatible range declared in the Gemfile.
Deployment fails during bundle installReview the application deployment log, native-extension requirements, and gem compatibility with the selected Ruby version.

What’s Next?