Merge pull request #212 from sbt/wip/getting-started-guide-additions

Wip/getting started guide additions

Author: jsuereth

src/sphinx/GettingStartedServers/AddingConfiguration.rst

@@ -0,0 +1,78 @@
+Adding configuration
+####################
+
+After :doc:`creating a package <MyFirstProject>`, the very next thing needed, usually, is the ability for users/ops to customize the application once it's deployed.   Let's add some configuration to the newly deployed application.
+
+There are generally two types of configurations:
+
+* Configuring the JVM and the process
+* 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.
+
+Linux
+*****
+
+Create ``src/templates/etc-default`` with the following template
+
+.. code-block :: bash
+
+    # Available replacements 
+    # ------------------------------------------------
+    # ${{author}}           debian author
+    # ${{descr}}            debian package description
+    # ${{exec}}             startup script name
+    # ${{chdir}}            app directory
+    # ${{retries}}          retries for startup
+    # ${{retryTimeout}}     retry timeout
+    # ${{app_name}}         normalized app name
+    # ${{daemon_user}}      daemon user
+    # -------------------------------------------------
+
+    # Setting -Xmx and -Xms in Megabyte
+    # -mem 1024
+
+    # Setting -X directly (-J is stripped)
+    # -J-X
+    # -J-Xmx1024
+
+    # Add additional jvm parameters
+    # -Dkey=val
+
+    # For play applications you may set
+    # -Dpidfile.path=/var/run/${{app_name}}/play.pid
+
+    # Turn on JVM debugging, open at the given port
+    # -jvm-debug <port>  
+
+    # Don't run the java version check
+    # -no-version-check
+    
+    # enabling debug and sending -d as app argument
+    # the '--' prevents app-parameter swalloing when
+    # using a reserved parameter. See #184
+    # -d -- -d
+
+The file will be installed to ``/etc/default/<normalizedName>`` and read from there
+by the startscript.
+
+Environment variables
+=====================
+
+The usual ``JAVA_OPTS`` can be used to override settings. This is a nice way to test
+different jvm settings with just restarting the jvm.
+
+Windows
+*****
+
+Support planned for 0.8.0
+
+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>`.

src/sphinx/GettingStartedServers/MyFirstProject.rst

@@ -0,0 +1,90 @@
+My First Packaged Server Project
+################################
+
+Follow the instructions for the basic ``java_application`` setup in :doc:`../GettingStartedApplications/index` to get a working build and
+understand the core concepts of sbt-native-packager. Based on this configuration we exchange
+in our ``build.sbt``
+
+.. code-block:: scala
+
+    packageArchetype.java_application
+    
+with
+
+.. code-block:: scala
+
+    packageArchetype.java_server
+
+
+which will activate all server specific settings. As the server settings are dependent
+on which OS your using the following sections will provide details for each supported
+OS.
+
+Linux
+*****
+
+A basic ``build.sbt`` for the supported ``rpm`` and ``deb`` packaging systems
+require the following information:
+
+.. code-block:: scala
+
+    maintainer in Linux := "John Smith <[email protected]>"
+
+    packageSummary in Linux := "A small package summary"
+
+    packageDescription := "A longer description of your application"
+    
+
+There are additional parameters available to configure. 
+
+.. code-block:: scala
+
+    daemonUser in Linux := normalizedName.value // user which will execute the application
+    
+    daemonGroup in Linux := daemonUser.value    // group which will execute the application
+
+
+Debian (.deb)
+=============
+
+A basic ``build.sbt`` for debian requires only the Linuxs settings. You can build your
+server application with
+
+::
+
+    debian:packageBin
+    
+
+Ubuntu provides two different bootsystems, SystemV and Upstart (default). To switch between
+both you can add this to your ``build.sbt``
+
+.. code-block:: scala
+
+    import com.typesafe.sbt.packager.archetypes.ServerLoader.{SystemV, Upstart}
+    
+    serverLoading in Debian := SystemV
+    
+RPM (.rpm)
+==========
+
+A basic ``build.sbt`` for rpm requires the Linuxs settings and
+
+.. code-block:: scala
+    
+    rpmVendor := "Your organization Inc."
+    
+Build your rpm package with ::
+
+    rpm:packageBin
+    
+The output is partially on ``stderr`` which is a bit confusing. If the build
+ends with *success* you are fine.
+
+Windows
+*******
+
+Planned for 0.8.0
+
+Next, let's look at how to :doc:`Add configuration files <AddingConfiguration>` to use with our script.
+
+

src/sphinx/GettingStartedServers/OverrdingTemplates.rst

@@ -0,0 +1,5 @@
+Overriding templates
+####################
+
+This works the same way as for the standard application type. Read more on :doc:`../GettingStartedApplications/OverridingTemplates` 
+

src/sphinx/GettingStartedServers/index.rst

@@ -25,3 +25,26 @@ Currently the native package supports the following installation targets for ser
 | Windows       | Windows Services   |           |
 +---------------+--------------------+-----------+
 
+What is a Server Archetype
+==========================
+
+A server project extends the basic ``java_application`` with some server specific features,
+which are currently on
+
+Linux
+~~~~~
+
+* ``/var/log/<pkg>`` is symlinked from ``<install-location>/log``
+
+* ``/var/run/<pkg>`` is created with write privileges for the ``daemonUser``
+  
+* ``/etc/<pkg>`` is symlinked from ``<install-location>/conf``
+
+* Creates a start script in ``/etc/init.d`` (SystemV) or ``/etc/init/`` (Upstart)
+
+* Creates a startup config file in ``/etc/default/<pkg>``
+
+
+Next, let's :doc:`get started with simple application <MyFirstProject>`
+
+

src/sphinx/conf.py

@@ -12,6 +12,7 @@
 # serve to show the default.
 
 import sys, os
+import sphinx_bootstrap_theme
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -91,15 +92,20 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'sphinxdoc'
+html_theme = 'bootstrap'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #html_theme_options = {}
+html_theme_options = {
+    'bootstrap_version': "3",
+    'bootswatch_theme': "yeti",
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
+html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".