You have a Heroku app, and you want to run it in development with the same convenience of deploying to Heroku?
WARNING: This is an exercise in Readme driven development. Current state of the project may not be reflected here. Void where prohibited, some restrictions may apply, etc.
# git clone myapp Cloning into myapp... # cd myapp # hoboku create Creating myapp... done. Starting application... done. App running at http://myapp.localhost/
Hoboku is a tool to easily deploy Heroku apps locally using Vagrant. It knows how to pull down the configs and data, and has drop-in replacements for some common plugins (shared database and redistogo, to begin with).
The first time you setup Hoboku locally will take a while, because it has to download the "base box" on which future applications will be built (may take on the order of 15 minutes, depending on your internet connection). Afterwards, setting up a new app should only take a minute or so, and from then on starting or restarting the box should take mere seconds, and changes to the app will be reflected instantly. (Unless your app requires a build process.)
Why would I want this?
To achieve dev/prod parity. Running your app in development with exactly the same OS, system packages, and dependencies as production minimizes the errors you getd when translating from one to another. Ever had a bug that only popped up in production because all your developers were on a case-insensitive file system? Embarrassing.
To get up and running faster. If you've ever dealt with walking through a long setup script to get all the dependencies for an app working, you know the pain. The more projects you work on, the more of a pain it is. While a proper Heroku app shouldn't be too hard to start, in practice getting the right database, cache, configuration and so on can be kind of a pain.
What exactly does it do?
hoboku create, a virtual box is created just for your app. (Note: just
like with Heroku, you can actually create multiple apps running different instances
of your project using the
-a|--app flag.) This box has the identical OS and system
packages to a Heroku Cedar dyno.
Using Heroku's own buildpacks, Hoboku autodetects the appropriate build for your
project (sniffing for clues like a
project.clj file, or
config.ru) and executes
the build. For polyglot projects, especially ones where you may not be familiar with
the intricacies of getting it set up, this can be a godsend. Want to hack on a
Clojure app, but you don't have a Java runtime installed? Maybe RVM is giving you a
hard time? Doesn't matter - the buildpack knows how to build the right system, you
just provide the app.
Just like with your Heroku app, you can simply add addons, with the same behavior
(same environment variables for configuration) as the Heroku ones. (Subject to
availability.) For example, a
hoboku addons:add redistogo will configure a Redis
service in the VM and set the appropriate configuration accordingly.
New addons can be added via user-contributed plugins. All most will really require is a special Chef cookbook that exports some environment variables.
Again, just like Heroku, Hoboku uses environment variables for configuration. You
can set them with the
hoboku config commands (mirroring the Heroku ones, of
course), but you can go one step further: a simple
hoboku config:import will
import the current configuration from your Heroku app. And if you have a
(and you should), Hoboku will pick that up automatically.
Well, okay, not actual DNS like Pow. Instead, something far simpler: each app
you create gets an entry in
/etc/hosts mapping to a loopback address, but with
ipfw rules to forward the correct ports into the hoboku box. This means that when
hoboku create myapp, you automatically get:
http://myapp.localhost/- port 80 serves up the default process (the one that binds to
ssh myapp.localhost- takes you straight to the box (you can also do
hoboku ssh, if you prefer)
If the app isn't currently running and you hit
http://myapp.localhost/, you'll get
a page offering to start the app at the press of a button. How's that for service?)
You can easily switch an app to production mode by doing
hoboku push (or
git push hoboku) - just like with Heroku, this will build the application from the git
checkout, and future changes in your directory will not be picked up. To switch back
to "live" mode, simply run
It's easy to run a dev and prod version side-by-side: just create two apps, and then make sure the production one is set as your remote:
hoboku create myapp-prod hoboku create myapp-dev # optional in this case - the first remote is automatically used hoboku remote -a myapp-prod
The apps will be accessible at
Running in production mode will not only freeze the code to the state of the git
repository, but will also set the appropriate environment variables (such as
RACK_ENV for ruby apps).
So how do I use it?
First, you're going to need to install Hoboku. While eventually Hoboku will be available on your local neighborhood package manager (brew, apt-get, yum, pacman, ports, portage, and... well, whatever windows devs use), for now it's good, old-fashioned:
git clone https://github.com/agnoster/hoboku cd hoboku make install
Note: this install process will (as mentioned before) take a while. Go ahead and make yourself a nice cup of tea while you wait, or perhaps learn Sanskrit?
hoboku CLI command should be immediately familiar to you if you use
Heroku. The most common commands are:
# All commands take the -a|--app flag hoboku create [app] hoboku stop hoboku start hoboku restart hoboku logs [-t] hoboku config:[get|set|unset|import] hoboku remote [-r|--remote-name (hoboku)] # set the git remote hoboku db:[pull|push] # import/export database from/to heroku hoboku destroy [--confirm (app)]
But it's a little premature given that there's no code. But, y'know.