diff --git a/README.md b/README.md deleted file mode 100644 index 0e9d962..0000000 --- a/README.md +++ /dev/null @@ -1,79 +0,0 @@ -# tox-docker - -A [tox](https://tox.readthedocs.io/en/latest/) plugin which runs one or -more [Docker](https://www.docker.com/) containers during the test run. - -[![build status](https://travis-ci.org/tox-dev/tox-docker.svg?branch=master)](https://travis-ci.org/tox-dev/tox-docker) - -## Usage and Installation - -Tox loads all plugins automatically. It is recommended that you install the -tox-docker plugin into the same Python environment as you install tox into, -whether that's a virtualenv, etc. - -You do not need to do anything special when running tox to invoke -tox-docker. You do need to configure your project to request docker -instances (see "Configuration" below). - -## Configuration - -In the `testenv` section, list the Docker images you want to include in -the `docker` multi-line-list. Be sure to include the version tag. - -You can include environment variables to be passed to the docker container -via the `dockerenv` multi-line list. These will also be made available to -your test suite as it runs, as ordinary environment variables: - - [testenv] - docker = - postgres:9-alpine - dockerenv = - POSTGRES_USER=username - POSTGRES_DB=dbname - -## Host and Port Mapping - -tox-docker runs docker with the "publish all ports" option. Any port the -container exposes will be made available to your test suite via environment -variables of the form `___PORT`. For -instance, for the postgresql container, there will be an environment -variable `POSTGRES_5432_TCP_PORT` whose value is the ephemeral port number -that docker has bound the container's port 5432 to. - -Likewise, exposed UDP ports will have environment variables like -`TELEGRAF_8092_UDP_PORT` Since it's not possible to check whether UDP port -is open it's just mapping to environment variable without any checks that -service up and running. - -The host name for each service is also exposed via environment as -`_HOST`, which is `POSTGRES_HOST` and `TELEGRAF_HOST` for -the two examples above. - -*Deprecation Note:* In older versions of tox-docker, the port was exposed as -`--`. This additional environment -variable is deprecated, but will be supported until tox-docker 2.0. - -## Health Checking - -As of version 1.4, tox-docker uses Docker's health checking to determine -when a container is fully running, before it begins your test. For Docker -images that conatain a `HEALTHCHECK` command, tox-docker uses that. - -You may also specify a custom health check in `tox.ini`, in a new section -like: - -``` -[docker:redis:5.0-alpine] -healthcheck_cmd = redis-cli ping | grep -q PONG -healthcheck_interval = 1 -healthcheck_timeout = 1 -healthcheck_retries = 30 -healthcheck_start_period = 0.5 -``` - -The image name -- everything after the `docker:` in the section header -- -must _exactly_ match the image name used in your testenv's `docker` setting. - -Tox-docker will print a message for each container that it is waiting on a -health check from, whether via the container's built-in `HEALTHCHECK` or a -custom health check. diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..f78c171 --- /dev/null +++ b/README.rst @@ -0,0 +1,85 @@ +============ + tox-docker +============ + +A `tox `__ plugin which runs one or +more `Docker `__ containers during the test run. + +.. image:: https://travis-ci.org/tox-dev/tox-docker.svg?branch=master + :target: https://travis-ci.org/tox-dev/tox-docker + :alt: Build Status + +Usage and Installation +---------------------- + +tox loads all plugins automatically. It is recommended that you install the +tox-docker plugin into the same Python environment as you install tox into, +whether that's a virtualenv, etc. + +You do not need to do anything special when running tox to invoke +tox-docker. You do need to configure your project to request docker +instances (see "Configuration" below). + +Configuration +------------- + +In the ``testenv`` section, list the Docker images you want to include in +the ``docker`` multi-line-list. Be sure to include the version tag. + +You can include environment variables to be passed to the docker container +via the ``dockerenv`` multi-line list. These will also be made available to +your test suite as it runs, as ordinary environment variables:: + + [testenv] + docker = + postgres:9-alpine + dockerenv = + POSTGRES_USER=username + POSTGRES_DB=dbname + +Host and Port Mapping +--------------------- + +tox-docker runs docker with the "publish all ports" option. Any port the +container exposes will be made available to your test suite via environment +variables of the form ``___PORT``. +For instance, for the PostgreSQL container, there will be an environment +variable ``POSTGRES_5432_TCP_PORT`` whose value is the ephemeral port number +that docker has bound the container's port 5432 to. + +Likewise, exposed UDP ports will have environment variables like +``TELEGRAF_8092_UDP_PORT`` Since it's not possible to check whether UDP port +is open it's just mapping to environment variable without any checks that +service up and running. + +The host name for each service is also exposed via environment as +``_HOST``, which is ``POSTGRES_HOST`` and ``TELEGRAF_HOST`` for +the two examples above. + +*Deprecation Note:* In older versions of tox-docker, the port was exposed as +``--``. This additional environment +variable is deprecated, but will be supported until tox-docker 2.0. + +Health Checking +--------------- + +As of version 1.4, tox-docker uses Docker's health checking to determine +when a container is fully running, before it begins your test. For Docker +images that contain a ``HEALTHCHECK`` command, tox-docker uses that. + +You may also specify a custom health check in ``tox.ini``, in a new section +like:: + + [docker:redis:5.0-alpine] + healthcheck_cmd = redis-cli ping | grep -q PONG + healthcheck_interval = 1 + healthcheck_timeout = 1 + healthcheck_retries = 30 + healthcheck_start_period = 0.5 + +The image name -- everything after the ``docker:`` in the section header -- +must *exactly* match the image name used in your testenv's ``docker`` setting. + +tox-docker will print a message for each container that it is waiting on a +health check from, whether via the container's built-in ``HEALTHCHECK`` or a +custom health check. diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..505216b --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,36 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +import os + +import vcversioner + + +ROOT_DIR = os.path.dirname( + os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) + + +# -- Project information ----------------------------------------------------- + +project = 'tox-docker' +copyright = '2019, Dan Crosta' +author = 'Dan Crosta' +version = release = vcversioner.find_version(root=ROOT_DIR).version + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ +] + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..a6210d3 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1 @@ +.. include:: ../../README.rst diff --git a/tox.ini b/tox.ini index 86c990b..da12773 100644 --- a/tox.ini +++ b/tox.ini @@ -7,6 +7,15 @@ envlist = integration,registry,healthcheck-builtin,healthcheck-custom commands_pre = python capture_containers_and_volumes.py commands_post = python assert_containers_and_volumes_unchanged.py +[testenv:docs] +deps = + sphinx + sphinx_rtd_theme + vcversioner +commands = sphinx-build -W -b html docs/source docs/build/html +commands_pre = +commands_post = + [testenv:integration] docker = nginx:1.13-alpine