Describe server loading options in server docs

src/sphinx/DetailedTopics/redhat.rst

@@ -124,7 +124,7 @@ Example Settings
 
 
 rpmChangelogFile
-----------
+----------------
 The rpmChangelogFile property allows you to set a source that will be imported and used on the RPM generation. So if you use rpm commands to see the changelog it brings that information. You have to create the content on that file following the RPM conventions that are available here http://fedoraproject.org/wiki/Packaging:Guidelines#Changelogs.
 
 Example Settings

src/sphinx/GettingStartedApplications/AddingConfiguration.rst

@@ -130,5 +130,18 @@ One means of doing this is hooking the ``batScriptExtraDefines`` key.  This allo
 
 Now, the windows version will also load the configuration from the ``conf/`` directory of the package.
 
+More Complex Scripts
+--------------------
+
+As you read earlier the ``bashScriptExtraDefines`` sequence allows you to add new lines to the default bash script used to start the application.
+This is useful when you need a setting which isn't mean for the command-line parameter list passed to the java process. The lines added to
+``bashScriptExtraDefines`` are placed near the end of the script and have access to a number of utility bash functions (e.g. ``addJava``,
+``addApp``, ``addResidual``, ``addDebugger``). You can add lines to this script as we did for the Typesage config file above. For more complex
+scripts you can also inject a seperate file managed in your source tree or resource directory: ::
+
+    bashScriptExtraDefines ++= IO.readLines(baseDirectory.value / "scripts" / "extra.sh")
+
+This will add the contents of ``/scripts/extra.sh`` in the resource directory to the bash script. Note you should always concatenate lines
+to ``bashScriptExtraDefines`` as other stages in the pipeline may be include linex to the start-script. 
 
 Next, let's :doc:`add some generated files <GeneratingFiles>`.

src/sphinx/GettingStartedApplications/OverridingTemplates.rst

@@ -1,10 +1,20 @@
-Overriding templates
-####################
+Template Customization and Overrides
+####################################
 
 While the native packager tries to provide robust BASH/BAT scripts for your applications, they may not always be enough.
-The native packager provides a mechanism where the template used to create each script can be directly overridden.
+The native packager provides a mechanism where the template used to create each script can be customized or directly 
+overridden. 
 
-Let's override the default BASH template.  To do so, we'll create a file in ``src/templates/bash-template`` 
+The easiest way to add functionality to the default script is by adding ``bashScriptExtraDefines`` :doc:`as described
+in adding configuration for applications </GettingStartedApplications/AddingConfiguration>`. Customizing the bash
+script will effect all platform-specific builds. The server archetype provides a further level of customization for
+specific System Loaders and Package types. These template file are described in 
+:doc:`configuring servers </GettingStartedServers/AddingConfiguration>`.
+
+Overriding Complete Templates
+-----------------------------
+
+In order to override full templates, like the default bash script, create a file in ``src/templates/bash-template`` 
 
 .. code-block:: bash
 
@@ -67,4 +77,4 @@ While we just replaced the default templates with simpler templates, this should
 
 In general, the templates are intended to provide enough utility that customization is only necessary for truly custom scripts.
 
-Next, let's look at how to :doc:`document the application <WritingDocumentation>`.
+Next, let's look at how to :doc:`document the application <WritingDocumentation>`.

src/sphinx/GettingStartedApplications/WritingDocumentation.rst

@@ -51,4 +51,4 @@ distribution.  The resulting man page is stored in ``/usr/share/man/man1/example
 TODO - A bit more on other documentation methods.
 
 
-That's the end fo the getting started guide for Java Applications!  Feel free to read the guide on Java Servers, which offers a few differences in how configuration is done, necessary for packaging to underlying systems.
+That's the end fo the getting started guide for Java Applications!  Feel free to read the guide on :doc:`Java Servers <GettingStartedServers>`, which offers a few differences in how configuration is done for packaging to underlying systems.

src/sphinx/GettingStartedApplications/index.rst

@@ -7,7 +7,16 @@ The sbt-native-packager is an sbt plugin for bundling your application for a var
 
 The sbt-native-packager attempts to make building packages for different operating systems easier.  While it provides
 some basic abstractions around packaging, it also allows you to dig down into the nuts and bolts of each platform as
