Link Search Menu Expand Document

Setting up your system

Since Wax produces static sites, all of the software runs on your own computer. This process spits out an HTML website that can be hosted easily without complex software on a server. This workflow is very freeing in terms of maintenance, but does mean there’s a higher barrier to getting started initially.

We have a few installation guides and options available to help you through this process.

Table of Contents

  1. Requirements
  2. Guides
    1. Option 1: Install manually
    2. Option 2: Install with Docker
  3. Check for requirements
    1. Manual install checks
    2. Docker install checks


Ultimately, you’ll need:

*NOTE: If you’re using a newer wax_tasks, we also recommend you install Libvips, which will replace ImageMagick in our stack.

You can check your versions by running the commands below in your terminal/shell of choice.

If you don’t have current versions for these packages or are starting from scratch, see our Installation Guides.


You have two main options for installing the software needed for Wax: manually on your machine or in a Docker container. Both options have pros and cons.

Both options *should* work across Mac, Windows, and Linux machines, so you should choose the option that makes the most sense for you and your use case.

Option 1: Install manually

If you go this route:

  • You’ll install things one-by-one directly on your computer.
  • The process will be more tedious, but you’ll finish with a robust set of development tools that may be broadly applicable to other projects.
  • Your software will run faster than it would in a Docker container.

Option 2: Install with Docker

If you go this route:

  • You’ll install packages quickly within Docker “containers.” This means the container will have just about everything you need in fewer steps.
  • When you’re not working on your Wax site, you can destroy the container (and all the software with it!), freeing up space on your computer.
  • The downsides are that you’ll need to start a container whenever you want to work with Wax, and the software will run a little slower than if you were running things on your host machine.

Check for requirements

Manual install checks

If you installed the software manually, you can run the following commands directly in your Terminal/shell app.

Check for Ruby:

ruby -v

*NOTE: This should be >=2.4 and < 3.0!

Install & check for Bundler:

gem install bundler
bundler -v

Check for Git:

git --version

To process images, you will also need to have ImageMagick and Ghostscript installed and functional. (Vips for later versions.)

Check ImageMagick:

convert -version

Check Ghostscript:

gs -version

Check Libvips:

vips -version

Docker install checks

If you installed with Docker, all of the required software will be inside your Docker container except for Git, which is installed on your directly on your computer.

At this stage, you’ll only need to check for Docker and Git by running the following checks in your Terminal/shell app.

Check Docker:

docker -v

Check Git:

git --version

Table of contents