gliderlabs/herokuish: Heroku-compatible container workflows

Why herokuish exists for PaaS image builders

herokuish solves a narrow infrastructure problem: reproducing selected Heroku conventions inside a container image. The README describes buildpack execution, Procfile parsing, application startup, and slug import or export as reusable logic. Platform authors can place that logic in an image and decide separately how containers are built, scheduled, mounted, and operated. The intended users are therefore not ordinary application developers looking for a deployment service. They are maintainers of systems such as Dokku, Deis, Flynn, or similar platform layers that need their images to behave like Heroku images. The project is community maintained and is not affiliated with Heroku.

The separation matters because Heroku compatibility involves more than running an application process. A build image may need to detect and install a buildpack, execute its build, preserve a cache, parse a Procfile, or produce a slug. A runtime image may need only Procfile handling. herokuish exposes those operations as commands, and the README explicitly says that buildpack, procfile, and slug commands can be used independently. This lets a platform author compose only the behavior needed by a particular image instead of adopting a larger platform framework.

The command and path model

The executable organizes its work around `buildpack`, `procfile`, and `slug` command groups. The `buildpack` group covers detection, installation, building, listing, and testing. The `procfile` group covers parsing a process type, running a command as an unprivileged user, and starting a process type. The `slug` group generates, imports, and exports gzipped application tarballs. `paths` reports the filesystem locations used by those commands, while `version` reports the herokuish version and supported buildpack versions.

The documented paths show how application data moves between stages. `IMPORT_PATH=/tmp/app` is the mounted path that can be copied to `APP_PATH=/app`, while `BUILD_PATH=/tmp/build` is the build working directory and `CACHE_PATH=/tmp/cache` is the buildpack cache location. `ENV_PATH=/tmp/env` points to files that define the base environment, and `BUILDPACK_PATH=/tmp/buildpacks` contains installed buildpacks. The command output also shows that these paths can be overridden through the relevant environment variables, although the README does not enumerate every variable name.

Some subcommands also work as container entrypoints. When the executable is invoked as `/start`, `/exec`, or `/build`, it dispatches to the corresponding subcommand. The project therefore supports both an explicit command interface and image conventions that call the binary directly through those paths.

Buildpacks are installed, not bundled

herokuish does not include buildpacks. The README says it is tested against recent versions of Heroku-supported buildpacks and points to `herokuish version` for the supported version information. The buildpack directory can be populated during image construction, mounted into the container, or populated with the installation command. This is a deliberate composition boundary. A platform author controls which language runtimes and buildpack revisions the image supports, rather than accepting every buildpack available in the herokuish distribution.

The installation command without arguments installs all supported buildpacks into the configured buildpack path. The documented individual form is `herokuish buildpack install <url> [committish]`, where the optional committish selects a particular revision. The Dockerfile for the published image demonstrates the all-buildpacks route by invoking `/bin/herokuish buildpack install` and then removing repository metadata, changelogs, specifications, tests, and temporary files from the installed buildpack directories. That image is based on the Heroku 24 build image and includes the runtime dependencies needed by the generated container.

This design makes image size and supported-runtime policy an explicit concern. It also means that an application cannot be built merely because herokuish is installed. The correct buildpack must be present, and the application and build environment must satisfy that buildpack's requirements.

Installing the binary inside a Docker build

The README directs users to download the latest binary tarball from the project's releases. Its Dockerfile example installs version `v0.11.19` directly into `/bin` during an image build. The command requires Bash 4.0 or newer and standard GNU utilities, and the README warns that Busybox is unlikely to work. The example should be read as a release-specific installation step, not as a complete Dockerfile or a promise that every dependency is installed by the command itself.

The basic installation block is:

RUN curl --location --silent https://github.com/gliderlabs/herokuish/releases/download/v0.11.19/herokuish_0.11.19_linux_x86_64.tgz \
    | tar -xzC /bin

After the image contains the binary and its required dependencies, a first check is to ask the executable for its version information. This does not build an application, but it verifies that the command is available and shows the buildpacks associated with the installation.

