Installation

There are several options how to run Dredd on your machine or in your Continuous Integration.

Docker

Installing Dredd using Docker is the easiest and the most hassle-free option for every major operating system.

Following line runs the dredd command using the apiaryio/dredd Docker image:

$ docker run -it -v $PWD:/api -w /api apiaryio/dredd dredd

As an example of how to pass arguments, following line runs the dredd init command:

$ docker run -it -v $PWD:/api -w /api apiaryio/dredd dredd init

Following line runs the dredd command using the apiaryio/dredd Docker image:

C:\Users\Susan> docker run -it -v ${pwd}:/api -w /api apiaryio/dredd dredd

As an example of how to pass arguments, following line runs the dredd init command:

C:\Users\Susan> docker run -it -v ${pwd}:/api -w /api apiaryio/dredd dredd init

npm

Dredd is a command-line application written in JavaScript, or to be more precise, in Node.js. If Docker isn’t an option for you, it’s possible to install Dredd using the npm package manager. To install Dredd’s dependencies, you’ll also need to have Git available.

Installing Node.js

  • If you’re using Homebrew, run brew install node
  • Otherwise download Node.js from the official website and install it using the downloaded installer
  • Make sure both node --version and npm --version work in your Terminal
  • Node.js needs to be at least version 6
  • Download Node.js from the official website and install it using the downloaded installer
  • Make sure both node --version and npm --version work in your Command Prompt
  • Node.js needs to be at least version 6

Warning

If your internet connection is restricted (VPN, firewall, proxy), you need to configure npm:

npm config set proxy "http://proxy.example.com:8080"
npm config set https-proxy "https://proxy.example.com:8080"

Otherwise you’ll get similar errors during Dredd installation:

npmERR! Cannot read property 'path' of null
npmERR!code ECONNRESET
npmERR!network socket hang up

Later be sure to read how to set up Dredd to correctly work with proxies.

Installing Dredd

Now that you have everything prepared, you can finally run npm to install Dredd:

npm install dredd --global --no-optional

Warning

If you get EACCES permissions errors, try one of the officially recommended solutions. In the worst case, you can run the command again with sudo.

You can verify Dredd is correctly installed by printing its version number:

dredd --version

Now you can start using Dredd!

Optional steps

Adding Dredd as dev dependency

If your API project is also an npm package, you may want to add Dredd as a dev dependency instead of installing it globally.

  • Make sure your project is an npm package with a package.json file
  • In the root of the project run npm install dredd --save-dev --no-optional
  • Once the installation is complete, you can run Dredd from the root of the project as npx dredd

This is how Dredd is installed in the dredd-example repository, so you may want to see it for inspiration.

When using npm with your API project, you might notice it tries to compile C++ dependencies again and again, which means every npm command takes very long until it finishes. The workaround is to append --no-optional every time to your npm command. We’re working on a better solution together with the team behind the C++ projects we depend on (drafter-npm#16).

Installing C++ dependencies

The API Blueprint parser is written in C++, which needs to be compiled during Dredd’s installation process. The --no-optional npm option forces Dredd to fall back to a slower, but easy to install pure JavaScript version of the parser:

npm install dredd --global --no-optional

This is ideal in case you are

  • using Dredd exclusively with OpenAPI 2,
  • using Dredd with small API Blueprint files,
  • using Dredd on Windows or other environments with complicated C++ compiler setup.

To gain more performance when parsing larger API Blueprint files, you may want to install Dredd without the --no-optional npm option. However, first check following requirements:

Have a modern C++ compiler
Check out the list of supported compilers. See how to compile on Windows or Travis CI.
Make sure npm uses Python 2
node-gyp, which performs the compilation, doesn’t support Python 3 yet. If your default Python is 3 (see python --version), tell npm to use an older version.

Now you can install Dredd like this:

npm install dredd --global

If you see errors mentioning node-gyp, gyp, or python, the compilation has failed:

gyp ERR! stack Error: `gyp` failed with exit code: 1
gyp ERR! not ok
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: [email protected] (node_modules/protagonist):
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: [email protected] install: `node-gyp rebuild`
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: Exit status 1

Despite that, Dredd itself will install and work correctly as in such case it falls back to the JavaScript version of the parser.

Note

See also C++ dependencies in the guide through Dredd’s internals.