diff --git a/README.md b/README.md index c62273fa7..4c1cf0418 100644 --- a/README.md +++ b/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 " + +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). diff --git a/src/sphinx/DetailedTopics/docker.rst b/src/sphinx/DetailedTopics/docker.rst new file mode 100644 index 000000000..d3383ef9e --- /dev/null +++ b/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 " + +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. diff --git a/src/sphinx/DetailedTopics/index.rst b/src/sphinx/DetailedTopics/index.rst index a179f4272..6e03c6492 100644 --- a/src/sphinx/DetailedTopics/index.rst +++ b/src/sphinx/DetailedTopics/index.rst @@ -11,4 +11,5 @@ Advanced Topics linux.rst redhat.rst debian.rst - windows.rst \ No newline at end of file + windows.rst + docker.rst \ No newline at end of file diff --git a/src/sphinx/GettingStartedApplications/MyFirstProject.rst b/src/sphinx/GettingStartedApplications/MyFirstProject.rst index 04f01430b..3229d95c4 100644 --- a/src/sphinx/GettingStartedApplications/MyFirstProject.rst +++ b/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 diff --git a/src/sphinx/GettingStartedServers/MyFirstProject.rst b/src/sphinx/GettingStartedServers/MyFirstProject.rst index f84426cf8..f2bc2ee62 100644 --- a/src/sphinx/GettingStartedServers/MyFirstProject.rst +++ b/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 " + + +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 ` to use with our script. diff --git a/src/sphinx/index.rst b/src/sphinx/index.rst index 1b7ec73a3..714ebaac0 100644 --- a/src/sphinx/index.rst +++ b/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 diff --git a/src/sphinx/installation.rst b/src/sphinx/installation.rst index be154d75c..444cd5092 100644 --- a/src/sphinx/installation.rst +++ b/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. \ No newline at end of file