docs: document quirks of running Dredd inside Docker

Close apiaryio/docker-base-images#149, close #748, document #755

docs/hooks/go.rst

@@ -19,12 +19,15 @@ Installation
 Usage
 -----
 
-Using Dredd with Go is slightly different to other languages, as a binary needs to be compiled for execution. The –hookfiles flags should point to compiled hook binaries. See below for an example hooks.go file to get an idea of what the source file behind the go binary would look like.
+Using Dredd with Go is slightly different to other languages, as a binary needs to be compiled for execution. The :option:`--hookfiles` options should point to compiled hook binaries. See below for an example hooks.go file to get an idea of what the source file behind the go binary would look like.
 
 ::
 
    $ dredd apiary.apib http://127.0.0.1:3000 --server=./go-lang-web-server-to-test --language=go --hookfiles=./hook-file-binary
 
+.. note::
+   If you're running :ref:`Dredd inside Docker <docker>`, read about :ref:`specifics of getting it working together with non-JavaScript hooks <hooks-docker>`.
+
 API Reference
 -------------
 

docs/hooks/index.rst

@@ -94,7 +94,7 @@ Now the tests should pass even if publishing new article requires auth.
 Supported languages
 -------------------
 
-Dredd itself is written in JavaScript, so it supports :ref:`JavaScript hooks <hooks-js>` out of the box. Hook handlers for other languages need to be installed before they can be used. Supported languages are:
+Dredd itself is written in JavaScript, so it supports :ref:`JavaScript hooks <hooks-js>` out of the box. Running hooks in other languages requires installing a dedicated *hook handler*. Supported languages are:
 
 .. toctree::
    :maxdepth: 1
@@ -189,3 +189,18 @@ Hooks get executed at specific points in Dredd's :ref:`execution life cycle <exe
 -  ``after`` called after a specific HTTP transaction regardless its result
 -  ``afterEach`` called after each HTTP transaction
 -  ``afterAll`` called after whole test run
+
+
+.. _hooks-docker:
+
+Hooks inside Docker
+-------------------
+
+As mentioned in :ref:`supported-languages`, running hooks written in languages other than JavaScript requires a dedicated hook handler. Hook handler is a separate process, which communicates with Dredd over a TCP socket.
+
+If you're :ref:`running Dredd inside Docker <docker>`, you may want to use a separate container for the hook handler and then run all your containers together as described in the :ref:`docker-compose` section.
+
+However, hooks were not originally designed with this scenario in mind. Dredd gets a name of (or path to) the hook handler in :option:`--language` and then starts it as a child process. To work around this, `fool Dredd with a dummy script <https://github.com/apiaryio/dredd/issues/748#issuecomment-285355519>`__ and set :option:`--hooks-worker-handler-host` together with :option:`--hooks-worker-handler-port` to point Dredd's TCP communication to the other container.
+
+.. note::
+    The issue described above is tracked in :ghissue:`#755`.

docs/hooks/perl.rst

@@ -23,6 +23,10 @@ Usage
 
    $ dredd apiary.apib http://127.0.0.1:3000 --language=dredd-hooks-perl --hookfiles=./hooks*.pl
 
+
+.. note::
+   If you're running :ref:`Dredd inside Docker <docker>`, read about :ref:`specifics of getting it working together with non-JavaScript hooks <hooks-docker>`.
+
 API Reference
 -------------
 

docs/hooks/php.rst

@@ -30,6 +30,9 @@ Usage
 
    $ dredd apiary.apib http://127.0.0.1:3000 --language=vendor/bin/dredd-hooks-php --hookfiles=./hooks*.php
 
+.. note::
+   If you're running :ref:`Dredd inside Docker <docker>`, read about :ref:`specifics of getting it working together with non-JavaScript hooks <hooks-docker>`.
+
 API Reference
 -------------
 

docs/hooks/python.rst

@@ -23,6 +23,9 @@ Usage
 
    $ dredd apiary.apib http://127.0.0.1:3000 --language=python --hookfiles=./hooks*.py
 
+.. note::
+   If you're running :ref:`Dredd inside Docker <docker>`, read about :ref:`specifics of getting it working together with non-JavaScript hooks <hooks-docker>`.
+
 API Reference
 -------------
 

docs/hooks/ruby.rst

@@ -23,6 +23,9 @@ Usage
 
    $ dredd apiary.apib http://127.0.0.1:3000 --language=ruby --hookfiles=./hooks*.rb
 