$ herokuish version

The README does not give a complete, self-contained first-build command for an application. It gives an application-running Docker example only as an incomplete excerpt, so this article does not complete that command with undocumented flags or volume arguments. For a real build, the platform image must provide the application mount, the build environment, and the buildpack installation expected by its entrypoint.

Procfile and runtime execution behavior

The `procfile` commands are useful when an image does not need the full buildpack or slug workflow. The README specifically mentions non-buildpack runtime images, such as `google/python-runtime`, as a case where Procfile support may be valuable. `herokuish procfile parse` obtains the command string for a process type from a Procfile. `herokuish procfile start` runs the command for a process type through `herokuish procfile exec`, and `exec` supplies a Heroku-like environment while running the application as an unprivileged user.

The privilege behavior has an important exception. By default, `herokuish exec` drops root privileges through `setuidgid`. If the command is already running as a non-root user, the README says that `setuidgid` will fail. In that situation, the documented opt-out is to set `HEROKUISH_SETUIDGUID=false`. This setting is an operational choice rather than a general convenience switch. Disabling it should be based on the privilege model of the surrounding image, because the documented purpose of the default is to run the process as an unprivileged user.

The README does not specify the complete argument grammar for each Procfile subcommand. It does establish the division between parsing, execution, and starting, which is enough to understand the runtime boundary without inventing unsupported flags.

Slug workflows and container boundaries

Slug support covers the movement of an application artifact between stages. `slug generate` creates a gzipped tarball from the current application, `slug import` reads a gzipped tarball from a URL or standard input, and `slug export` sends the generated tarball to a URL with `PUT` or writes it to standard output. The help example shows that export requires the generated slug file to exist. When no URL argument is supplied, the command writes the file to standard output.

This behavior is optional. The README says image builders that produce an image without an intermediate slug can ignore slug commands. That is a meaningful distinction for adoption. A platform that builds directly into a final image does not need to maintain a slug transfer protocol merely because it wants Heroku-like application execution. A platform that separates build output from runtime image creation may use generate, export, and import to move that artifact.

The repository does not document authentication, retry policy for slug URLs beyond the help example, artifact retention, or rollback behavior. Those are platform responsibilities unless the image or surrounding workflow supplies them. The help excerpt shows `curl` with retries for a URL export, but it does not establish a general network or durability guarantee.

Maintenance, licensing, and upgrade work

The repository is not archived, and its last push was on 2026-10-16. Recent releases include `v0.11.19` on 2026-10-09, `v0.11.18` on 2026-09-28, and `v0.11.17` on 2026-09-09. Those dates indicate recent repository activity, but an upgrade still needs to be treated as an image change rather than a harmless binary swap. The supported buildpack revisions, base image, runtime dependencies, and path conventions can affect how applications are built.

The project license is MIT. That permits use and modification under the license's terms, but it does not remove the need to review the license text and any separate terms for buildpacks, base images, or other dependencies. The Dockerfile identifies the base as `heroku/heroku:${STACK_VERSION}-build` and sets `STACK_VERSION` to `24` by default. A platform changing that stack value must account for the resulting base-image and buildpack behavior.

Upgrade cost is therefore concentrated in image maintenance: rebuilding the image, checking supported buildpack versions with `herokuish version`, and validating Procfile and runtime behavior for the applications hosted on that image. The README does not promise a compatibility window or an automatic migration mechanism.

Editorial conclusion

Adopt herokuish when building a Heroku-compatible image or platform layer that needs buildpack, Procfile, or slug behavior. Do not treat it as a complete container platform or as a replacement for Heroku itself. Verify first that the target image includes Bash 4.0 or newer, the required GNU utilities, daemontools, and the buildpack set your applications expect. The project uses an MIT license, so review the license and included dependencies separately when packaging the tool.

Frequently asked questions

Official sources

1. gliderlabs/herokuish on GitHub
2. Issues
3. License: MIT
4. README
5. Releases