A command line tool for emulating Heroku build and runtime tasks in containers.
Herokuish is made for platform authors. The project consolidates and decouples Heroku compatibility logic (running buildpacks, parsing Procfile) and supporting workflow (importing/exporting slugs) from specific platform images like those in Dokku/Buildstep, Deis, Flynn, etc.
The goal is to be the definitive, well maintained and heavily tested Heroku emulation utility shared by all. It is complemented by progrium/cedarish, which focuses on reproducing the base Heroku system image. Together they form a toolkit for achieving Heroku compatibility.
Download and uncompress the latest binary tarball from releases.
For example, you can do this directly in your Dockerfiles installing into /bin as one step:
RUN curl https://github.com/gliderlabs/herokuish/releases/download/v0.1.0/herokuish_0.1.0_linux_x86_64.tgz \
--silent -L | tar -xzC /bin
Herokuish depends on Bash (4.0 or newer) and a handful of standard GNU utilties you probably have. It likely won't work on Busybox, though neither will any Heroku buildpacks.
Herokuish is meant to work behind the scenes inside a container. It tries not to force decisions about how you construct and operate containers. In fact, there's nothing that even ties it specifically to Docker. It focuses on neatly emulating Heroku, letting you design and orchestrate containers around it.
$ herokuish
Available commands:
buildpack Use and install buildpacks
build Build an application using installed buildpacks
install Install buildpack from Git URL and optional committish
list List installed buildpacks
help Shows help information for a command
paths Shows path settings
procfile Use Procfiles and run app commands
exec Run as random, unprivileged user with Heroku-like env
parse Get command string for a process type from Procfile
start Run process type command from Procfile through exec
slug Manage application slugs
export Export generated slug tarball to URL (PUT) or STDOUT
generate Generate a gzipped slug tarball from the current app
import Import a gzipped slug tarball from URL or STDIN
version Show version and supported version info
Main functionality revolves around buildpack commands, procfile/exec commands, and slug commands. They are made to work together, but can be used independently or not at all.
For example, build processes that produce Docker images without producing intermediary slugs can ignore slug commands. Similarly, non-buildpack runtime images such as google/python-runtime might find procfile commands useful just to support Procfiles.
Herokuish does not come with any buildpacks, but it is tested against recent versions of Heroku supported buildpacks. You can see this information with herokuish version. Example output:
$ herokuish version
herokuish version: 0.1.0
compatible cedarish: v2
compatible buildpacks:
heroku-buildpack-multi cddec34
heroku-buildpack-nodejs v60
heroku-buildpack-php v43
heroku-buildpack-python v52
heroku-buildpack-ruby v127
...
You can install all supported buildpacks with herokuish buildpack install, or you can manually install buildpacks individually with herokuish buildpack install <url> [committish]. You can also mount a directory containing your platform's supported buildpacks (see Paths, next section), or you could bake your supported buildpacks into an image. These are the types of decisions that are up to you.
Use herokuish paths to see relevant system paths it uses. You can use these to import or mount data for use inside a container. They can also be overridden by setting the appropriate environment variable.
$ herokuish paths
APP_PATH=/app # Application path during runtime
ENV_PATH=/tmp/env # Path to files for defining base environment
BUILD_PATH=/tmp/build # Working directory during builds
CACHE_PATH=/tmp/cache # Buildpack cache location
BUILDPACK_PATH=/tmp/buildpacks # Path to installed buildpacks
Some subcommands are made to be used as default commands or entrypoint commands for containers. Specifically, herokuish detects if it was called as /start, /exec, or /build which will shortcut it to running those subcommands directly. This means you can either install the binary in those locations or create symlinks from those locations, allowing you to use them as your container entrypoint.
Don't be afraid of the help command. It actually tells you exactly what a command does:
$ herokuish help slug export
slug-export <url>
Export generated slug tarball to URL (PUT) or STDOUT
slug-export ()
{
declare desc="Export generated slug tarball to URL (PUT) or STDOUT";
declare url="$1";
if [[ ! -f "$slug_path" ]]; then
return 1;
fi;
if [[ -n "$url" ]]; then
curl -0 -s -o /dev/null --retry 2 -X PUT -T "$slug_path" "$url";
else
cat "$slug_path";
fi
}
Pull requests are welcome! Herokuish is written in Bash and Go. Please conform to the Bash styleguide used for this project when writing Bash.
Developers should have Go installed with cross-compile support for Darwin and Linux. Tests will require Docker to be available. If you have OS X, we recommend boot2docker.
This project was sponsored and made possible by the Deis Project.
That said, herokuish was designed based on the experience developing and re-developing Heroku compatibility in Dokku, Deis, and Flynn. Herokuish is based on code from all three projects, as such, thank you to all the contributors of those projects.
In fact, since I hope this is the final implementation of Heroku emulation I'm involved with, I'd like to finally thank Matt Freeman (@nonuby). I've been more or less copy-and-pasting code he originally wrote for the now defunct OpenRoku since 2012.
BSD