minicomp/wax 🐝

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.

• Prerequisites
• Getting Started
• Using Docker
• Contributing

Prerequisites

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

Check your versions with:

ruby -v

bundler -v

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

... and check Ghostscript with:

gs -version

Vips will soon replace ImageMagick for Wax's image processing. If you're ahead of the curve, you can check your version with

vips -v

Getting Started

There are a few ways to get started with Wax, depending on your needs. Copyin the demo template 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. Log into your GitHub account. (Or sign up if you don't have one!)

2. Head to the Wax demo page and click "Use this Template" button. It will prompt you to create a copy of the repository in your own account. You should name it after the collection or exhibition you'll make, since this name will inform your free URL for the project with GitHub. For this example, our repository is called "my-wax-site".

3. On your own, new Wax repository page, click the Green "Code" button and copy the URL it provides to your clipboard, e.g,

git@github.com:mnyrop/my-wax-site.git

4. Open your Terminal/Shell application and change directory into where you'd like to work on your project, e.g., your Desktop:

cd ~/Desktop

5. Run the git clone command plus the link you copied on your clipboard in one line, e.g.,

git clone git@github.com:mnyrop/my-wax-site.git

6. When the clone is complete, change directory into your newly cloned project folder, in our case:

cd my-wax-site

7. Install the project-specific Ruby dependencies by running the command

bundle install

8. 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-6 above to copy and cd into the repo.

Next, build the minicomp/wax base image:

docker build -t minicomp/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 minicomp/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 0.0.0.0

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

Contributing

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.