Run Vendored Binaries on Heroku

By Jon Saints - 12 May 2014

Summary

Often on Heroku your app might depend on a system package that is not installed in the base Heroku system. Including an external binary dependency in your Heroku app is easy. These binaries are called vendored binaries.

Here is a quick summary of how to do this:

Compile the binary on the heroku platform using a one-off dyno bash prompt heroku run /bin/bash

Copy the compiled package to your local git repo and place it in a folder .heroku/vendor

On your next push to heroku, the system path will recognize the binary dependencies in your path LD_LIBRARY_PATH.

Background

Recently I needed to install the python Shapely library on a Heroku app. Shapely has a dependency on the C Library GEOS which is not part of the base Heroku system.

Here is how I complied and vendored the GEOS binary for Heroku. You could use the same process to vendor a different binary.

When the compiling is finished you will have a working binary in the /app/scratch-space folder. In my case geos made three folders in the scratch-space folder: bin, lib, and include.

Create an zip archive of the binaries.

tar -czvf /app/geos-3.4.2-heroku.tar.gz .heroku/vendor

Step #3: Add the vendor library to your local source control

Next copy the geos-3.4.2-heroku.tar.gz to your local machine. I did this in two steps. You might have a better method. I used scp to copy the file to another server and then scp again copy the geos-3.4.2-heroku.tar.gz to my local machine.

With the geos-3.4.2-heroku.tar.gz on your local machine extract it into a folder .heroku/vendor in the root of your app. Heroku will automatically add the .heroku/vendor folder to your LD_LIBRARY_PATH.

Commit all of this to your local source and push to heroku. NOTE: Everytime PHP is upgraded on heroku you will need to recompile the geos extension. The php-config --extension-dir will change with each upgrade as well.