Permalink
a4f1fc7 Dec 10, 2018
1 contributor

Users who have contributed to this file

179 lines (103 sloc) 7.03 KB

Installation

There are several options how to run Dredd on your machine or in your :ref:`continuous-integration`.

Docker

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

.. tabs::

   .. group-tab:: macOS, Linux

      Following line runs the ``dredd`` command using the `apiaryio/dredd <https://hub.docker.com/r/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

   .. group-tab:: Windows

      Following line runs the ``dredd`` command using the `apiaryio/dredd <https://hub.docker.com/r/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

.. tabs::

   .. group-tab:: macOS

      - If you’re using `Homebrew <https://brew.sh/>`__, run ``brew install node``
      - Otherwise `download Node.js <https://nodejs.org/en/download/>`__ 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

   .. group-tab:: Linux

      - `Install Node.js as a system package <https://nodejs.org/en/download/package-manager/>`__
      - In case your Linux distribution calls the Node.js binary ``nodejs``, please `follow this advice <https://stackoverflow.com/a/18130296/325365>`__ to have it as ``node`` instead
      - Make sure both ``node --version`` and ``npm --version`` work in your Terminal
      - Node.js needs to be at least version 6

   .. group-tab:: Windows

      - `Download Node.js <https://nodejs.org/en/download/>`__ 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 :ref:`how to set up Dredd to correctly work with proxies <using-https-proxy>`.

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 :ref:`start using Dredd <quickstart>`!

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 :ref:`C++ dependencies <install-cpp>` 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 (:ghissue:`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: protagonist@1.6.8 (node_modules/protagonist):
npm WARN optional SKIPPING OPTIONAL DEPENDENCY: protagonist@1.6.8 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 :ref:`cpp-dependencies` in the guide through Dredd's internals.