FIX #443 Refactor documentation. Work in progress

src/sphinx/formats/debian.rst

@@ -0,0 +1,167 @@
+Debian Plugin
+=============
+
+The debian package specification is very robust and powerful.  If you wish to do any advanced features, it's best to understand how
+the underlying packaging system works.  http://tldp.org/HOWTO/html_single/Debian-Binary-Package-Building-HOWTO/ is an excellent tutorial.
+
+SBT Native Packager provides two ways to build debian packages. A native one, where you need ``dpkg-deb`` installed
+or a java, platform independent approach with `jdeb <https://github.com/tcurdt/jdeb>`_. By default the _native_ implementation
+is activated.
+
+.. contents:: 
+  :depth: 2
+
+
+.. raw:: html
+
+  <div class="alert alert-info" role="alert">
+    <span class="glyphicon glyphicon-info-sign" aria-hidden="true"></span>
+    The debian plugin dependens on the linux plugin. For general linux settings read the 
+    <a href="linux.html">Linux Plugin Documentation</a>
+  </div>
+
+Requirements
+------------
+
+If you use the _native_  debian package implementation you need the following applications installed:
+
+* dpkg-deb
+* dpkg-sig
+* dpkg-genchanges
+* lintian
+* fakeroot
+
+Build
+-----
+
+.. code-block:: bash
+
+  sbt debian:packageBin
+
+Required Settings
+~~~~~~~~~~~~~~~~~
+
+A debian package needs some mandatory settings to be valid. Make sure
+you have these settings in your build:
+
+.. code-block:: scala
+
+    name := "Debian Example"
+
+    version := "1.0"
+
+    maintainer := "Max Smith <max.smith@yourcompany.io>"
+
+    packageSummary := "Hello World Debian Package"
+
+    packageDescription := """A fun package description of our software,
+      with multiple lines."""
+
+1.0 or higher
+~~~~~~~~~~~~~
+
+Enable the debian plugin to activate the native package implementation.
+
+.. code-block:: scala
+
+  enablePlugins(DebianPlugin)
+
+If you want to use the java based implementation, enable the following plugin.
+
+.. code-block:: scala
+
+  enablePlugins(JDebPackaging)
+
+0.8 or lower
+~~~~~~~~~~~~
+
+For this versions debian packaging is automatically activated.
+See the `Getting Started </GettingStarted>` page for informations
+on how to enable sbt native packager.
+
+If you want to enable `jdeb` packaging add the following to your `build.sbt`
+
+.. code-block:: scala
+
+    packageBin in Debian <<= debianJDebPackaging in Debian
+    
+
+Settings
+--------
+
+Debian requires the following specific settings:
+
+  ``name in Debian``
+    The name of the package for debian (if different from general linux name).
+
+  ``version in Debian``
+    The debian-friendly version of the package.   Should be of the form ``x.y.z-build-aa``.
+
+  ``debianPackageDependencies in Debian``
+    The list of debian packages that this package depends on.
+
+  ``debianPackageRecommends in Debian``
+    The list of debian packages that are recommended to be installed with this package.
+
+  ``linuxPackageMappings in Debian``
+    Debian requires a ``/usr/share/doc/{package name}/changelog.gz`` file that describes
+    the version changes in this package. These should be appended to the base linux versions.
+
+  ``debianMaintainerScripts``
+    These are the packaging scripts themselves used by ``dpkg-deb`` to build your debian.  These
+    scripts are used when installing/uninstalling a debian, like prerm, postinstall, etc.  These scripts
+    are placed in the ``DEBIAN`` file when building.    Some of these files can be autogenerated,
+    for example when using a package archetype, like server_application.  Howeve, any autogenerated file
+    can be overridden by placing your own files in the ``src/debian/DEBIAN`` directory.
+
+  ``changelog in Debian``
+    This is the changelog used by ``dpkg-genchanges`` to create the .changes file. This will allow you to
+    upload the debian package to a mirror.
+
+
+Tasks
+-----
+
+The Debian support grants the following commands:
+
+  ``debian:package-bin``
+    Generates the ``.deb`` package for this project.
+
+  ``debian:lintian``
+    Generates the ``.deb`` file and runs the ``lintian`` command to look for issues in the package.  Useful for debugging.
+
+  ``debian:gen-changes``
+    Generates the ``.changes``, and therefore the ``.deb`` package for this project.
+
+
+Customize
+---------------
+
+This section contains example on how you can customize your debian build.
+
+Customizing Debian Metadata
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A Debian package provides metadata, which includes **dependencies** and **recommendations**.
+A basic example to depend on java and recommend a git installation.
+
+.. code-block:: scala
+
+    debianPackageDependencies in Debian ++= Seq("java2-runtime", "bash (>= 2.05a-11)")
+
+    debianPackageRecommends in Debian += "git"
+    
+To hook into the debian package lifecycle (https://wiki.debian.org/MaintainerScripts) you
+can add ``preinst`` , ``postinst`` , ``prerm`` and/or ``postrm`` scripts. Just place them into
+``src/debian/DEBIAN``.
+
+If you use the ``packageArchetype.java_server`` there are predefined ``postinst`` and
+``preinst`` files, which start/stop the application on install/remove calls. Existing
+maintainer scripts will be extended not overridden.
+
+Your control scripts are in a different castle.. directory? No problem.
+
+.. code-block:: scala
+
+    debianControlScriptsDirectory <<= (sourceDirectory) apply (_ / "deb" / "control")
+

src/sphinx/formats/docker.rst

@@ -0,0 +1,154 @@
+Docker Plugin
+=============
+
+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.
+
+.. contents:: 
+  :depth: 2
+
+Requirements
+------------
+
+You need the docker console client installed. SBT Native Packager doesn't use the REST API.
+
+
+Build
+-----
+
+.. code-block:: bash
+
+  sbt docker:publishLocal
+  
+
+Required Settings
+~~~~~~~~~~~~~~~~~
+
+Docker images require the following setting:
+
+.. code-block:: scala
+
+    maintainer in Docker := "John Smith <john.smith@example.com>"
+
+    
+1.0 or higher
+~~~~~~~~~~~~~
+
+.. code-block:: scala
+
+  enablePlugins(DockerPlugin)
+
+0.8.x
+~~~~~
+
+For this versions docker packaging is automatically activated.
+See the `Getting Started </GettingStarted>` page for informations
+on how to enable sbt native packager.
+
+
+Settings
+--------
+
+Informational Settings
+~~~~~~~~~~~~~~~~~~~~~~
+
+
+  ``packageName in Docker``
+    The name of the package for Docker (if different from general name).
+    This will only affect the image 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.
+
+  ``dockerEntrypoint in Docker``
+    Overrides the default entrypoint for docker-specific service discovery tasks before running the application.
+    Defaults to the bash executable script, available at ``bin/<script name>`` in the current ``WORKDIR`` of ``/opt/docker``.
+
+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]``.
+
+  ``dockerUpdateLatest``
+    The flag to automatic update the latest tag when the ``docker:publish`` task is run. Default value is ``FALSE``.
+
+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.
+
+
+Customize
+---------
+
+Docker Image Name
+~~~~~~~~~~~~~~~~~
+
+.. code-block:: scala
+
+    packageName in Docker := packageName.value
+    
+    version in Docker := version.value
+    
+Docker Base Image
+~~~~~~~~~~~~~~~~~
+
+.. code-block:: scala
+
+    dockerBaseImage := "dockerfile/java"
+    
+Docker Repository
+~~~~~~~~~~~~~~~~~
+
+.. code-block:: scala
+
+    dockerRepository := Some("dockeruser")
+    
+Docker Image Customization
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: scala
+
+    dockerExposedPorts in Docker := Seq(9000, 9443)
+    
+    dockerExposedVolumes in Docker := Seq("/opt/docker/logs")
+
+Install Location
+~~~~~~~~~~~~~~~~
+The path to which the application is written can be changed with the setting.
+The files from ``mappings in Docker`` are extracted underneath this directory.
+
+.. code-block:: scala
+  
+  defaultLinuxInstallLocation in Docker := "/opt/docker"