Browse files

Add troubleshooting and other supporting sections

  • Loading branch information...
1 parent 2833436 commit e873d6b517e1c508bd228f7ed1ae203e2fec7b55 @rwdaigle committed Jul 4, 2012
Showing with 80 additions and 19 deletions.
  1. +80 −19 content/pages/a/using-vulcan-to-build-binary-dependencies-on-heroku.mdown
@@ -10,7 +10,7 @@ What remains unsolved is how to declare and manage system-level dependencies --
This post will explore explicitly managing and building system-level dependencies using the [Vulcan]( build server.
-## The problem
+## Problem
It's common for an application to shell out to a local executable to perform some computationally intense work where compiled libraries are more performant or robust. Some common examples include [Ghostscript](, which your application might use to manipulate PDF or PostScript files, or [ImageMagick]( for resizing and cropping uploaded images.
@@ -20,7 +20,7 @@ Additionally, having the ability to install system-wide binaries in your deploym
[Twelve-factor]( makes [the case]( to "not rely on the implicit existence of any system tools" for the deleterious effects it may have on future environment migration and upgrade efforts. Instead of solving system dependencies at a system level solve them at the application level by explicitly bundling binaries with the application that requires them.
-## Vulcan
+## Solution
Bundling a binary dependency requires that the binary be built specifically for the remote environment's operating system and processor architecture. This is a non-trivial task when you're faced with having to boot up a local host-VM just to simulate the remote server environment. Even then the processor architecture may be in conflict.
@@ -220,51 +220,112 @@ $ cd /app/vendor/wget-1.13
Many binaries were compiled in the course of writing this article for use on Heroku. Here is a list in case they're useful to you:
<p class="note" markdown="1">
-If you'd like to list a binary compiled for Heroku here, please send a pull request [for this article]().
+If you'd like to list a Heroku binary here, please [send a pull request](
- <th>Source</th>
<th>Build command</th>
+ <th>Contributor</th>
- <td><a href="">GNU Wget</a> v1.13</td>
- <td><a href=""></a></td>
- <td><code>vulcan build -v -s ./wget-1.13 -c "./configure --prefix /app/vendor/wget-1.13 --without-ssl && make install" -p /app/vendor/wget-1.13</code>
- <td><a href=""></a></td>
+ <td><a href="">GNU Wget v1.13</a></td>
+ <td><code>vulcan build -v -s ./wget-1.13 -c "./configure --prefix /app/vendor/wget-1.13 --without-ssl &amp;&amp; make install" -p /app/vendor/wget-1.13</code></td>
+ <td><a href="">download</a></td>
+ <td><a href="">Ryan Daigle</a></td>
+ </tr>
+ <tr>
+ <td><a href="">ImageMagick v6.7.8-1</a></td>
+ <td><code>vulcan build -v -s ./ImageMagick-6.7.8-1</code></td>
+ <td><a href="">download</a></td>
+ <td><a href="">Ryan Daigle</a></td>
+ </tr>
+ <tr>
+ <td><a href="">Ghostscript v9.05</a></td>
+ <td><code>vulcan build -v -s ./ghostscript-9.05</code></td>
+ <td><a href="">download</a></td>
+ <td><a href="">Ryan Daigle</a></td>
-#### Notes
+## Updates
+Updating Vulcan is quite simple. Update the CLI using ruby gems:
+<pre lang="bash"><code>
+$ gem install vulcan
+Please run 'vulcan update' to update your build server.
+Successfully installed vulcan-0.8.0
+1 gem installed
-repo of Heroku builds
+And use the `vulcan update` command to update the build server.
-specify output dir -p /tmp/name w/ configure --prefix (must be writable on dyno)
+<p class="warning" markdown="1">
+Be aware that updating the build server while active compilations are running will cause them to be aborted.
-Update w/ gem install vulcan && vulcan update
+<pre lang="bash"><code>
+$ vulcan update
+Initialized empty Git repository in /private/var/folders/tt/7f38d4b14qq5xglpj3yl0smr0000gn/T/d20120704-53816-m4n0rn/.git/
+Counting objects: 883, done.
-If already have buildserver,
+-----> Heroku receiving push
+-----> Node.js app detected
+-----> Resolving engine versions
+ Using Node.js version: 0.6.18
+ Using npm version: 1.1.4
+-----> Launching... done, v15
+ deployed to Heroku
-In practice: switch between local dev and remote (using the bin/ env)
+ + a5f27be...a934704 master -> master (forced update)
+## Troubleshooting
+### Invalid secret
-[web.1]: [672b5df6-ad8c-49ed-9831-515207e2dc4f] ERROR: invalid secret
+If working across multiple development environments or some other non-default workflow you may see the following build server error logged when attempting to invoke a build:
+2012-07-04T17:39:47+00:00 app[web.1]: [672b5df6-ad8c-49ed-9831-515207e2dc4f] ERROR: invalid secret
2012-07-04T17:39:47+00:00 app[web.1]: invalid secret
-heroku config -s | grep SECRET
+This occurs when the CLI secret hash, created when the build server was created with `vulcan create`, either doesn't exist or doesn't match the server-side secret. The most common cause is that the `~/.vulcan` configuration file doesn't exist in your environment. You can create it with the following contents:
+<h5 class="file">~/.vulcan</h5>
+<pre lang="yaml"><code>
:app: buildserver-you
-:secret: f575054501266d29eac5fcf9d8811dfb846f2520
+:secret: reallylonghash12df
+If you don't have access to your original `.vulcan` file you can find your secret on Heroku using `heroku config`:
+<pre lang="bash"><code>
+$ heroku config:get SECRET -a buildserver-you
+<p class="note" markdown="1">
+Copy your `~/.vulcan` file to each development machine from which you wish to invoke builds.
+## Notes
+Vendoring/In practice: switch between local dev and remote (using the bin/ env)
+style table
## Dependencies
Unlike Ghostscript, many libraries themselves have dependencies that are not available in your target environment. `wget` is a useful utility that requires the [GNU transport layer security library (gnutls)]( for SSL connections. To compile wget first compile gnutls.

0 comments on commit e873d6b

Please sign in to comment.