Deploying a Ruby Project Generated on Windows
Last updated 06 January 2016
Table of Contents
Heroku’s stacks run on a distribution of Linux, and as a result requires all libraries installed to be Linux compatible. If you are developing on a Windows machine there can be problems when deploying to Linux due to cross OS compatibility issue with dependencies. Developers on a Mac or another Linux distribution will not have the problems described below.
Background: dependency resolution
If you are developing a Ruby application, you use a
Gemfile to declare the dependencies that you need. When you run
bundle install all of your dependencies are evaluated to see if they can be resolved. Bundler then creates a
Gemfile.lock. This file has the exact versions of the dependencies that were installed so that if you give the same
Gemfile.lock to someone on another computer and have them run
bundle install it should install the exact same versions.
Some gems have decided to create specialized versions to maintain compatibility with windows. When you run
bundle install on a Windows machine you may see something that looks like this in the
PLATFORMS ruby x86-mingw32
x86-mingw32 line tells bundler that the
Gemfile was evaluated on a Windows machine. You may also see
mswin instead of
mingw. You may or may not notice individual gems that contain a special marker:
This indicates that this gem is custom for the platform
x86-mingw32 or windows.
Because Heroku stacks are based on Linux, this type of gem will not run on Heroku. Due to this problem the previous
Gemfile.lock resolution must be discarded and we must run
bundle install from scratch.
Bundle install with no lockfile
Gemfile.lock is removed before running
bundle install all history of libraries and their versions installed is gone. The resolver in bundler must now work to re-generate a new
Gemfile.lock and install gems. This has two problems: inconsistency between development and production code, and the potential to have a Gemfile that does not resolve at all.
When Heroku detects that you a Windows specific
Gemfile.lock it will output a warning in line. Check your deploy output for something like this:
Removing `Gemfile.lock` because it was generated on Windows.
Inconsistent dev-prod parity
Gemfile.lock If you have a line in your Gemfile like this:
You are stating you want bundler to install any version of Rails. If it detects that you already have
3.2.x installed on your local machine it may decide to use that version, where if you were to install on a co-worker’s machine it may install
This inconsistency between machines and between development and production is likely to cause errors. You may see strange behavior in production that you cannot re-produce in development. To help avoid that, and achieve dev/prod parity, be as specific as possible in your Gemfile:
gem 'rails', '4.0.1'
This guarantees that Rails 4.0.1 will be installed even if the
Gemfile.lock is missing. While it is impossible to do this for all of your dependencies you can use operators such as greater than or equal (
>=) or preferably the pessimistic locking operator (
~>) to limit the scope of your gem requirements.
The down side to being specific in the Gemfile is that upgrading one gem may cause a gem resolution to fail and you may need to spend some time figuring out exactly how declare the versions of your dependencies manually.
Cannot resolve Gemfile
If your gem versions are too vague, and if those libraries have circular requirements it is possible to get bundler into a state where it cannot resolve your dependencies but continues to try in an infinite loop. If the output after
bundle install seems to freeze for many minutes, or continuously outputs dots
.......... it may be a sign that it cannot resolve your
Gemfile when the
Gemfile.lock is removed. In this scenario you likely need to make your gem version requirements more specific to better help bundler do its job and narrow down its search space.
Be as specific in your Gemfile as you possibly can when developing on Windows. If only one developer on your team has a Windows machine, consider not checking in their
Gemfile.lock changes or manually bundle installing and committing on a non-Windows machine before deploying.