-neeeded to generate the best package possible.   
+neeeded to generate the best package possible. 
+
+Application packaging focuses on how your application is launched (via a ``bash`` or ``bat`` script), how dependencies
+are managed and how configuration and other auxillary files are included in the final distributable.
+
+Additionally there is :doc:`Server Packaging <GettingStartedServers>` which provides platform-specific
+functionality for installing your application in server environments. You can customize specific debian and rpm packaging
+for a variety of platforms and init service loaders including Upstart, System V and SystemD (experimental).
+
+Sbt-Native-Packager is highly customizable and you can add or override several aspects of application and server packaging.
 
 .. toctree::
    :maxdepth: 1

src/sphinx/GettingStartedServers/AddingConfiguration.rst

@@ -9,7 +9,8 @@ There are generally two types of configurations:
 * Configuring the Application itself.
 
 The server archetype provides you with a special feature to configure your application
-with a single file. As this file is OS dependend, each OS gets section.
+with a single file outside of customizing the ``bash`` or ``bat`` script for applications. 
+As this file is OS dependend, each OS gets section.
 
 Linux
 *****
@@ -64,7 +65,7 @@ The usual ``JAVA_OPTS`` can be used to override settings. This is a nice way to
 different jvm settings with just restarting the jvm.
 
 Windows
-*****
+*******
 
 Support planned for 0.8.0
 
@@ -74,5 +75,7 @@ Example Configurations
 A list of very small configuration settings can be found at `sbt-native-packager-examples`_
 
     .. _sbt-native-packager-examples: https://github.com/muuki88/sbt-native-packager-examples
-
-Next, let's :doc:`how to override start templates <OverrdingTemplates>`.
+
+In addition to adding configuration settings it's possible to override parts of the start/stop scripts
+used in the ``java_server`` archetype or replace entire templates. The next section on 
+:doc:`how to override start templates <OverridingTemplates>` explains this feature.

src/sphinx/GettingStartedServers/OverrdingTemplates.rst → src/sphinx/GettingStartedServers/OverridingTemplates.rst

@@ -11,6 +11,22 @@ For the ``java_server`` package lifecycle scripts are customized to provide the
 For this purpose *sbt-native-packager* ships with some predefined templates. These can be
 overriden with different techniques, depending on the packaging system.
 
+Partially Replace Template Functionality
+========================================
+
+Most sbt-native-packager scripts are broken up into partial templates in the `resources directory 
+<https://github.com/sbt/sbt-native-packager/tree/master/src/main/resources/com/typesafe/sbt/packager>`_. 
+You can override these default template snippets by adding to the ``linuxScriptReplacements`` map. As
+an example you can change the ``loader-functions`` which starts/stop services based on a certain ```ServerLoader```:
+
+.. code-block:: scala
+
+  linuxScriptReplacements += "loader-functions" -> TemplateWriter.generateScript(getClass.getResource("/custom-loader-functions"), Nil)
+
+The ``custom-loader-functions`` file must declare the ``startService()`` and ``stopService()`` functions used in various
+service management scripts.
+
+
 RPM Scriptlets
 ==============
 

src/sphinx/GettingStartedServers/index.rst

@@ -5,25 +5,92 @@ The sbt-native-packager is an sbt plugin for bundling your server for a variety
 
 **Note:** Please follow the :ref:`Installation` instructions for how to set it up on a project.
 
-The sbt-native-packager attempts to make building packages for different operating systems easier.  While it provides
+In the :doc:`Application Packaging <GettingStartedApplications>` section we described how to build and
+customize settings related to the application. Sbt-Native-Packager provides a further level for servers
+which define how applications are installed and initialized for various platforms. 
+be customized for specific platforms. While it provides
 some basic abstractions around packaging, it also allows you to dig down into the nuts and bolts of each platform as
 neeeded to generate the best package possible.   
 
