Installing with Docker

Herbie is available through Docker, which is sort of like a virtual machine. This page describes how to install the official Docker image for Herbie.

We recommend most users install Herbie from package or source. Herbie via Docker is only recommended if you already have Docker experience.

Installing Herbie via Docker

First, install Docker. Docker supports Windows, macOS, and Linux. Depending on how you install Docker, you may need to prefix the docker commands with sudo or run them as the administrative user.

With Docker installed, you can run the Herbie shell with:

docker run -it uwplse/herbie shell

This will download the Herbie image and then run its shell tool.

Herbie in Docker is more limited; for example, it will not recognize plugins installed outside the Docker container.

Running the web interface

You can run the Herbie web server locally with

docker run -it --rm -p 8000:80 uwplse/herbie

(Herbie's Docker image binds to port 80 by default; this command uses the -p <hostport>:80 option to expose Herbie on port 8000.)

If you are using the --log or --save-session flags for the web shell, you will also need to mount the relevant directories into the Docker container using the -v Docker option, as in the examples below.

Generating files and reports

To use Herbie in batch mode, you will need to mount the input in the Docker container. Do that with:

docker run -it --rm \
    -v in-dir:/in \
    -v out-dir:/out \
    -u $USER \
    uwplse/herbie improve /in/in-file /out/out-file

In this command, you are asking Herbie to read input from in-file in in-dir, and write output to out-file in out-dir. The command looks the same if you want Herbie to read input from a directory; just leave in-file blank.

To generate reports from Herbie, you can run:

docker run -it --rm \
    -v in-dir:/in \
    -v out-dir:/out \
    -u $USER \
    uwplse/herbie report /in/in-file /out/

As before, the input and output directories must be mounted inside the Docker container. Note that both here and above, the user is set to the current user. This is to ensure that the files Herbie creates have the correct permissions set.

Building the Docker image

This section is primarily of interest for the Herbie developers.

Clone the repo and confirm that Herbie builds correctly with make install.

Next, examine the Dockerfile and Makefile together. The Dockerfile should follow a process exactly like the Makefile, except a clean initial environment is assumed. The build may be split into 2 or more stages to limit the size of the resulting image. Each stage consists of a FROM command and a series of further commands to build up the desired environment, and later stages can refer to earlier stages by name—for example, COPY --from=earlier-stage ... can copy files compiled in earlier images. You may need to do things like bumping the version of Rust used for binary compilation or the version of Racket used in production, or adjusting paths to match the newest version of the repo.

Once you are ready to build, run this command from the repository root:

docker build -t uwplse/herbie:test .

This builds a new test image and tags it uwplse/herbie:test. You can run this image with:

docker run -p 8000:80 -it uwplse/herbie:test

The web demo should now be visible at http://localhost:8000.

To open a shell in a running container for testing, first get the container ID with:

docker ps

Then open a root shell in that container with

docker exec -it <CONTAINER ID> sh

The code and egg-herbie binaries should be under /src.