A few years ago, I was helping a junior dev deploy a Ruby app to a Linux VPS. On his MacBook, everything was humming along perfectly. But the moment he ran bundle install on the server, the whole process crashed with a cryptic error about native extensions. To make matters worse, the server was spending five minutes trying to compile pry-byebug and rspec—gems that have absolutely no business being on a production server. He was frustrated, and I had to explain that his Gemfile was treating the production server exactly like his local development environment.

Slicing Your Gems into Environment Groups

You don't want every gem you use to be loaded in every environment. If you're using rspec for testing or better_errors for debugging, loading those into production is a waste of memory and, in some cases, a legitimate security risk. Bundler lets you categorize these using groups.

Instead of just listing gems at the top level of your Gemfile, you can wrap them in a block. Here is how I usually structure a professional Gemfile:

gem 'pg' # Needed everywhere

group :development, :test do
  gem 'rspec'
  gem 'pry-byebug'
end

group :development do
  gem 'better_errors'
end

group :production do
  gem 'rack-timeout'
end

When you run bundle install, Bundler still installs everything by default. However, when you're actually deploying to a server, you can tell Bundler to ignore specific groups. I always use the --without flag in my deployment scripts: bundle config set --local without 'development test'. This ensures the production server stays lean and doesn't waste time installing tools you'll never use in a live environment.

Solving the "Works on My Machine" Platform Clash

Now, let's talk about platforms. This is where things get gritty. Some gems are "pure Ruby," but others are "native extensions"—they actually compile C code during installation. Because a MacBook (especially the M1/M2 ARM chips) is fundamentally different from a Linux server (x86_64), the Gemfile.lock needs to know about both environments.

If you generate your lockfile on macOS and then push it to a Linux server, you might see an error saying the lockfile was created for a different platform. I used to just delete the lockfile and run bundle install on the server to fix this, but that's a terrible habit because it risks upgrading other gems unexpectedly.

The right way to handle this is to explicitly add the target platforms to your lockfile from your local machine. If you know your app will run on a standard Linux server, run this command:

bundle lock --add-platform x86_64-linux

If you're deploying to a Docker container or a specific cloud provider, you might also see ruby (the generic platform) or arm64-linux. By adding these platforms, Bundler resolves the dependencies for all of them and stores the correct versions in the lockfile. When the server sees the lockfile already has the x86_64-linux resolution, it just works without complaining.

📋 Practical Task

Exercise: Pruning the Production Environment and Syncing Platforms

You have been handed a Gemfile for a project that is currently "bloated." The developer previously put everything in the global scope, and the production deployment is failing because of a platform mismatch between the developer's Mac and the Ubuntu server.

Your Goal: Modify the provided Gemfile and use the terminal to prepare the lockfile for a Linux environment.

# Current Gemfile
source 'https://rubygems.org'

gem 'rails'
gem 'sqlite3'
gem 'rspec'
gem 'factory_bot_rails'
gem 'pry-byebug'
gem 'aws-sdk-s3'

1. Rewrite the Gemfile so that rspec and factory_bot_rails are in a group for both development and test.
2. Move pry-byebug into a development-only group.
3. Assuming you are on a non-Linux machine, write the exact command you would run in the terminal to ensure the Gemfile.lock supports the x86_64-linux platform without deleting the lockfile.
4. Write the command you would run on the production server to install the gems while skipping the development and test groups.