-Currently the native package supports the following installation targets for servers:
-
-+---------------+--------------------+-----------+
-| Platform      |  Service Manager   |  Working  |
-+===============+====================+===========+
-| Ubuntu        | Upstart            |    X      |
-+---------------+--------------------+-----------+
-| Ubuntu        | System V           |    X      |
-+---------------+--------------------+-----------+
-| CentOS        | System V           |    X      |
-+---------------+--------------------+-----------+
-| Fedora        | System V           |    X      |
-+---------------+--------------------+-----------+
-| Windows       | Windows Services   |           |
-+---------------+--------------------+-----------+
+Service Managers
+================
+
+Platforms are tied to both package managers (Rpm, Debian) and Service Managers (System V, Upstart, SystemD). By 
+default the native packager will configure a service manager to run the daemon process. The available 
+configurations are:
+
++---------------+--------------------+--------------+
+| Platform      |  Service Manager   |  Working     |
++===============+====================+==============+
+| Ubuntu        | Upstart (Default)  |    X         |
++---------------+--------------------+--------------+
+| Ubuntu        | System V           |    X         |
++---------------+--------------------+--------------+
+| CentOS        | System V (Default) |    X         |
++---------------+--------------------+--------------+
+| CentOS 6.5    | Upstart            |    X         |
++---------------+--------------------+--------------+
+| Fedora        | System V (Default) |    X         |
++---------------+--------------------+--------------+
+| Fedora        | systemd            | experimental |
++---------------+--------------------+--------------+
+| Windows       | Windows Services   |              |
++---------------+--------------------+--------------+
+
+Changing Service Managers
+=========================
+
+It is possible to change the default Service Manager for a given platform by specifying a ``ServerLoader``. To use 
+Upstart for an Rpm package simply:
+
+.. code-block:: scala
+
+    serverLoading in Rpm := ServerLoader.Upstart
+
+
+*As a side note Fedora/RHEL/Centos family of linux          
+specifies* ``Default requiretty`` *in its* ``/etc/sudoers`` 
+*file. This prevents the default Upstart script from working 
+correctly as it uses sudo to run the application            
+as the* ``daemonUser`` *. Simply disable requiretty          
+to use Upstart or modify the Upstart template.*             
+
+Sbt Native Packager leverages templating to customize various start/stop scripts and pre/post install tasks. 
+The :doc:`templating reference <OverridingTemplates>` describes this functionality in-depth.
+As an example, to alter the ``loader-functions`` which manage the specific start and stop process commands 
+for SystemLoaders you can to the ``linuxScriptReplacements`` map:
+
+.. code-block:: scala
+
+  linuxScriptReplacements += "loader-functions" -> TemplateWriter.generateScript(getClass.getResource("/custom-loader-functions"), Nil)
+
+which will add the following resource file to use start/stop instead of initctl in the post install script:
+
+.. code-block:: bash
+
+  startService() {
+      app_name=$1
+      start $app_name 
+  }
+
+  stopService() {
+      app_name=$1
+      stop $app_name 
+  }
+
+The :doc:`debian <DetailedTopics/debian>` and :doc:`redhat </DetailedTopics/redhat>` pages have further information on overriding distribution scpecific actions.
+
+SystemD Support
+================
+
+There is also experimental systemd support for Fedora release 20 (Heisenbug). You can use the ```Systemd``` server loader:
+
+.. code-block:: scala
+
+   serverLoading in Rpm:= ServerLoader.Systemd
+
+There is only partial systemd support in Ubuntu 14.04 LTS which prevents sbt-native-packager systemd from working correctly on
+Ubuntu.
 
 What is a Server Archetype
 ==========================

src/sphinx/documentation.rst

@@ -0,0 +1,20 @@
+Contributing Documentation
+##########################
+
+You can clone the `sbt-native-packager GitHub repo <https://github.com/sbt/sbt-native-packager>`_ and modify
+the `rst files <http://sphinx-doc.org/rest.html>`_ in the 
+`src/sphinx/ <https://github.com/sbt/sbt-native-packager/tree/master/src/sphinx>`_ directory. 
+
+The site is generated with the `sbt-site <https://github.com/sbt/sbt-site>`_ plugin. You'll need the following
+dependencies installed:
+
+* python-sphinx
+* python-pip
+
+and the ``sphinx_bootstrap_theme`` library available via pip: ::
+
+    pip install sphinx_bootstrap_theme
+
+
+See `the sbt-native-packager developer guide <https://github.com/sbt/sbt-native-packager/wiki/Developer-Guide#documentation>`_
+for more information.

src/sphinx/index.rst

@@ -2,21 +2,20 @@ SBT - Native Packager Plugin
 ############################
 
 This is the documentation for the sbt-native-packager plugin.  This plugin aims
-to allow native packages to be created for all major operating systems, including:
+to allow easy generation of native packages for all major operating systems, including:
 
 * Windows MSI files
 * Debian DEB packages
 * RedHat RPM packages
-* Universal (Zipped) packages
 * Docker images
-
-
+* Universal (Zipped) packages for easily-launchable start scripts
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    installation.rst
    /GettingStartedApplications/index.rst
    /GettingStartedServers/index.rst
    /DetailedTopics/index.rst
+   documentation.rst