Merge pull request #281 from garycoady/wip/docker-documentation

Documentation for docker support.

README.md

@@ -40,6 +40,19 @@ To enable this feature follow [My First Packaged Server Project guide](http://ww
 
 Any help on testing and improving this feature is appreciated so feel free to report bugs or making PR.
 
+## Experimental Docker support ##
+
+Native packager now provides experimental `Docker` images.
+To enable this feature follow [My First Packaged Server Project guide](http://www.scala-sbt.org/sbt-native-packager/GettingStartedServers/MyFirstProject.html) and use one of the provided Docker tasks for generating images.
+The only essential extra setting for creating a local image for testing is:
+
+    maintainer in Docker := "John Smith <john.smith@example.com>"
+
+To publish the image, ``dockerRepository`` should also be set.
+
+As with the `systemd` support, help with testing and improvements is appreciated.
+
+
 ## Documentation ##
 
 There's a complete "getting started" guide and more detailed topics available at [the sbt-native-packager site](http://scala-sbt.org/sbt-native-packager).  

src/sphinx/DetailedTopics/docker.rst

@@ -0,0 +1,84 @@
+Docker
+======
+
+Docker images describe how to set up a container for running an application, including what files are present, and what program to run.
+
+  https://docs.docker.com/introduction/understanding-docker/ provides an introduction to Docker.
+  https://docs.docker.com/reference/builder/ describes the Dockerfile; a file which describes how to set up the image.
+
+  sbt-native-packager focuses on creating a Docker image which can "just run" the application built by SBT.
+
+Settings
+--------
+
+Docker images require the following setting:
+
+.. code-block:: scala
+
+    maintainer in Linux := "John Smith <john.smith@example.com>"
+
+It may require these settings:
+
+.. code-block:: scala
+
+    name in Docker := "sbt",
+    version in Docker <<= sbtVersion,
+    dockerBaseImage := "dockerfile/java",
+    dockerRepository := Some("dockeruser"),
+    dockerExposedPorts in Docker := Seq(9000, 9443),
+    dockerExposedVolumes in Docker := Seq("/opt/docker/logs")
+
+Informational Settings
+~~~~~~~~~~~~~~~~~~~~~~
+
+  ``name in Docker``
+    The name of the package for Docker (if different from general name).
+
+  ``version in Docker``
+    The version of the package for Docker (if different from general version).  Often takes the form ``x.y.z``.
+
+  ``maintainer in Docker``
+    The maintainer of the package, required by the Dockerfile format.
+
+Environment Settings
+~~~~~~~~~~~~~~~~~~~~
+
+  ``dockerBaseImage``
+    The image to use as a base for running the application. It should include binaries on the path for ``chown``, ``mkdir``, have a discoverable ``java`` binary, and include the user configured by ``daemonUser`` (``daemon``, by default).
+
+  ``daemonUser in Docker``
+    The user to use when executing the application. Files below the install path also have their ownership set to this user.
+
+  ``dockerExposedPorts in Docker``
+    A list of ports to expose from the Docker image.
+
+  ``dockerExposedVolumes in Docker``
+    A list of data volumes to make available in the Docker image.
+
+Publishing Settings
+~~~~~~~~~~~~~~~~~~~
+
+  ``dockerRepository``
+    The repository to which the image is pushed when the ``docker:publish`` task is run. This should be of the form ``[username]`` (assumes use of the ``index.docker.io`` repository) or ``[repository.host]/[username]``.
+
+
+Tasks
+-----
+The Docker support provides the following commands:
+
+  ``docker:stage``
+    Generates a directory with the Dockerfile and environment prepared for creating a Docker image.
+
+  ``docker:publishLocal``
+    Builds an image using the local Docker server.
+
+  ``docker:publish``
+    Builds an image using the local Docker server, and pushes it to the configured remote repository.
+
+
+Install Location
+----------------
+The path to which the application is written can be changed with the setting
+
+  ``defaultLinuxInstallLocation in Docker``
+    The files from ``mappings in Docker`` are extracted underneath this directory.

src/sphinx/DetailedTopics/index.rst

@@ -11,4 +11,5 @@ Advanced Topics
    linux.rst
    redhat.rst
    debian.rst
-   windows.rst
+   windows.rst
+   docker.rst

src/sphinx/GettingStartedApplications/MyFirstProject.rst

@@ -126,9 +126,10 @@ We can generate other packages via the following tasks.  Here's a complete list
 * ``universal:packageBin`` - Generates a universal zip file
 * ``universal:packageZipTarball`` - Generates a universal tgz file
 * ``debian:packageBin`` - Generates a deb
+* ``docker:publishLocal`` - Builds a Docker image using the local Docker server
 * ``rpm:packageBin`` - Generates an rpm
 * ``universal::packageOsxDmg`` - Generates a DMG file with the same contents as the universal zip/tgz.
-* ``windows:packageBin`` - Generates an MSI 
+* ``windows:packageBin`` - Generates an MSI
 
 While we only covered the necessary configuration for ``debian``, each package type beyond ``universal`` requires some additonal
 configuration relative to that packager.  For example, windows MSIs require UUIDs for all packages which are used to uniquely

src/sphinx/GettingStartedServers/MyFirstProject.rst

@@ -108,6 +108,44 @@ Windows
 
 Planned for 0.8.0
 
+Docker
+******
+
+A basic ``build.sbt`` for Docker requires the ``linux.Keys.maintainer`` setting:
+
+
+.. code-block:: scala
+
+    maintainer in Linux := "John Smith <john.smith@example.com>"
+
+
+There are a number of other available settings:
+
+.. code-block:: scala
+
+    daemonUser in Docker := normalizedName.value // user in the Docker image which will execute the application (must already exist)
+
+    dockerBaseImage := "dockerfile/java" // Docker image to use as a base for the application image
+
+    dockerExposedPorts in Docker := Seq(9000, 9443) // Ports to expose from container for Docker container linking
+
+    dockerExposedVolumes in Docker := Seq("/opt/docker/logs") // Data volumes to make available in image
+
+    dockerRepository := Some("dockerusername") // Repository used when publishing Docker image
+
+A directory with appropriate contents for building a Docker image can be created with ::
+
+  docker:stage
+
+To build an image and store it in the local Docker server, use ::
+
+  docker:publishLocal
+
+To build an image, publish locally, and then push to a remote Docker repository, use ::
+
+  docker:publish
+
+
 Next, let's look at how to :doc:`Add configuration files <AddingConfiguration>` to use with our script.
 
 

src/sphinx/index.rst

@@ -8,6 +8,7 @@ to allow native packages to be created for all major operating systems, includin
 * Debian DEB packages
 * RedHat RPM packages
 * Universal (Zipped) packages
+* Docker images
 
 
 

src/sphinx/installation.rst

@@ -53,3 +53,13 @@ Creating ``tgz`` or ``txz`` requires the use of the following command line tools
 - ``gzip``
 - ``xz``
 - ``tar``
+
+Docker
+------
+
+Creating Docker images requires the use of the following command line tools:
+
+- ``docker``
+
+It is currently not possible to provide authentication for Docker repositories from within the build. The ``docker`` binary used by the build should already have been configured with the appropriate authentication details.
+See https://docs.docker.com/reference/commandline/cli/#login.