+.. note::
+   If you're running :ref:`Dredd inside Docker <docker>`, read about :ref:`specifics of getting it working together with non-JavaScript hooks <hooks-docker>`.
+
 API Reference
 -------------
 

docs/hooks/rust.rst

@@ -19,12 +19,15 @@ Installation
 Usage
 -----
 
-Using Dredd with Rust is slightly different to other languages, as a binary needs to be compiled for execution. The –hookfiles flags should point to compiled hook binaries. See below for an example hooks.rs file to get an idea of what the source file behind the Rust binary would look like.
+Using Dredd with Rust is slightly different to other languages, as a binary needs to be compiled for execution. The :option:`--hookfiles` options should point to compiled hook binaries. See below for an example hooks.rs file to get an idea of what the source file behind the Rust binary would look like.
 
 ::
 
    $ dredd apiary.apib http://127.0.0.1:3000 --server=./rust-web-server-to-test --language=rust --hookfiles=./hook-file-binary
 
+.. note::
+   If you're running :ref:`Dredd inside Docker <docker>`, read about :ref:`specifics of getting it working together with non-JavaScript hooks <hooks-docker>`.
+
 API Reference
 -------------
 

docs/installation.rst

@@ -7,12 +7,16 @@ Installation
 There are several options how to run Dredd on your machine or in your :ref:`continuous-integration`.
 
 
+.. _docker:
 .. _install-docker:
 
 Docker
 ------
 
-Installing Dredd using `Docker <https://docs.docker.com>`__ is the easiest and the most hassle-free option for every major operating system.
+If you are familiar with `Docker <https://docs.docker.com>`__, you can get started with Dredd quickly by using the ready-made `apiaryio/dredd <https://hub.docker.com/r/apiaryio/dredd/>`__ image. Specifics of running Dredd inside Docker are:
+
+- you won't be able to use the :option:`--server` option (see :ref:`docker-compose`)
+- setting up non-JavaScript :ref:`hooks <hooks>` is less straightforward (see :ref:`hooks-docker`)
 
 .. tabs::
 
@@ -37,18 +41,28 @@ Installing Dredd using `Docker <https://docs.docker.com>`__ is the easiest and t
          C:\Users\Susan> docker run -it -v ${pwd}:/api -w /api apiaryio/dredd dredd init
 
 
+.. _docker-compose:
+
+Docker Compose
+~~~~~~~~~~~~~~
+
+Inside Docker it's impossible for Dredd to manage child processes, so the :option:`--server` and :option:`--language` options won't work properly.
+
+Instead, you should have separate containers for each process and run them together with Dredd using `Docker Compose <https://docs.docker.com/compose/overview/>`__. You can `use -\\-abort-on-container-exit and -\\-exit-code-from <https://stackoverflow.com/a/49485880/325365>`__ with Docker Compose to manage the tear down of all the other containers when the Dredd tests finish.
+
+
 .. _install-npm:
 
 npm
 ---
 
-Dredd is a command-line application written in JavaScript, or to be more precise, in `Node.js <https://nodejs.org>`__. If Docker isn't an option for you, it's possible to install Dredd using the `npm <https://www.npmjs.com>`__.
+Dredd is a command-line application written in JavaScript (to be more precise, in `Node.js <https://nodejs.org>`__) and as such can be installed using `npm <https://www.npmjs.com>`__.
 
 
 .. _install-nodejs:
 
-Installing Node.js
-~~~~~~~~~~~~~~~~~~
+Installing Node.js and npm
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. tabs::
 
@@ -72,7 +86,7 @@ Installing Node.js
       - Make sure both ``node --version`` and ``npm --version`` work in your Command Prompt
       - Node.js needs to be at least version 6
 
-.. warning::
+.. note::
    If your internet connection is restricted (VPN, firewall, proxy), you need to `configure npm <https://docs.npmjs.com/misc/config#https-proxy>`__:
 
    .. code-block:: text
@@ -102,7 +116,7 @@ Now that you have everything prepared, you can finally run npm to install Dredd:
 
    npm install dredd --global
 
-.. warning::
+.. note::
    If you get ``EACCES`` permissions errors, try `one of the officially recommended solutions <https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally>`__. In the worst case, you can run the command again with ``sudo``.
 
 You can verify Dredd is correctly installed by printing its version number:
@@ -114,8 +128,8 @@ You can verify Dredd is correctly installed by printing its version number:
 Now you can :ref:`start using Dredd <quickstart>`!
 
 
-Adding Dredd as dev dependency
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Adding Dredd as a 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.