From 60c90188bbd434f8f7ec3388e9758b2559a5fba6 Mon Sep 17 00:00:00 2001 From: Nepomuk Seiler Date: Wed, 2 Apr 2014 19:39:14 +0200 Subject: [PATCH 1/3] Server archetype additions --- .../AddingConfiguration.rst | 78 ++++++++++++++++ .../GettingStartedServers/MyFirstProject.rst | 90 +++++++++++++++++++ .../OverrdingTemplates.rst | 5 ++ src/sphinx/GettingStartedServers/index.rst | 23 +++++ 4 files changed, 196 insertions(+) create mode 100644 src/sphinx/GettingStartedServers/AddingConfiguration.rst create mode 100644 src/sphinx/GettingStartedServers/MyFirstProject.rst create mode 100644 src/sphinx/GettingStartedServers/OverrdingTemplates.rst diff --git a/src/sphinx/GettingStartedServers/AddingConfiguration.rst b/src/sphinx/GettingStartedServers/AddingConfiguration.rst new file mode 100644 index 000000000..9b48ec704 --- /dev/null +++ b/src/sphinx/GettingStartedServers/AddingConfiguration.rst @@ -0,0 +1,78 @@ +Adding configuration +#################### + +After :doc:`creating a package `, 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 + + # 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/`` 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 `. diff --git a/src/sphinx/GettingStartedServers/MyFirstProject.rst b/src/sphinx/GettingStartedServers/MyFirstProject.rst new file mode 100644 index 000000000..fec7706fc --- /dev/null +++ b/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 dependend +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 " + + 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 ` to use with our script. + + diff --git a/src/sphinx/GettingStartedServers/OverrdingTemplates.rst b/src/sphinx/GettingStartedServers/OverrdingTemplates.rst new file mode 100644 index 000000000..8f9683cc0 --- /dev/null +++ b/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` + diff --git a/src/sphinx/GettingStartedServers/index.rst b/src/sphinx/GettingStartedServers/index.rst index ee058eed9..e7c550b51 100644 --- a/src/sphinx/GettingStartedServers/index.rst +++ b/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/`` is symlinked from ``/log`` + +* ``/var/run/`` is created with write privileges for the ``daemonUser`` + +* ``/etc/`` is symlinked from ``/conf`` + +* Creates a start script in ``/etc/init.d`` (SystemV) or ``/etc/init/`` (Upstart) + +* Creates a startup config file in ``/etc/default/`` + + +Next, let's :doc:`get started with simple application ` + + From 8492a6b72ecdda7851a2482178d6146724770f2d Mon Sep 17 00:00:00 2001 From: Nepomuk Seiler Date: Wed, 2 Apr 2014 19:49:07 +0200 Subject: [PATCH 2/3] Styling the docs a bit. ```bash sudo apt-get install python-pip sudo pip install sphinx_bootstrap_theme ``` --- src/sphinx/conf.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/src/sphinx/conf.py b/src/sphinx/conf.py index b3d5d65b7..b3374a8a4 100644 --- a/src/sphinx/conf.py +++ b/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 # " v documentation". From 986ee3b93ea210f666d2c31b126d3b4b44d397c4 Mon Sep 17 00:00:00 2001 From: Nepomuk Seiler Date: Wed, 2 Apr 2014 20:06:00 +0200 Subject: [PATCH 3/3] Fix type --- src/sphinx/GettingStartedServers/MyFirstProject.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/sphinx/GettingStartedServers/MyFirstProject.rst b/src/sphinx/GettingStartedServers/MyFirstProject.rst index fec7706fc..3b86b7684 100644 --- a/src/sphinx/GettingStartedServers/MyFirstProject.rst +++ b/src/sphinx/GettingStartedServers/MyFirstProject.rst @@ -16,7 +16,7 @@ with packageArchetype.java_server -which will activate all server specific settings. As the server settings are dependend +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.