Skip to content
Go to file


Failed to load latest commit information.

minicomp/wax šŸ

Gem Version PRs Welcome Build Status Depfu Gem Downloads Join the chat the minicomp-wax channel of the Code4Lib Slack License

Wax is an extensible workflow for producing scholarly exhibitions with minimal computing principles.
It's comprised of: a few Ruby gems for processing image data and associated metadata (wax_tasks, wax_iiif), a Jekyll theme (wax_theme), and (hopefully soon!) a lot of documentation and recipes for creating, deploying, and maintaining digital exhibitions.


You'll need git and ruby >= 2.4 with bundler installed. These dependencies can either be installed natively on your system or within a Docker environment. For instructions, check the Wiki's Installation Guide.

Check your versions with:

$ ruby -v
  ruby 2.4.5p335 (2018-10-18 revision 65137) [x86_64-darwin18]

$ bundler -v
  Bundler version 2.0.1

To process images, you will also need to have ImageMagick and Ghostscript installed and functional. You can check to see if you have ImageMagick by running:

$ convert -version
  Version: ImageMagick 6.9.9-20 Q16 x86_64 2017-10-15
  Copyright: (c) 1999-2017 ImageMagick Studio LLC

... and check Ghostscript with:

$ gs -version
  GPL Ghostscript 9.21 (2017-03-16)
  Copyright (C) 2017 Artifex Software, Inc.  All rights reserved.

Getting Started

There are a few ways to get started with Wax, depending on your needs. Downloading the demo is suggested for new users so you can see how a full Wax site would work. Advanced Jekyllers can start from a clean Jekyll install. To start with the demo:

  1. Change directory into where you'd like your site, e.g., your Desktop:

    cd ~/Desktop
  2. Download the zip file from the wax github repository. The option to download the zip file should be on the button labeled "Code." Your browser will save the file where it normally saves downloads.

  3. Move the zip file to the location you will use. In our example, to the Desktop.

  4. Unzip the file. This can be done through your operating system graphic user interface, or in the terminal:


    You can delete the zip file once you're done.

  5. Rename the directory and go inside the project folder:

    mv wax-master my-project
    cd wax-master
  6. Install the gems (not required if using Docker):

    bundle install
  7. Run the demo site:

    bundle exec jekyll serve

After the last step, the terminal will provide you with a localhost URL for you to see your local copy of the site on your browser. This is the template site you will make changes to in order to make your own exhibition. For more, check out the Minicomp/Wax Wiki.

Using Docker

To use Wax in a container, make sure you are familiar with Docker and have Docker installed.

Run the "Getting Started" steps 1-5 above to copy and cd into the repo.

Next, build the wax_image base image:

$ docker build -t ubuntu/wax .

You will run all of the Wax tasks and commands within an interactive bash container, which you can create and access by running:

$ docker run -it --rm -v "$PWD":/wax --name wax -p 4000:4000 ubuntu/wax bash

To serve the site, you can run the following command in the guest container and view it in your host browser:

$ bundle exec jekyll serve --host --incremental --force-polling

You can exit the container at any time with $ exit, which will automatically stop and remove the container.


We welcome contributions to Wax, including bug reports and feature requests (submitted as Issues), code contributions (submitted as Pull Requests), and documentation updates (submitted however!) Not sure where to start? Feel free to get in touch via GitHub issue or grab an invite to join the conversation on the #minicomp-wax channel of the Code4Lib Slack.