.. _development_docker:

================================================================================
Building Docker Containers for PDAL
================================================================================


PDAL's :ref:`repository <source>` is linked to `DockerHub`_ for automatic building
of `Docker`_ containers. PDAL keeps three Docker containers current.

* ``pdal/dependencies:latest`` -- PDAL's dependencies
* ``pdal/pdal:latest`` -- PDAL master
* ``pdal/pdal:1.5`` -- PDAL maintenance branch




.. _`Docker`: https://www.docker.com/
.. _`DockerHub`: https://hub.docker.com/r/pdal/pdal/


.. note::

    Containers are built upon the `Dependences`_ container, but the
    `Dependences`_ container is not pinned to specific Xenial or PDAL release
    times. It corresponds to where ever the ``dependencies`` tag of
    the PDAL source tree at https://github.com/PDAL/PDAL resides

.. _`DockerHub`: https://hub.docker.com/r/pdal/pdal/

Dependences
================================================================================

The PDAL dependencies Docker container is used by both the latest and release
branch Docker containers. The dependencies container is also used during
:ref:`integration` testing by Travis. It is built using the
Dockerfile at https://github.com/PDAL/PDAL/blob/master/scripts/docker/dependencies/Dockerfile

The ``pdal/dependencies:latest`` image is regenerated by force-pushing a tag
of the SHA you wish to use to have `DockerHub`_ build.

::

    git tag -f dependencies
    git push origin refs/tags/dependencies -f

.. note::

    The dependencies container is currently built upon `Ubuntu Xenial`_. When
    the next Ubuntu LTS is released, the PDAL project will likely move to it.

.. _`Ubuntu Xenial`: http://releases.ubuntu.com/16.04/

Maintenance
================================================================================

A PDAL container corresponding to the last major release is automatically created
and maintained with every commit to the active release branch. For example, the
``1.4-maintenance`` branch will have a corresponding ``pdal/pdal:1.4`` container
made with every commit on `DockerHub`_. Users are encouraged to use these containers
for testing, bug confirmation, and deployment

.. figure:: ../images/docker-maintenance-branch.png

    Docker containers on maintenance branch correspond to
    major PDAL releases.


Latest (or master)
================================================================================

A PDAL container corresponding to a developer-selected release point is
made available at ``pdal/pdal:latest`` and corresponds to the manual push
of a ``docker-master`` tag by PDAL developers. This container is typically
used for testing and verification of fixes, and it is recommended that users
looking to depend on PDAL's Docker containers always use known release
versions off of the last stable release branch.

.. warning::

    You should be using the `Maintenance`_ Docker container for any
    production-oriented operations. Only use the latest one to test
    or prototype a latest, unreleased feature.

.. figure:: ../images/docker-master-branch.png

    The ``pdal/pdal:latest`` branch is current relative to the
    ``docker-master`` branch in GitHub.

::

    $ git tag -f docker-master
    $ git push origin refs/tags/docker-master -f
