diff --git a/src/sphinx/DetailedTopics/index.rst b/src/sphinx/DetailedTopics/index.rst deleted file mode 100644 index 5dffb878e..000000000 --- a/src/sphinx/DetailedTopics/index.rst +++ /dev/null @@ -1,18 +0,0 @@ -Advanced Topics -############### - - - -.. toctree:: - :maxdepth: 2 - - archetypes.rst - universal.rst - linux.rst - redhat.rst - debian.rst - windows.rst - docker.rst - paths.rst - custom.rst - play.rst diff --git a/src/sphinx/GettingStartedApplications/OverridingTemplates.rst b/src/sphinx/GettingStartedApplications/OverridingTemplates.rst deleted file mode 100644 index c83235582..000000000 --- a/src/sphinx/GettingStartedApplications/OverridingTemplates.rst +++ /dev/null @@ -1,80 +0,0 @@ -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 customized or directly -overridden. - -The easiest way to add functionality to the default script is by adding ``bashScriptExtraDefines`` :doc:`as described -in adding configuration for applications `. 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 `. - -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 - - #!/usr/bin/env bash - - realpath() { - # TODO - The original bash template has a robust mechanism to find the true - # path to your application, following multiple symlinks. - # - } - - addJava() { - # Here we override the original templates addJava method to do nothing, - # since this was how we were adding configuration before. - } - - declare -r real_script_path="$(realpath "$0")" - - # We have to provide an app_home for the default bash declarations to work. - declare -r app_home="$(realpath "$(dirname "$real_script_path")")" - - # The auto-generated classpath relies on this variable existing - # and pointing at the lib directory. - declare -r lib_dir="$(realpath "${app_home}/../lib")" - - # This line tells the native packager template engine to inject - # all of its settings into this spot in the bash file. - ${{template_declares}} - - # Here we make use of two of the injected settings for the bash file: - # * app_classpath - represents the full list of JARs for this applciation. - # * app_mainclass - represents the class with a main method we should call. - exec java -cp $app_classpath $app_mainclass $@ - - -Similarly the windows BAT template can be overridden by placing a new template in ``src/templates/bat-template`` - -.. code-block:: bat - - @REM A bat starter script - @echo off - - @REM Here we need to set up a "home" variable for our classpath. - @REM The APP_ENV_NAME variable is replaced by the packager template engine - @REM with an "environment variable friendly" name for the app. - if "%@@APP_ENV_NAME@@_HOME%"=="" set "@@APP_ENV_NAME@@_HOME=%~dp0\\.." - set "APP_LIB_DIR=%@@APP_ENV_NAME@@_HOME%\lib\" - - @REM - This tells the template engine to inject any custom defines into our bat file here. - @@APP_DEFINES@@ - - @REM - Here we use the provided APP_CLASSPATH and APP_MAIN_CLASS parameters - java -cp "%APP_CLASSPATH%" %APP_MAIN_CLASS% %* - - -While we just replaced the default templates with simpler templates, this should really only be done if: - -1. There is a bug in one of the script templates you need to workaround -2. There is a deficiency in the features of one of the templates you need to fix. - -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 `. diff --git a/src/sphinx/GettingStartedApplications/index.rst b/src/sphinx/GettingStartedApplications/index.rst deleted file mode 100644 index 1d439633e..000000000 --- a/src/sphinx/GettingStartedApplications/index.rst +++ /dev/null @@ -1,28 +0,0 @@ -Getting Started with Applications -################################# - -The sbt-native-packager is an sbt plugin for bundling your application for a variety of platforms. - -**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 -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. - -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 ` 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 - - MyFirstProject.rst - AddingConfiguration.rst - GeneratingFiles.rst - OverridingTemplates.rst - WritingDocumentation.rst diff --git a/src/sphinx/GettingStartedServers/AddingConfiguration.rst b/src/sphinx/GettingStartedServers/AddingConfiguration.rst deleted file mode 100644 index 7c058f9f7..000000000 --- a/src/sphinx/GettingStartedServers/AddingConfiguration.rst +++ /dev/null @@ -1,81 +0,0 @@ -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 outside of customizing the ``bash`` or ``bat`` script for applications. -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 - -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 ` explains this feature. diff --git a/src/sphinx/GettingStartedServers/OverridingTemplates.rst b/src/sphinx/GettingStartedServers/OverridingTemplates.rst deleted file mode 100644 index 0071ff98b..000000000 --- a/src/sphinx/GettingStartedServers/OverridingTemplates.rst +++ /dev/null @@ -1,139 +0,0 @@ -Overriding templates -#################### - -Some scripts are covered in the standard application type. Read more on :doc:`../GettingStartedApplications/OverridingTemplates`. -For the ``java_server`` package lifecycle scripts are customized to provide the following additional features - -* Chowning directories and files correctly -* Create/Delete users and groups according to your mapping -* Register application at your init system - -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 -`_. -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 -============== - -RPM puts all scripts into one file. To override or append settings to your -scriptlets use these settings: - - ``rpmPre`` - %pre scriptlet - - ``rpmPost`` - %post scriptlet - - ``rpmPosttrans`` - %posttrans scriptlet - - ``rpmPreun`` - "%preun scriptlet" - - ``rpmPostun`` - %postun scriptlet - - ``rpmVerifyscript`` - %verifyscript scriptlet - -If you want to have your files separated from the build definition use the -default location for rpm scriptlets. To override default templates in a RPM -build put the new scriptlets in the ``rpmScriptsDirectory`` (by default ``src/rpm/scriptlets``). - - ``rpmScriptsDirectory`` - By default to ``src/rpm/scriptlets``. Place your templates here. - -Available templates are - - ``post-rpm`` - ``pre-rpm`` - ``postun-rpm`` - ``preun-rpm`` - -Override Postinst scriplet -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -By default the ``post-rpm`` template only starts the service, but doesn't register it. - -.. code-block :: bash - - service ${{app_name}} start - -For **CentOS** we can do - -.. code-block :: bash - - chkconfig ${{app_name}} defaults - service ${{app_name}} start || echo "${{app_name}} could not be started. Try manually with service ${{app_name}} start" - -For **RHEL** - -.. code-block :: bash - - update-rc.d ${{app_name}} defaults - service ${{app_name}} start || echo "${{app_name}} could not be started. Try manually with service ${{app_name}} start" - - - -Debian Control Scripts -====================== - -To override default templates in a Debian build put the new control files in the -``debianControlScriptsDirectory`` (by default ``src/debian/DEBIAN``). - - ``debianControlScriptsDirectory`` - By default to ``src/debian/DEBIAN``. Place your templates here. - - ``debianMakePreinstScript`` - creates or discovers the preinst script used by this project. - - ``debianMakePrermScript`` - creates or discovers the prerm script used by this project. - - ``debianMakePostinstScript`` - creates or discovers the postinst script used by this project. - - ``debianMakePostrmScript`` - creates or discovers the postrm script used by this project. - - -Available templates are - - ``postinst`` - ``preinst`` - ``postun`` - ``preun`` - - -Linux Replacements -================== - - This is a list of values you can access in your templates - - .. code-block :: bash - - ${{author}} - ${{descr}} - ${{exec}} - ${{chdir}} - ${{retries}} - ${{retryTimeout}} - ${{app_name}} - ${{daemon_user}} - ${{daemon_group}} - diff --git a/src/sphinx/GettingStartedServers/index.rst b/src/sphinx/GettingStartedServers/index.rst deleted file mode 100644 index 989db9efe..000000000 --- a/src/sphinx/GettingStartedServers/index.rst +++ /dev/null @@ -1,117 +0,0 @@ -Getting Started with Servers -############################ - -The sbt-native-packager is an sbt plugin for bundling your server for a variety of platforms. - -**Note:** Please follow the :ref:`Installation` instructions for how to set it up on a project. - -In the :doc:`Application Packaging ` 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. - -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 ` 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 ` and :doc:`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 -========================== - -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 ` - - diff --git a/src/sphinx/archetypes/akka_app/index.rst b/src/sphinx/archetypes/akka_app/index.rst new file mode 100644 index 000000000..3a1d1b4e9 --- /dev/null +++ b/src/sphinx/archetypes/akka_app/index.rst @@ -0,0 +1,2 @@ +Akka Microkernel +################ diff --git a/src/sphinx/DetailedTopics/paths.rst b/src/sphinx/archetypes/cheatsheet.rst similarity index 52% rename from src/sphinx/DetailedTopics/paths.rst rename to src/sphinx/archetypes/cheatsheet.rst index 85fb281ce..67a46fdbd 100644 --- a/src/sphinx/DetailedTopics/paths.rst +++ b/src/sphinx/archetypes/cheatsheet.rst @@ -1,3 +1,10 @@ +.. _Cheatsheet: + +Archetype Cheatsheet +#################### + +This is a set FAQ composed on a single page. + Path Configurations =================== This section describes where and how to configure different kind of paths settings. @@ -37,8 +44,6 @@ logs Linux J ======================================================== =================== ===================== ======= - - Settings -------- @@ -60,3 +65,75 @@ These settings configure the path behaviour Defaults to ``/var/log/``. Used to determine the log path for linux packages (rpm, debian). + +Overriding Templates +==================== + +You can override the default template used to generate any of the scripts in +any archetype. Listed below are the overridable files and variables that +you can use when generating scripts. + +Bat Script - ``src/templates/bat-template`` +------------------------------------------- + +Creating a file here will override the default template used to +generate the ``.bat`` script for windows distributions. + +**Syntax** + +``@@APP_ENV_NAME@@`` - will be replaced with the script friendly name of your package. + +``@@APP_NAME@@`` - will be replaced with user friendly name of your package. + +``@APP_DEFINES@@`` - will be replaced with a set of variable definitions, like + ``APP_MAIN_CLASS``, ``APP_MAIN_CLASS``. + +You can define addiitonal variable definitions using ``batScriptExtraDefines``. + +Bash Script - ``src/templates/bash-template`` +--------------------------------------------- + +Creating a file here will override the default template used to +generate the BASH start script found in ``bin/`` in the +universal distribution + +**Syntax** + +``${{template_declares}}`` - Will be replaced with a series of ``declare `` +lines based on the ``bashScriptDefines`` key. You can add more defines to +the ``bashScriptExtraDefines`` that will be used in addition to the default set: + +* ``app_mainclass`` - The main class entry point for the application. +* ``app_classpath`` - The complete classpath for the application (in order). + + + +Service Manager - ``src/templates/start`` +----------------------------------------- + +Creating a file here will override either the init.d startup script or +the upstart start script. It will either be located at +``/etc/init/`` or ``/etc/init.d/`` depending on which +serverLoader is being used. + +**Syntax** + +You can use ``${{variable_name}}`` to reference variables when writing your scirpt. The default set of variables is: + +* ``descr`` - The description of the server. +* ``author`` - The configured author name. +* ``exec`` - The script/binary to execute when starting the server +* ``chdir`` - The working directory for the server. +* ``retries`` - The number of times to retry starting the server. +* ``retryTimeout`` - The amount of time to wait before trying to run the server. +* ``app_name`` - The name of the application (linux friendly) +* ``app_main_class`` - The main class / entry point of the application. +* ``app_classpath`` - The (ordered) classpath of the application. +* ``daemon_user`` - The user that the server should run as. + +Server App Config - ``src/templates/etc-default`` +------------------------------------------------- + +Creating a file here will override the ``/etc/default/`` template +used when SystemV is the server loader. + diff --git a/src/sphinx/DetailedTopics/archetypes.rst b/src/sphinx/archetypes/index.rst similarity index 55% rename from src/sphinx/DetailedTopics/archetypes.rst rename to src/sphinx/archetypes/index.rst index 7d568eeeb..4b5c7293c 100644 --- a/src/sphinx/DetailedTopics/archetypes.rst +++ b/src/sphinx/archetypes/index.rst @@ -1,5 +1,13 @@ .. _Archetypes: +.. toctree:: + :maxdepth: 2 + + java_app/index.rst + java_server/index.rst + akka_app/index.rst + cheatsheet.rst + Project Archetypes ================== @@ -79,49 +87,17 @@ This archetype is designed for Java applications that are intended to run as servers or services. This archetype includes wiring an application to start immediately upon startup. To activate this archetype replace ``packageArchetype.java_application`` with -.. code-block:: scala - - packageArchetype.java_server - -Currently supported operating systems: - -* Ubuntu 12.04 LTS - Upstart -* Ubuntu 12.04 LTS - init.d - The Java Server archetype has a similar installation layout as the java -application archetype. The primary differneces are: +application archetype. The primary differences are: * Linux * ``/var/log/`` is symlinked from ``/logs`` - * Creates a start script in ``/etc/init.d`` or ``/etc/init/`` - * Creates a startup config file in ``/etc/default/`` -For Debian servers, you can select to either use SystemV or Upstart for your servers. By default, Upstart (the current Ubuntu LTS default), is used. To switch to SystemV, add the following: - -.. code-block:: scala - - import NativePackagerKeys._ - import com.typesafe.sbt.packager.archetypes.ServerLoader - - serverLoading in Debian := ServerLoader.SystemV - -By default, the native packager will install and run services using a user and group based on your package name. You can change the installation and usage user via the ``appUser`` and ``appGroup`` key: - -.. code-block:: scala - - appUser in Linux := "my_app_user" - - appGroup in Linux := "my_app_group" - -The archetype will automatically append/prepend the creation/deletion of the user -to your packaging for Debian. *Note:* All specified users are **deleted** on an ``apt-get purge ``. - -*Note:* It is not a good idea to use **root** as the ``appUser`` for services as it represents a security risk. Akka Microkernel Application ---------------------------- @@ -164,75 +140,3 @@ For more information take a look at the akka docs * `akka.kernel.Main source `_ * `akka.kernel.Bootable docs `_ - -Overriding Templates --------------------- - -You can override the default template used to generate any of the scripts in -any archetype. Listed below are the overridable files and variables that -you can use when generating scripts. - -``src/templates/bat-template`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Creating a file here will override the default template used to -generate the ``.bat`` script for windows distributions. - -**Syntax** - -``@@APP_ENV_NAME@@`` - will be replaced with the script friendly name of your package. - -``@@APP_NAME@@`` - will be replaced with user friendly name of your package. - -``@APP_DEFINES@@`` - will be replaced with a set of variable definitions, like - ``APP_MAIN_CLASS``, ``APP_MAIN_CLASS``. - -You can define addiitonal variable definitions using ``batScriptExtraDefines``. - -``src/templates/bash-template`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Creating a file here will override the default template used to -generate the BASH start script found in ``bin/`` in the -universal distribution - -**Syntax** - -``${{template_declares}}`` - Will be replaced with a series of ``declare `` -lines based on the ``bashScriptDefines`` key. You can add more defines to -the ``bashScriptExtraDefines`` that will be used in addition to the default set: - -* ``app_mainclass`` - The main class entry point for the application. -* ``app_classpath`` - The complete classpath for the application (in order). - - - -``src/templates/start`` -~~~~~~~~~~~~~~~~~~~~~~~ - -Creating a file here will override either the init.d startup script or -the upstart start script. It will either be located at -``/etc/init/`` or ``/etc/init.d/`` depending on which -serverLoader is being used. - -**Syntax** - -You can use ``${{variable_name}}`` to reference variables when writing your scirpt. The default set of variables is: - -* ``descr`` - The description of the server. -* ``author`` - The configured author name. -* ``exec`` - The script/binary to execute when starting the server -* ``chdir`` - The working directory for the server. -* ``retries`` - The number of times to retry starting the server. -* ``retryTimeout`` - The amount of time to wait before trying to run the server. -* ``app_name`` - The name of the application (linux friendly) -* ``app_main_class`` - The main class / entry point of the application. -* ``app_classpath`` - The (ordered) classpath of the application. -* ``daemon_user`` - The user that the server should run as. - -``src/templates/etc-default`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Creating a file here will override the ``/etc/default/`` template -used when SystemV is the server loader. - diff --git a/src/sphinx/GettingStartedApplications/AddingConfiguration.rst b/src/sphinx/archetypes/java_app/customize.rst similarity index 52% rename from src/sphinx/GettingStartedApplications/AddingConfiguration.rst rename to src/sphinx/archetypes/java_app/customize.rst index 0fa2ca1f3..10297342f 100644 --- a/src/sphinx/GettingStartedApplications/AddingConfiguration.rst +++ b/src/sphinx/archetypes/java_app/customize.rst @@ -1,14 +1,38 @@ -Adding configuration -#################### +Customize Java Applications +########################### -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. +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 customized or directly +overridden. + +The easiest way to add functionality to the default script is by adding ``bashScriptExtraDefines`` :doc:` as described +in adding configuration for applications `. 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 `. + +Customizing Templates (Bash/Bat) +-------------------------------- + +.. raw:: html + + + +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 native packager provides a direct hook into the generated scripts for JVM configuration. Let's make use of this. First, add the following to the ``src/universal/conf/jvmopts`` file in the project :: +The native packager provides a direct hook into the generated scripts for JVM configuration. Let's make use of this. +First, add the following to the ``src/universal/conf/jvmopts`` file in the project :: -DsomeProperty=true @@ -64,7 +88,9 @@ in the startup BASH script. To do so, add the following to ``build.sbt`` :: bashScriptExtraDefines += """addJava "-Dconfig.file=${app_home}/../conf/app.config"""" -This line modifies the generated BASH script to add the JVM options the location of the application configuration on disk. Now, let's modify the application (``src/main/scala/TestApp.scala``) to read this configuration :: +This line modifies the generated BASH script to add the JVM options the location of the application configuration on disk. Now, let's modify the application (``src/main/scala/TestApp.scala``) to read this configuration + +.. code-block:: scala import com.typesafe.config.ConfigFactory @@ -101,7 +127,9 @@ The resulting structure is the following :: /etc/ example-cli -> /usr/share/example-cli/conf -Here, we can see that the entire ``conf`` directory for the application is exposed on ``/etc`` as is standard for other linux applications. By convention, all files in the universal ``conf`` directory are marked as configuration files when packaged, allowing users to modify them. +Here, we can see that the entire ``conf`` directory for the application is exposed on ``/etc`` as is standard for +other linux applications. By convention, all files in the universal ``conf`` directory are marked as configuration +files when packaged, allowing users to modify them. Configuring for Windows ~~~~~~~~~~~~~~~~~~~~~~~ @@ -131,7 +159,7 @@ 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 @@ -144,4 +172,106 @@ scripts you can also inject a seperate file managed in your source tree or resou 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 `. + + +Overriding Templates (Bash/Bat) +------------------------------- + +In order to override full templates, like the default bash script, create a file in ``src/templates/bash-template`` + +.. code-block:: bash + + #!/usr/bin/env bash + + realpath() { + # TODO - The original bash template has a robust mechanism to find the true + # path to your application, following multiple symlinks. + # + } + + addJava() { + # Here we override the original templates addJava method to do nothing, + # since this was how we were adding configuration before. + } + + declare -r real_script_path="$(realpath "$0")" + + # We have to provide an app_home for the default bash declarations to work. + declare -r app_home="$(realpath "$(dirname "$real_script_path")")" + + # The auto-generated classpath relies on this variable existing + # and pointing at the lib directory. + declare -r lib_dir="$(realpath "${app_home}/../lib")" + + # This line tells the native packager template engine to inject + # all of its settings into this spot in the bash file. + ${{template_declares}} + + # Here we make use of two of the injected settings for the bash file: + # * app_classpath - represents the full list of JARs for this applciation. + # * app_mainclass - represents the class with a main method we should call. + exec java -cp $app_classpath $app_mainclass $@ + + +Similarly the windows BAT template can be overridden by placing a new template in ``src/templates/bat-template`` + +.. code-block:: bat + + @REM A bat starter script + @echo off + + @REM Here we need to set up a "home" variable for our classpath. + @REM The APP_ENV_NAME variable is replaced by the packager template engine + @REM with an "environment variable friendly" name for the app. + if "%@@APP_ENV_NAME@@_HOME%"=="" set "@@APP_ENV_NAME@@_HOME=%~dp0\\.." + set "APP_LIB_DIR=%@@APP_ENV_NAME@@_HOME%\lib\" + + @REM - This tells the template engine to inject any custom defines into our bat file here. + @@APP_DEFINES@@ + + @REM - Here we use the provided APP_CLASSPATH and APP_MAIN_CLASS parameters + java -cp "%APP_CLASSPATH%" %APP_MAIN_CLASS% %* + + +While we just replaced the default templates with simpler templates, this should really only be done if: + +1. There is a bug in one of the script templates you need to workaround +2. There is a deficiency in the features of one of the templates you need to fix. + +In general, the templates are intended to provide enough utility that customization is only necessary for truly custom scripts. + + +``src/templates/bat-template`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Creating a file here will override the default template used to +generate the ``.bat`` script for windows distributions. + +**Syntax** + +``@@APP_ENV_NAME@@`` - will be replaced with the script friendly name of your package. + +``@@APP_NAME@@`` - will be replaced with user friendly name of your package. + +``@APP_DEFINES@@`` - will be replaced with a set of variable definitions, like + ``APP_MAIN_CLASS``, ``APP_MAIN_CLASS``. + +You can define addiitonal variable definitions using ``batScriptExtraDefines``. + +``src/templates/bash-template`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Creating a file here will override the default template used to +generate the BASH start script found in ``bin/`` in the +universal distribution + +**Syntax** + +``${{template_declares}}`` - Will be replaced with a series of ``declare `` +lines based on the ``bashScriptDefines`` key. You can add more defines to +the ``bashScriptExtraDefines`` that will be used in addition to the default set: + +* ``app_mainclass`` - The main class entry point for the application. +* ``app_classpath`` - The complete classpath for the application (in order). + +Next, let's look at how to :doc:`document the application `. diff --git a/src/sphinx/GettingStartedApplications/GeneratingFiles.rst b/src/sphinx/archetypes/java_app/generating-files.rst similarity index 83% rename from src/sphinx/GettingStartedApplications/GeneratingFiles.rst rename to src/sphinx/archetypes/java_app/generating-files.rst index 58d625cff..75ce28d2c 100644 --- a/src/sphinx/GettingStartedApplications/GeneratingFiles.rst +++ b/src/sphinx/archetypes/java_app/generating-files.rst @@ -5,7 +5,9 @@ Let's dynamically (in the build) construct some files that should be included in For the example, let's download a license file for our application and add it to the distribution. First, -let's create a task which will download a license file. Add the following to build.sbt :: +let's create a task which will download a license file. Add the following to build.sbt + +.. code-block: scala val downloadLicense = taskKey[File]("Downloads the latest license file.") @@ -25,9 +27,11 @@ In sbt, a **mappings** object is a grouping of files and relative locations, e.g /home/jsuereth/projects/example/src/universal/conf/app.config -> conf/app.config /home/jsuereth/projects/example/src/universal/conf/jvmopts -> conf/jvmopts -shows the mapping of the configuration files we set up :doc:`previously `. We can directly +shows the mapping of the configuration files we set up :doc:`previously `. We can directly append files to the mappings rather than relying on the native packager to find things. Let's add -the license in the root of the package we're creating. Add the following to the ``build.sbt`` :: +the license in the root of the package we're creating. Add the following to the ``build.sbt`` + +.. code-block: scala mappings in Universal += downloadLicense.value -> "LICENSE" @@ -42,10 +46,5 @@ can verify this by checking the ``stage`` task :: You can see the license file is now included in the distribution. -TODO - Describe linuxPackageMappings - With control over mappings, you can rework any aspect of the native packager defaults just by overriding -which files are used. However, sometimes the defaults don't need to be completely replaced, just altered a bit. - -Next, let's look at :doc:`how to provide our own BASH template ` that the native packager will use when generating -the script. +which files are used. However, sometimes the defaults don't need to be completely replaced, just altered a bit. diff --git a/src/sphinx/GettingStartedApplications/gettingstarted.rst b/src/sphinx/archetypes/java_app/gettingstarted.rst similarity index 77% rename from src/sphinx/GettingStartedApplications/gettingstarted.rst rename to src/sphinx/archetypes/java_app/gettingstarted.rst index 404fc957f..cc9a1279c 100644 --- a/src/sphinx/GettingStartedApplications/gettingstarted.rst +++ b/src/sphinx/archetypes/java_app/gettingstarted.rst @@ -1,7 +1,7 @@ Getting Started =============== -The sbt-native-packager is an sbt plugin. Please follow the :ref:`Installation` instructions for how to set it up on a project. +The sbt-native-packager is an sbt plugin. Please follow the :doc:`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 some basic abstractions around packaging, it also allows you to dig down into the nuts and bolts of each platform as @@ -26,7 +26,7 @@ Defining a new package ~~~~~~~~~~~~~~~~~~~~~~ To define a new package, after installing the plugin and ensuring the basic settings are on the project, start configuring your package contents -either using :ref:`Archetypes` or :ref:`Universal` hooks. These will describe the appropriate way to begin packaging for your applciation. +either using :doc:`Archetypes ` or :ref:`Universal` hooks. These will describe the appropriate way to begin packaging for your application. diff --git a/src/sphinx/archetypes/java_app/index.rst b/src/sphinx/archetypes/java_app/index.rst new file mode 100644 index 000000000..127857f38 --- /dev/null +++ b/src/sphinx/archetypes/java_app/index.rst @@ -0,0 +1,73 @@ +Java Application Archetype +########################## + +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. The `JavaAppPackaging` archetype +provides a default application structure and executable scripts to launch your application. + +Additionally there is :doc:`Server Packaging ` 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). + +Features +-------- + +The `JavaAppPackaging` archetype contains the following features. + +* Default application mappings (no fat jar) +* Executable bash/bat script + + +Usage +----- + +.. raw:: html + +
+
+ +Version 1.0 or higher with sbt 0.13.5 and and higher + +.. code-block:: scala + + enablePlugins(JavaAppPackaging) + +.. raw:: html + +
+
+ +Version 0.8 or lower + +.. code-block:: scala + + import com.typesafe.sbt.SbtNativePackager._ + import NativePackagerKeys._ + + packageArchetype.java_app + +.. raw:: html + +
+
+ + +Customize +--------- + +You can customize the bash/bat scripts in different ways. This is explained in +the :doc:`Customize ` section. The application structure is customizable +via the standard mappings, which is described in the :doc:`Universal Plugin Section `. + + +Sitemap +------- + +.. toctree:: + :maxdepth: 1 + + gettingstarted + my-first-project.rst + customize.rst + generating-files.rst + writing-documentation.rst diff --git a/src/sphinx/GettingStartedApplications/MyFirstProject.rst b/src/sphinx/archetypes/java_app/my-first-project.rst similarity index 89% rename from src/sphinx/GettingStartedApplications/MyFirstProject.rst rename to src/sphinx/archetypes/java_app/my-first-project.rst index acfa6dc8c..0833d9de6 100644 --- a/src/sphinx/GettingStartedApplications/MyFirstProject.rst +++ b/src/sphinx/archetypes/java_app/my-first-project.rst @@ -4,38 +4,66 @@ My First Packaged Project After installing the native packager, let's set up a raw sbt project to experiment with bundling things. First, let's create a ``project/build.properties`` file to save the sbt version :: - sbt.version=0.13.1 + sbt.version=0.13.7 sbt builds should always specify which version of sbt they are designed to use. This helps keeps builds consistent between developers, and documents to users which version of sbt you require for the build. Next, let's add the native packager to our build by created a ``project/plugins.sbt`` file with the following contents :: - addSbtPlugin("com.typesafe.sbt" % "sbt-native-packager" % "0.8.0-M2") + addSbtPlugin("com.typesafe.sbt" % "sbt-native-packager" % "x.y.z") Now, the build needs to be configured for packaging. Let's define the ``build.sbt`` file as follows + +.. raw:: html + +
+
+ +Version 1.0 or higher with sbt 0.13.5 and and higher + +.. code-block:: scala + + name := "example-cli" + version := "1.0" + + enablePlugins(JavaAppPackaging) + +.. raw:: html + +
+
+ +Version 0.8 or lower + .. code-block:: scala import com.typesafe.sbt.SbtNativePackager._ import NativePackagerKeys._ - + name := "example-cli" version := "1.0" packageArchetype.java_application +.. raw:: html + +
+
+ + The third line of ``build.sbt`` adds the default packaging settings for java applications. The native packager includes two "batteries included" options for packaging applications: * ``java_application`` - Defines packaging of your project with a start script and automatic PATH additions * ``java_server`` - Defines packaging of your project with automatic service start scripts (supports System V + init.d). -In addition to these, you can always directly configure all packaging by hand. For now, we're using one of the built-in options +In addition to these, you can always directly configure all packaging by hand. For now, we're using one of the built-in options as these are pretty robust and configurable. -Now that the build is set up, Let's create an application that we can run on the command line. Create the following file +Now that the build is set up, Let's create an application that we can run on the command line. Create the following file ``src/main/scala/TestApp.scala`` .. code-block:: scala @@ -88,13 +116,10 @@ installation and update mechanism. So, let's try to make a debian out of our p [error] packageDescription in Debian := "My package Description" [error] Total time: 0 s, completed Apr 1, 2014 10:21:13 AM -Here, the native packager is warning that we haven't fully configured all the information required to generate a valid debian file. In particular, the packageDescription needs to be filled out for debian, in addition to a few other settings. Let's add the debian configuration to ``build.sbt`` :: +Here, the native packager is warning that we haven't fully configured all the information required to generate a valid debian file. In particular, the packageDescription needs to be filled out for debian, in addition to a few other settings. Let's add the debian configuration to ``build.sbt`` - name := "example-cli" - version := "1.0" - - packageArchetype.java_application +.. code-block:: scala packageDescription in Debian := "Example Cli" @@ -135,6 +160,6 @@ While we only covered the necessary configuration for ``debian``, each package t configuration relative to that packager. For example, windows MSIs require UUIDs for all packages which are used to uniquely identifiy two packages that may have the same name. -Next, let's look at how to :doc:`Add configuration files ` to use with our script. +Next, let's look at how to :doc:`customize the executable bash/bat scripts`. diff --git a/src/sphinx/GettingStartedApplications/WritingDocumentation.rst b/src/sphinx/archetypes/java_app/writing-documentation.rst similarity index 84% rename from src/sphinx/GettingStartedApplications/WritingDocumentation.rst rename to src/sphinx/archetypes/java_app/writing-documentation.rst index 0aaec966b..319942399 100644 --- a/src/sphinx/GettingStartedApplications/WritingDocumentation.rst +++ b/src/sphinx/archetypes/java_app/writing-documentation.rst @@ -19,7 +19,9 @@ To create a linux man page for the application, let's create a ``src/linux/usr/s .SH SYNOPSIS .B example-cli [-h] -Notice the location of the file. Any file under ``src/linux`` is automatically included, relative to ``/``, in linux packages (deb, rpm). That means the man file will **not** appear in the universal package (confusing linux users). +Notice the location of the file. Any file under ``src/linux`` is automatically included, +relative to ``/``, in linux packages (deb, rpm). That means the man file will **not** appear +in the universal package (confusing linux users). Now that the man page is created, we can use a few tasks provided to view it in sbt. Let's look in the sbt console :: @@ -51,4 +53,6 @@ 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 :doc:`Java Servers `, which offers a few differences in how configuration is done 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 `, which offers a few differences in how configuration +is done for packaging to underlying systems. diff --git a/src/sphinx/archetypes/java_server/customize.rst b/src/sphinx/archetypes/java_server/customize.rst new file mode 100644 index 000000000..3c63ad32d --- /dev/null +++ b/src/sphinx/archetypes/java_server/customize.rst @@ -0,0 +1,307 @@ +Customize Java Server Applications +################################## + +Application 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 outside of customizing the ``bash`` or ``bat`` script for applications. +As this file is OS dependend, each OS gets section. + +Linux Configuration +------------------- + +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 Configuration +--------------------- + +Support planned. + + +Service Manager Configuration +============================= + +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 + + import com.typesafe.sbt.packager.archetypes.ServerLoader + + 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.* + +Customize Start Script +---------------------- + +Sbt Native Packager leverages templating to customize various start/stop scripts and pre/post install tasks. +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 + + import com.typesafe.sbt.packager.archetypes.TemplateWriter + + linuxScriptReplacements += { + val functions = sourceDirectory.value / "templates" / "custom-loader-functions" + // Nil == replacements. If you want to replace stuff in your script put them in this Seq[(String,String)] + "loader-functions" -> TemplateWriter.generateScript(functions.toURL, 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 ` and :doc:`redhat ` pages have further information on overriding +distribution scpecific actions. + +Override Start Script - ``src/templates/start`` +----------------------------------------------- + +It's also possible to override the entire script/configuration for your service manager. +Create a file ``src/templates/start`` and it will be used instead. + +**Syntax** + +You can use ``${{variable_name}}`` to reference variables when writing your scirpt. The default set of variables is: + +* ``descr`` - The description of the server. +* ``author`` - The configured author name. +* ``exec`` - The script/binary to execute when starting the server +* ``chdir`` - The working directory for the server. +* ``retries`` - The number of times to retry starting the server. +* ``retryTimeout`` - The amount of time to wait before trying to run the server. +* ``app_name`` - The name of the application (linux friendly) +* ``app_main_class`` - The main class / entry point of the application. +* ``app_classpath`` - The (ordered) classpath of the application. +* ``daemon_user`` - The user that the server should run as. + + +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. + +Package Lifecycle Configuration +=============================== + +Some scripts are covered in the standard application type. Read more on :doc:`Java Application Customization`. +For the ``java_server`` package lifecycle scripts are customized to provide the following additional features + +* Chowning directories and files correctly (if neccessary) +* Create/Delete users and groups according to your mapping +* Register application at your init system + +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 +`_. +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 +-------------- + +RPM puts all scripts into one file. To override or append settings to your +scriptlets use these settings: + + ``rpmPre`` + %pre scriptlet + + ``rpmPost`` + %post scriptlet + + ``rpmPosttrans`` + %posttrans scriptlet + + ``rpmPreun`` + "%preun scriptlet" + + ``rpmPostun`` + %postun scriptlet + + ``rpmVerifyscript`` + %verifyscript scriptlet + +If you want to have your files separated from the build definition use the +default location for rpm scriptlets. To override default templates in a RPM +build put the new scriptlets in the ``rpmScriptsDirectory`` (by default ``src/rpm/scriptlets``). + + ``rpmScriptsDirectory`` + By default to ``src/rpm/scriptlets``. Place your templates here. + +Available templates are + + ``post-rpm`` + ``pre-rpm`` + ``postun-rpm`` + ``preun-rpm`` + +Override Postinst scriplet +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default the ``post-rpm`` template only starts the service, but doesn't register it. + +.. code-block :: bash + + service ${{app_name}} start + +For **CentOS** we can do + +.. code-block :: bash + + chkconfig ${{app_name}} defaults + service ${{app_name}} start || echo "${{app_name}} could not be started. Try manually with service ${{app_name}} start" + +For **RHEL** + +.. code-block :: bash + + update-rc.d ${{app_name}} defaults + service ${{app_name}} start || echo "${{app_name}} could not be started. Try manually with service ${{app_name}} start" + + + +Debian Control Scripts +---------------------- + +To override default templates in a Debian build put the new control files in the +``debianControlScriptsDirectory`` (by default ``src/debian/DEBIAN``). + + ``debianControlScriptsDirectory`` + By default to ``src/debian/DEBIAN``. Place your templates here. + + ``debianMakePreinstScript`` + creates or discovers the preinst script used by this project. + + ``debianMakePrermScript`` + creates or discovers the prerm script used by this project. + + ``debianMakePostinstScript`` + creates or discovers the postinst script used by this project. + + ``debianMakePostrmScript`` + creates or discovers the postrm script used by this project. + + +Available templates are + + ``postinst`` + ``preinst`` + ``postun`` + ``preun`` + + +Linux Replacements +------------------ + + This is a list of values you can access in your templates + + .. code-block :: bash + + ${{author}} + ${{descr}} + ${{exec}} + ${{chdir}} + ${{retries}} + ${{retryTimeout}} + ${{app_name}} + ${{daemon_user}} + ${{daemon_group}} + + +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 + diff --git a/src/sphinx/archetypes/java_server/index.rst b/src/sphinx/archetypes/java_server/index.rst new file mode 100644 index 000000000..dfbb6df2a --- /dev/null +++ b/src/sphinx/archetypes/java_server/index.rst @@ -0,0 +1,98 @@ +Java Server Application Archetype +################################# + +In the :doc:`Application Packaging ` section we described how to build and +customize settings related to an application. The server archetype adds additional features you may +need when running your application as a service on a server. SBT Native Packager ships with a set of +predefined install and uninstall scripts for various platforms and service managers. + + +Features +-------- + +The `JavaServerAppPackaging` archetype contains all `JavaAppPackaing` feature and the following + +* install/uninstall services +* default mappings for server applications +* Creates a start script in ``/etc/init.d`` (SystemV) or ``/etc/init/`` (Upstart) + + +Usage +----- + +.. raw:: html + +
+
+ +Version 1.0 or higher with sbt 0.13.5 and and higher + +.. code-block:: scala + + enablePlugins(JavaServerAppPackaging) + +.. raw:: html + +
+
+ +Version 0.8 or lower + +.. code-block:: scala + + import com.typesafe.sbt.SbtNativePackager._ + import NativePackagerKeys._ + + packageArchetype.java_server + +.. raw:: html + +
+
+ + +Customize +--------- + +The server archetype provides :doc:`additional options to customize your application ` +behaviour at buildtime, installation, uninstallation and during runtime. The +basic application script customization is discussed in :doc:`Java Application Customization `. + +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 | | ++---------------+--------------------+--------------+ + +Sitemap +------- + +.. toctree:: + :maxdepth: 1 + + my-first-project.rst + customize.rst + + +Next, let's :doc:`get started with simple application ` + + diff --git a/src/sphinx/GettingStartedServers/MyFirstProject.rst b/src/sphinx/archetypes/java_server/my-first-project.rst similarity index 78% rename from src/sphinx/GettingStartedServers/MyFirstProject.rst rename to src/sphinx/archetypes/java_server/my-first-project.rst index 1b85fbba5..835244858 100644 --- a/src/sphinx/GettingStartedServers/MyFirstProject.rst +++ b/src/sphinx/archetypes/java_server/my-first-project.rst @@ -1,19 +1,39 @@ 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`` +Follow the instructions for the basic ``java_application`` setup in :doc:`../java_app/index` to get a working build and +understand the core concepts of sbt-native-packager. Based on this configuration we exchange enable in our ``build.sbt`` + + +.. raw:: html + +
+
+ +Version 1.0 or higher with sbt 0.13.5 and and higher .. code-block:: scala - packageArchetype.java_application + enablePlugins(JavaServerAppPackaging) // instead of JavaAppPackaging + +.. raw:: html + +
+
-with +Version 0.8 or lower .. code-block:: scala - packageArchetype.java_server + import com.typesafe.sbt.SbtNativePackager._ + import NativePackagerKeys._ + + packageArchetype.java_server // instead of java_application + +.. raw:: html + +
+
which will activate all server specific settings. As the server settings are dependent @@ -42,6 +62,18 @@ There are additional parameters available to configure. daemonUser in Linux := normalizedName.value // user which will execute the application daemonGroup in Linux := (daemonUser in Linux).value // group which will execute the application + + +The archetype will automatically append/prepend the creation/deletion of the user +to your packaging for Debian. *Note:* All specified users are **deleted** on an ``apt-get purge ``. + +.. raw:: html + + + Default Mappings ================ @@ -68,7 +100,7 @@ this `native packager discussion`_. .. _native packager discussion: https://github.com/sbt/sbt-native-packager/pull/174 If you want to change something in this predefined structure read more about it in -the :doc:`linux section `. +the :doc:`linux section `. Debian (.deb) ============= @@ -149,6 +181,6 @@ To build an image, publish locally, and then push to a remote Docker repository, docker:publish -Next, let's look at how to :doc:`Add configuration files ` to use with our script. +Next, let's look at how to :doc:`customize a java server application `. diff --git a/src/sphinx/DetailedTopics/debian.rst b/src/sphinx/formats/debian.rst similarity index 56% rename from src/sphinx/DetailedTopics/debian.rst rename to src/sphinx/formats/debian.rst index be4339650..80b235625 100644 --- a/src/sphinx/DetailedTopics/debian.rst +++ b/src/sphinx/formats/debian.rst @@ -1,14 +1,29 @@ -Debian -====== +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 `_. By default the *native* implementation +is activated. +.. contents:: + :depth: 2 + + +.. raw:: html -Getting Started ---------------- -By default, the debian packaging settings will take all files under ``src/debian/DEBIAN`` and map them into the debian control directory. -Make sure you have to following tools installed on your machine in order to build debian packages natively: + + +Requirements +------------ + +If you use the *native* debian package implementation you need the following applications installed: * dpkg-deb * dpkg-sig @@ -16,7 +31,70 @@ Make sure you have to following tools installed on your machine in order to buil * lintian * fakeroot -If you are on windows you can try to use the jdeb packaging described below. +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 " + + 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 :doc:`Getting Started ` 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 + + +Configurations +-------------- + +Settings and Tasks inherited from parent plugins can be scoped with ``Debian``. + +.. code-block:: scala + + linuxPackageMappings in Debian := linuxPackageMappings.value + Settings -------- @@ -65,66 +143,14 @@ The Debian support grants the following commands: ``debian:gen-changes`` Generates the ``.changes``, and therefore the ``.deb`` package for this project. - -Examples --------- - -Plain Debian Packaging -~~~~~~~~~~~~~~~~~~~~~~ - -For a basic debian packaging your ``build.sbt`` must contain the following settings - -.. code-block:: scala - - import NativePackagerKeys._ - - name := "Debian Example" - - version := "1.0" - - packageArchetype.java_application - - maintainer := "Max Smith " - - packageSummary := "Hello World Debian Package" - - packageDescription := """A fun package description of our software, - with multiple lines.""" - -When you run ``sbt debian:packageBin`` you will find a debian package in your ``target`` folder. - -Multi OS Packaging with Debian -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you package for multiple operating systems you may have to be a bit more explicit in your ``build.sbt``. -For example - -.. code-block:: scala - - import NativePackagerKeys._ - - name := "Example Package" - - version := "1.0" - - packageArchetype.java_application - - maintainer in Debian := "Max Smith " - - maintainer in Windows := "Jane Smith " - - packageSummary in Debian := "Hello World Debian Package" - packageSummary in Windows := "Hello World Windows Package" +Customize +--------------- - packageDescription := """A fun package description of our software, - with multiple lines.""" - -As you see, we duplicated the ``maintainer`` and ``packageSummary`` setting, but defined it for -different configuration scopes. +This section contains example on how you can customize your debian build. -Customizing Debian Packaging -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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. @@ -149,40 +175,3 @@ Your control scripts are in a different castle.. directory? No problem. debianControlScriptsDirectory <<= (sourceDirectory) apply (_ / "deb" / "control") -Customizing Debian Server Archetype -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The debian packaging supports the ``packageArchetype.java_server``, which generates -autostart scripts and some default links for logging and configuration. - -The default configuration looks like this (that means you don't have to add anything!) - -.. code-block:: scala - - import com.typesafe.sbt.packager.archetypes.ServerLoader.{Upstart, SystemV} - - serverLoading := Upstart - -The default configuration will create a default system user and group for ownerships of the -installed files. This user will also be used to execute the daemon service so it does -not run as the **root** user. - -This default can be overridden using the ``appUser`` and ``appGroup`` keys, change -these values as you need. The user or group you define in the appropriate keys will be -created within in the ``postinst`` script and removed with ``apt-get purge`` through the -``postrm`` script. - -For more information look at the :ref:`Archetypes` page. - -Use JDeb for Debian Packaging -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If don't run a linux or mac system with ``dpkg`` installed, you can configure the -debian packaging be done by `jdeb`_ . To enable this just set another packaging -implementation in your ``build.sbt`` - -.. code-block:: scala - - packageBin in Debian <<= debianJDebPackaging in Debian - -.. _jdeb: https://github.com/tcurdt/jdeb diff --git a/src/sphinx/DetailedTopics/docker.rst b/src/sphinx/formats/docker.rst similarity index 63% rename from src/sphinx/DetailedTopics/docker.rst rename to src/sphinx/formats/docker.rst index 3177305e5..f2660c898 100644 --- a/src/sphinx/DetailedTopics/docker.rst +++ b/src/sphinx/formats/docker.rst @@ -1,5 +1,5 @@ -Docker -====== +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. @@ -7,27 +7,66 @@ Docker images describe how to set up a container for running an application, inc 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 -Settings --------- +Requirements +------------ + +You need the docker console client installed. SBT Native Packager doesn't use the REST API. + +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. + + +Build +----- + +.. code-block:: bash + + sbt docker:publishLocal + + +Required Settings +~~~~~~~~~~~~~~~~~ Docker images require the following setting: .. code-block:: scala - import NativePackagerKeys._ maintainer in Docker := "John Smith " -It may require these settings: + +1.0 or higher +~~~~~~~~~~~~~ + +.. code-block:: scala + + enablePlugins(DockerPlugin) + +0.8.x +~~~~~ + +For this versions docker packaging is automatically activated. +See the :doc:`Getting Started ` page for informations +on how to enable sbt native packager. + +Configuration +------------- + +Settings and Tasks inherited from parent plugins can be scoped with ``Docker``. .. code-block:: scala - packageName in Docker := packageName.value, - version in Docker := version.value, - dockerBaseImage := "dockerfile/java", - dockerRepository := Some("dockeruser"), - dockerExposedPorts in Docker := Seq(9000, 9443), - dockerExposedVolumes in Docker := Seq("/opt/docker/logs") + mappings in Docker := mappings.value + + +Settings +-------- + Informational Settings ~~~~~~~~~~~~~~~~~~~~~~ @@ -85,9 +124,46 @@ The Docker support provides the following commands: 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 path to which the application is written can be changed with the setting. +The files from ``mappings in Docker`` are extracted underneath this directory. - ``defaultLinuxInstallLocation in Docker`` - The files from ``mappings in Docker`` are extracted underneath this directory. +.. code-block:: scala + + defaultLinuxInstallLocation in Docker := "/opt/docker" diff --git a/src/sphinx/formats/index.rst b/src/sphinx/formats/index.rst new file mode 100644 index 000000000..bb8cfc7fb --- /dev/null +++ b/src/sphinx/formats/index.rst @@ -0,0 +1,14 @@ +Packaging Formats +################# + + + +.. toctree:: + :maxdepth: 2 + + universal.rst + linux.rst + debian.rst + rpm.rst + docker.rst + windows.rst diff --git a/src/sphinx/DetailedTopics/linux.rst b/src/sphinx/formats/linux.rst similarity index 82% rename from src/sphinx/DetailedTopics/linux.rst rename to src/sphinx/formats/linux.rst index 640d2927a..6552e722d 100644 --- a/src/sphinx/DetailedTopics/linux.rst +++ b/src/sphinx/formats/linux.rst @@ -1,9 +1,95 @@ .. _Linux: -Writing Linux Packages -====================== +Linux Plugin +============ -The native packager plugin is designed so that linux packages look similar, but can contain distribution specific information. +The native packager plugin is designed so that linux packages look similar, but can contain distribution specific information. + +.. contents:: + :depth: 2 + +.. raw:: html + + + +Related Plugins +--------------- + +.. toctree:: + :maxdepth: 1 + + debian.rst + rpm.rst + docker.rst + + +Build +----- + +The linux plugin is just a top level plugin for linux packaging formats. +The ``Linux`` scope contains settings which can be used by the plugins +depending on the linux plugin. + + +.. code-block:: bash + + sbt "show linux:linuxPackageMappings" + +Required Settings +~~~~~~~~~~~~~~~~~ + +A linux package needs some mandatory settings to be valid. Make sure +you have these settings in your build: + +.. code-block:: scala + + name := "Linux Example" + + version := "1.0" + + maintainer := "Max Smith " + + 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(LinuxPlugin) + + +0.8 or lower +~~~~~~~~~~~~ + +For this versions linux packaging is automatically activated. +See the :doc:`Getting Started ` page for informations +on how to enable sbt native packager. + +In order to use the utility functions you need to import them with +(if you haven't alreay imported this) + +.. code-block:: scala + + import com.typesafe.sbt.SbtNativePackager._ + +Configurations +-------------- + +Settings and tasks inherited from parent plugins can be scoped with ``Linux``. + +.. code-block:: scala + + name in Linux := name.value Settings -------- @@ -25,8 +111,11 @@ The required fields for any linux distribution are: A list of files and their desired installation locations for the package, as well as other metainformation. +Customize +--------- + Package Mappings ----------------- +~~~~~~~~~~~~~~~~ Most of the work in generating a linux package is constructing package mappings. These 'map' a file to a location on disk where it should reside as well as information about that file. Package mappings allow the specification of file ownership, permissions and whether or not @@ -248,7 +337,7 @@ on how to filter mappings. Alter LinuxPackageMapping ~~~~~~~~~~~~~~~~~~~~~~~~~ -First we alter the permissions for all ``LinuxPackageMapping``s that match a specific criteria. +First we alter the permissions for all ``LinuxPackageMapping`` s that match a specific criteria. .. code-block:: scala @@ -273,7 +362,7 @@ First we alter the permissions for all ``LinuxPackageMapping``s that match a spe Alter LinuxSymlinks ~~~~~~~~~~~~~~~~~~~ -First we alter the permissions for all ``LinuxPackageMapping``s that match a specific criteria. +First we alter the permissions for all ``LinuxPackageMapping`` s that match a specific criteria. .. code-block:: scala @@ -284,8 +373,3 @@ First we alter the permissions for all ``LinuxPackageMapping``s that match a spe links filter { /* remove stuff */ } map { /* change stuff */} } -.. toctree:: - :maxdepth: 2 - - debian.rst - redhat.rst diff --git a/src/sphinx/DetailedTopics/redhat.rst b/src/sphinx/formats/rpm.rst similarity index 61% rename from src/sphinx/DetailedTopics/redhat.rst rename to src/sphinx/formats/rpm.rst index abb9f7dd1..3fe168fd1 100644 --- a/src/sphinx/DetailedTopics/redhat.rst +++ b/src/sphinx/formats/rpm.rst @@ -1,22 +1,84 @@ -RedHat -====== +Rpm Plugin +========== -RedHat ``rpm`` files support a very advanced number of features. To take full advantage of this environment, it's best to understand how the ``rpm`` package system works. http://fedoraproject.org/wiki/How_to_create_an_RPM_package is a good tutorial, but it focuses on building packages from source. The sbt-native-packager takes the approach that SBT has built your source and generated 'binary' packages. +RedHat ``rpm`` files support a very advanced number of features. To take full advantage of this environment, +it's best to understand how the ``rpm`` package system works. +http://fedoraproject.org/wiki/How_to_create_an_RPM_package is a good tutorial, but it focuses on building +packages from source. The sbt-native-packager takes the approach that SBT has built your source and generated +'binary' packages. + +.. contents:: + :depth: 2 + + +.. raw:: html + + + + +Requirements +------------ + +You need the following applications installed + +* rpm + +Build +----- + +.. code-block:: bash + + sbt rpm:packageBin + +Required Settings +~~~~~~~~~~~~~~~~~ + +A rpm package needs some mandatory settings to be valid. Make sure +you have these settings in your build: + +.. code-block:: scala + + rpmRelease := "1" + + rpmVendor := "typesafe" + + rpmUrl := Some("http://github.com/paulp/sbt-extras") + + rpmLicense := Some("BSD") + + +1.0 or higher +~~~~~~~~~~~~~ + +Enables the rpm plugin + +.. code-block:: scala + + enablePlugins(RpmPlugin) -Settings --------- -Rpms require the following specific settings: +0.8 or lower +~~~~~~~~~~~~ + +For this versions rpm packaging is automatically activated. +See the :doc:`Getting Started ` page for informations +on how to enable sbt native packager. + +Configuration +------------- + +Settings and Tasks inherited from parent plugins can be scoped with ``Rpm``. .. code-block:: scala - name in Rpm := "sbt", - version in Rpm <<= sbtVersion.identity, - rpmRelease := "1", - rpmVendor := "typesafe", - rpmUrl := Some("http://github.com/paulp/sbt-extras"), - rpmLicense := Some("BSD"), - rpmChangelogFile := Some("changelog") + linuxPackageMappings in Rpm := linuxPackageMappings.value + +Settings +-------- Informational Settings @@ -46,53 +108,53 @@ Dependency Settings ``rpmRequirements`` The RPM packages that are required to be installed for this RPM to work. - ``rpmProvides`` + ``rpmProvides`` The RPM package names that this RPM provides. - ``rpmPrerequisites`` + ``rpmPrerequisites`` The RPM packages this RPM needs before installation - ``rpmObsoletes`` + ``rpmObsoletes`` The packages this RPM allows you to remove - ``rpmConflcits`` + ``rpmConflcits`` The packages this RPM conflicts with and cannot be installed with. Meta Settings ~~~~~~~~~~~~~ - ``rpmPrefix`` + ``rpmPrefix`` The path passed set as the base for the revocable package - ``rpmChangelogFile`` + ``rpmChangelogFile`` External file to be imported and used to generate the changelog of the RPM. Scriptlet Settings ~~~~~~~~~~~~~~~~~~ - ``rpmPretrans`` + ``rpmPretrans`` The ``%pretrans`` scriptlet to run. - ``rpmPre`` + ``rpmPre`` The ``%pre`` scriptlet to run. - ``rpmVerifyScript`` + ``rpmVerifyScript`` The ``%verifyscript%`` scriptlet to run - ``rpmPost`` + ``rpmPost`` The ``%post`` scriptlet to run - ``rpmPosttrans`` + ``rpmPosttrans`` The ``%posttrans`` scriptlet to run - ``rpmPreun`` + ``rpmPreun`` The ``%preun`` scriptlet to run. - ``rpmPostun`` + ``rpmPostun`` The ``%postun`` scriptlet to run. - ``rpmBrpJavaRepackJars`` + ``rpmBrpJavaRepackJars`` appends ``__os_install_post`` scriplet to ``rpmPre`` avoiding jar repackaging @@ -108,12 +170,18 @@ The Rpm support grants the following commands: Generates the ``.rpm`` file and runs the ``rpmlint`` command to look for issues in the package. Useful for debugging. +Customize +--------- + Rpm Prefix ----------- -The rpm prefix allows you to create a relocatable package as defined by http://www.rpm.org/max-rpm/s1-rpm-reloc-prefix-tag.html. This optional setting with a handful of overrides to scriptlets and templates will allow you to create a working java_server archetype that can be relocated in the file system. +~~~~~~~~~~ + +The rpm prefix allows you to create a relocatable package as defined by http://www.rpm.org/max-rpm/s1-rpm-reloc-prefix-tag.html. +This optional setting with a handful of overrides to scriptlets and templates will allow you to create a working java_server +archetype that can be relocated in the file system. -Example Settings -~~~~~~~~~~~~~~~~~~ + +Example Settings: .. code-block:: scala @@ -124,19 +192,23 @@ 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 -~~~~~~~~~~~~~~~~~~ +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: .. code-block:: scala - changelog := "changelog.txt", + changelog := "changelog.txt" + rpmChangelogFile := Some(changelog) -.. code-block:: txt +.. code-block:: bash + * Sun Aug 24 2014 Team - 1.1.0 -Allow to login using social networks * Wed Aug 20 2014 Team - 1.0.1 @@ -147,6 +219,7 @@ Example Settings Template Changes ~~~~~~~~~~~~~~~~~~ + Apply the following changes to the default init start script. You can find this in the sbt-native-packager source. @@ -165,7 +238,10 @@ Apply the following changes to the default init start script. You can find this Scriptlet Changes ~~~~~~~~~~~~~~~~~~ -Apply the following changes to the scriptlets that can be found in the sbt-native-packager source. + +Changing the scripts can be done in two ways. Override the ``rpmPre``, etc. scripts +or place your new scripts in the ``src/rpm`scriptlest`` folder. For example: + ``src/rpm/scriptlets/post-rpm`` @@ -186,7 +262,7 @@ Apply the following changes to the scriptlets that can be found in the sbt-nativ Jar Repackaging ---------------- +~~~~~~~~~~~~~~~ rpm repackages jars by default (described in this `blog post`_) in order to optimize jars. This behaviour is turned off by default with this setting. diff --git a/src/sphinx/DetailedTopics/universal.rst b/src/sphinx/formats/universal.rst similarity index 82% rename from src/sphinx/DetailedTopics/universal.rst rename to src/sphinx/formats/universal.rst index 07c177227..a6ea0987d 100644 --- a/src/sphinx/DetailedTopics/universal.rst +++ b/src/sphinx/formats/universal.rst @@ -1,15 +1,177 @@ .. _Universal: -Universal -========= +Universal Plugin +================ Universal packaging just takes a plain ``mappings`` configuration and generates various package files for distribution. It allows you to provide your users a distribution that is not tied to any particular platform, but may require manual labor to set up. +.. contents:: + :depth: 2 + +.. raw:: html + + + +Related Plugins +--------------- + +.. toctree:: + :maxdepth: 1 + + linux.rst + windows.rst + docker.rst + + +Requirements +------------ + +Depending on what package format you want to use, you need one of the following applications installed + +* zip (if native) +* gzip +* xz +* tar +* hdiutil (for dmg) + +Build +----- + +There is a task for each output format + + **Zip** + + .. code-block:: bash + + sbt universal:packageBin + + **Tar** + + .. code-block:: bash + + sbt universal:packageZipTarball + + **Xz** + + .. code-block:: bash + + sbt universal:packageXzTarball + + **Dmg** + + .. code-block:: bash + + sbt universal:packageOsxDmg + + +Required Settings +~~~~~~~~~~~~~~~~~ + +A universal has no mandatory fields. + + +1.0 or higher +~~~~~~~~~~~~~ + +Enable the universal plugin + +.. code-block:: scala + + enablePlugins(UniversalPlugin) + + +0.8 or lower +~~~~~~~~~~~~ + +For this versions universal packaging is automatically activated. +See the :doc:`Getting Started ` page for informations +on how to enable sbt native packager. + + +Configurations +-------------- + +Settings and Tasks inherited from parent plugins can be scoped with ``Universal``. + +Universal packaging provides three Configurations: + + ``universal`` + For creating full distributions + ``universal-docs`` + For creating bundles of documentation + ``universal-src`` + For creating bundles of source. + +.. code-block:: scala + + name in Universal := name.value + + name in UniversalDocs <<= name in Universal + + name in UniversalSrc <<= name in Universal + + packageName in Universal := packageName.value + +Settings +-------- +As we showed before, the Universal packages are completely configured through the use of the mappings key. Simply +specify the desired mappings for a given configuration. For Example: + +.. code-block:: scala + + mappings in Universal <+= packageBin in Compile map { p => p -> "lib/foo.jar" } + +However, sometimes it may be advantageous to customize the files for each archive separately. For example, perhaps +the .tar.gz has an additional README plaintext file in additon to a README.html. To add this just to the .tar.gz file, +use the task-scope feature of sbt: + +.. code-block:: scala + + mappings in Universal in package-zip-tarball += file("README") -> "README" + +Besides ``mappings``, the ``name``, ``sourceDirectory`` and ``target`` configurations are all respected by universal packaging. + +**Note: The Universal plugin will make anything in a bin/ directory executable. This is to work around issues with JVM +and file system manipulations.** + +Tasks +----- + + ``universal:package-bin`` + Creates the ``zip`` universal package. + + ``universal:package-zip-tarball`` + Creates the ``tgz`` universal package. + + ``universal:package-xz-tarball`` + Creates the ``txz`` universal package. The ``xz`` command can get better compression + for some types of archives. + + ``universal:package-osx-dmg`` + Creates the ``dmg`` universal package. This only work on OSX or systems with ``hdiutil``. + + ``universal-docs:package-bin`` + Creates the ``zip`` universal documentation package. + + ``universal-docs:package-zip-tarball`` + Creates the ``tgz`` universal documentation package. + + ``universal-docs:package-xz-tarball`` + Creates the ``txz`` universal documentation package. The ``xz`` command can get better compression + for some types of archives. + +Customize +--------- + Getting Started with Universal Packaging ----------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default, all files found in the ``src/universal`` directory are included in the distribution. So, the first step in creating a a distribution is to place files in this directory in the layout you would like in the distributed zip file. @@ -40,7 +202,7 @@ You can use this to add anything you desire to the package. Universal Conventions ---------------------- +~~~~~~~~~~~~~~~~~~~~~ This plugin has a set of conventions for universal packages that enable the automatic generation of native packages. The universal convention has the following package layout: @@ -117,50 +279,29 @@ Notice how we're *only* modifying the package mappings for Debian linux packages :ref:`Windows` and :ref:`Linux` documentation. +MappingsHelper +~~~~~~~~~~~~~~ -Configurations --------------- -Universal packaging provides three Configurations: - - ``universal`` - For creating full distributions - ``universal-docs`` - For creating bundles of documentation - ``universal-src`` - For creating bundles of source. - - -Settings --------- -As we showed before, the Universal packages are completely configured through the use of the mappings key. Simply -specify the desired mappings for a given configuration. For Example: - -.. code-block:: scala - - mappings in Universal <+= packageBin in Compile map { p => p -> "lib/foo.jar" } - -However, sometimes it may be advantageous to customize the files for each archive separately. For example, perhaps -the .tar.gz has an additional README plaintext file in additon to a README.html. To add this just to the .tar.gz file, -use the task-scope feature of sbt: - -.. code-block:: scala +The `MappingsHelper`_ class provides a set of helper functions to make mapping directories easier. - mappings in Universal in package-zip-tarball += file("README") -> "README" + **sbt 0.13.5 and plugin 1.0.x or higher** + + .. code-block:: scala -Besides ``mappings``, the ``name``, ``sourceDirectory`` and ``target`` configurations are all respected by universal packaging. + import NativePackagerHelper._ + + **plugin version 0.8.x or lower** + + .. code-block:: scala + + import com.typesafe.sbt.SbtNativePackager._ + import NativePackagerHelper._ -**Note: The Universal plugin will make anything in a bin/ directory executable. This is to work around issues with JVM and file system manipulations.** -MappingsHelper --------------- - -The `MappingsHelper`_ class provides a set of helper functions to make mapping directories easier. +You get a set of methods which will help you to create mappings very easily. .. code-block:: scala - import com.typesafe.sbt.SbtNativePackager._ - import NativePackagerHelper._ - mappings in Universal ++= directory("src/main/resources/cache") mappings in Universal ++= contentOf("src/main/resources/docs") @@ -170,10 +311,10 @@ The `MappingsHelper`_ class provides a set of helper functions to make mapping d mappings in Universal <++= sourceDirectory map (src => contentOf(src / "main" / "resources" / "docs")) -.. _MappingsHelper: https://github.com/sbt/sbt-native-packager/blob/master/src/main/scala/com/typesafe/sbt/packager/MappingsHelper.scala +.. _MappingsHelper: http://www.scala-sbt.org/sbt-native-packager/latest/api/#com.typesafe.sbt.packager.MappingsHelper$ Mapping Examples ----------------- +~~~~~~~~~~~~~~~~ SBT provides and IO and `Path`_ API, which lets you define custom mappings easily. The files will appear in the generate universal zip, but also in your @@ -204,9 +345,6 @@ It exists some helper methods to map a complete directory in more human readable .. code-block:: scala - import com.typesafe.sbt.SbtNativePackager._ - import NativePackagerHelper._ - //For dynamic content, e.g. something in the target directory which depends on a Task mappings in Universal <++= (packageBin in Compile, target) map { (_, target) => directory(target / "scala-2.10" / "api") @@ -283,28 +421,3 @@ The complete ``build.sbt`` should contain these settings if you want a single as scriptClasspath := Seq( (jarName in assembly).value ) -Commands --------- - - ``universal:package-bin`` - Creates the ``zip`` universal package. - - ``universal:package-zip-tarball`` - Creates the ``tgz`` universal package. - - ``universal:package-xz-tarball`` - Creates the ``txz`` universal package. The ``xz`` command can get better compression - for some types of archives. - - ``universal:package-osx-dmg`` - Creates the ``dmg`` universal package. This only work on OSX or systems with ``hdiutil``. - - ``universal-docs:package-bin`` - Creates the ``zip`` universal documentation package. - - ``universal-docs:package-zip-tarball`` - Creates the ``tgz`` universal documentation package. - - ``universal-docs:package-xz-tarball`` - Creates the ``txz`` universal documentation package. The ``xz`` command can get better compression - for some types of archives. diff --git a/src/sphinx/DetailedTopics/windows.rst b/src/sphinx/formats/windows.rst similarity index 74% rename from src/sphinx/DetailedTopics/windows.rst rename to src/sphinx/formats/windows.rst index e685a7a77..6e6f5348a 100644 --- a/src/sphinx/DetailedTopics/windows.rst +++ b/src/sphinx/formats/windows.rst @@ -1,62 +1,84 @@ .. _Windows: -Packaging for Windows -===================== +Windows Plugin +============== -The windows packaging is completely tied to the WIX installer toolset. For any non-trivial package, it's important to understand how WIX works. http://wix.tramontana.co.hu/ is an excellent tutorial to how to create packages using wix. +The windows packaging is completely tied to the WIX installer toolset. For any non-trivial package, +it's important to understand how WIX works. http://wix.tramontana.co.hu/ is an excellent tutorial +to how to create packages using wix. -However, the native-packager provides a simple layer on top of wix that *may* be enough for most projects. If it is not, just override ``wixConfig`` or ``wixFile`` settings. Let's look at the layer above direct xml configuration. +However, the native-packager provides a simple layer on top of wix that *may* be enough for most projects. +If it is not, just override ``wixConfig`` or ``wixFile`` settings. Let's look at the layer above direct +xml configuration. +.. contents:: + :depth: 2 + + +.. raw:: html -Feature configuration ---------------------- -The abstraction over wix allows you to configure "features" that users may optionally install. These feature are higher level things, like a set of files or menu links. -The currently supported compoennts of features are: + -1. Files (``ComponentFile``) -2. Path Configuration (``AddDirectoryToPath``) -3. Menu Shortcuts (``AddShortCuts``) +Requirements +------------ +You need the following applications installed -To create a new feature, simple instantiate the ``WindowsFeature`` class with the desired feature components that are included. +* `WIX Toolset `_ -Here's an example feature that installs a binary and a script, as well as path settings: +Build +----- + +.. code-block:: bash + + sbt windows:packageBin + +Required Settings +~~~~~~~~~~~~~~~~~ + +A rpm package needs some mandatory settings to be valid. Make sure +you have these settings in your build: .. code-block:: scala - wixFeatures += WindowsFeature( - id="BinaryAndPath", - title="My Project's Binaries and updated PATH settings", - desc="Update PATH environment variables (requires restart).", - components = Seq( - ComponentFile("bin/cool.bat"), - ComponentFile("lib/cool.jar"), - AddDirectoryToPath("bin")) - ) + rpmRelease := "1" + + rpmVendor := "typesafe" + + rpmUrl := Some("http://github.com/paulp/sbt-extras") + + rpmLicense := Some("BSD") + -All file references should line up exactly with those found in the ``mappings in Windows`` configuration. When generating an MSI, the plugin will first create -a directory using all the ``mappings in Windows`` and configure this for inclusion in a ``cab`` file. If you'd like to add files to include, these must *first* -be added to the mappings, and then to a feature. For example, if we complete the above setting to include file mappings, we'd have the following: +1.0 or higher +~~~~~~~~~~~~~ + +Enables the rpm plugin .. code-block:: scala - mappings in Windows ++= (packageBin in Compile, sourceDirectory in Windows) map { (jar, dir) => - Seq(jar -> "lib/cool.jar", (dir / "cool.bat") -> "bin/cool.bat") - } + enablePlugins(RpmPlugin) - wixFeatures += WindowsFeature( - id="BinaryAndPath", - title="My Project's Binaries and updated PATH settings", - desc="Update PATH environment variables (requires restart).", - components = Seq( - ComponentFile("bin/cool.bat"), - ComponentFile("lib/cool.jar"), - AddDirectoryToPath("bin")) - ) -Right now this layer is *very* limited in what it can accomplish, and hasn't been heavily debugged. If you're interested in helping contribute, please -do so! However, for most command line tools, it should be sufficient for generating a basic ``msi`` that windows users can install. +0.8 or lower +~~~~~~~~~~~~ + +For this versions rpm packaging is automatically activated. +See the :doc:`Getting Started ` page for informations +on how to enable sbt native packager. +Configuration +------------- + +Settings and Tasks inherited from parent plugins can be scoped with ``Rpm``. + +.. code-block:: scala + + linuxPackageMappings in Rpm := linuxPackageMappings.value Now, let's look at the full set of windows settings. @@ -100,17 +122,15 @@ Settings A list of file->location pairs. This list is used to move files into a location where WIX can pick up the files and generate a ``cab`` or embedded ``cab`` for the ``msi``. The WIX xml should use the relative locations in this mappings when references files for the package. -Commands --------- +Tasks +----- - ``windows:package-bin`` + ``windows:packageBin`` Creates the ``msi`` package. ``wix-file`` Generates the Wix xml file from `wixConfig` and `wixProductConfig` setings, unless overriden. -Utilities ---------- The native-packager plugin provides a few handy utilities for generating Wix XML. These utilities are located in the ``com.typesafe.packager.windows.WixHelper`` object. Among @@ -128,3 +148,56 @@ these are the following functions: ``Id`` settings for any generated components. This is a handy way to package a large directory of files for usage in the Features of an MSI. + +Customize +--------- + +Feature configuration +~~~~~~~~~~~~~~~~~~~~~ + +The abstraction over wix allows you to configure "features" that users may optionally install. These feature are higher level things, like a set of files or menu links. +The currently supported compoennts of features are: + +1. Files (``ComponentFile``) +2. Path Configuration (``AddDirectoryToPath``) +3. Menu Shortcuts (``AddShortCuts``) + + +To create a new feature, simple instantiate the ``WindowsFeature`` class with the desired feature components that are included. + +Here's an example feature that installs a binary and a script, as well as path settings: + +.. code-block:: scala + + wixFeatures += WindowsFeature( + id="BinaryAndPath", + title="My Project's Binaries and updated PATH settings", + desc="Update PATH environment variables (requires restart).", + components = Seq( + ComponentFile("bin/cool.bat"), + ComponentFile("lib/cool.jar"), + AddDirectoryToPath("bin")) + ) + +All file references should line up exactly with those found in the ``mappings in Windows`` configuration. When generating an MSI, the plugin will first create +a directory using all the ``mappings in Windows`` and configure this for inclusion in a ``cab`` file. If you'd like to add files to include, these must *first* +be added to the mappings, and then to a feature. For example, if we complete the above setting to include file mappings, we'd have the following: + +.. code-block:: scala + + mappings in Windows ++= (packageBin in Compile, sourceDirectory in Windows) map { (jar, dir) => + Seq(jar -> "lib/cool.jar", (dir / "cool.bat") -> "bin/cool.bat") + } + + wixFeatures += WindowsFeature( + id="BinaryAndPath", + title="My Project's Binaries and updated PATH settings", + desc="Update PATH environment variables (requires restart).", + components = Seq( + ComponentFile("bin/cool.bat"), + ComponentFile("lib/cool.jar"), + AddDirectoryToPath("bin")) + ) + +Right now this layer is *very* limited in what it can accomplish, and hasn't been heavily debugged. If you're interested in helping contribute, please +do so! However, for most command line tools, it should be sufficient for generating a basic ``msi`` that windows users can install. diff --git a/src/sphinx/gettingstarted.rst b/src/sphinx/gettingstarted.rst new file mode 100644 index 000000000..e67bd5585 --- /dev/null +++ b/src/sphinx/gettingstarted.rst @@ -0,0 +1,163 @@ +.. _GettingStarted: + +.. contents:: + :depth: 2 + +Installation +============ + +The sbt-native-packager is a plugin. To use it, first create a ``project/plugins.sbt`` file with the following content. + +.. code-block:: scala + + addSbtPlugin("com.typesafe.sbt" % "sbt-native-packager" % "x.y.z") + + +Also, each operating system requires its own tools. These tools are specified +in the operating system specific sections. + +Version 1.0 and greater +----------------------- + +If you use sbt 0.13.5 or greater you can enable sbt native packager by enabling it in your ``build.sbt``. +We recommend to `use an archetype `_ for setting up your build + +.. code-block:: scala + + enablePlugins(JavaAppPackaging) + +but if you only want the bare minimum you can only add the packager plugin + +.. code-block:: scala + + enablePlugins(SbtNativePackager) + +The autoplugins mechanism will import everything automatically. + +Build.scala +~~~~~~~~~~~ + +If you use a ``Build.scala`` you can import the available keys +with this statement + +.. code-block:: scala + + import com.typesafe.sbt.SbtNativePackager.autoImport._ + + +Version 0.8.x or lower +---------------------- + + +If you don't use autoplugins you need to import the available +keys yourself. In your ``build.sbt`` or ``Build.scala`` add + +.. code-block:: scala + + import com.typesafe.sbt.SbtNativePackager._ + import NativePackagerKeys._ + + + +Packaging Formats +================= + + +.. raw:: html + +
+
+
+

*.deb

+

Packaging format for Debian based systems like Ubuntu

+ 
debian:packageBin
+ Debian Plugin » +
+
+

*.rpm

+

Packaging format for Redhat based systems like RHEL or CentOS.

+ 
rpm:packageBin
+ Rpm Plugin » +
+
+

*.msi

+

Packaging format for windows systems.

+ 
windows:packageBin
+ Windows Plugin » +
+
+

*.dmg

+

Packaging format for osx based systems.

+ 
universal:packageOsxDmg
+ Universal Plugin » +
+
+
+
+

docker

+

Package your application in a docker container.

+ 
docker:publishLocal
+ Docker Plugin » +
+
+

*.zip

+

Packaging format for all systems supporting zip.

+ 
universal:packageBin
+ Universal Plugin » +
+
+

*.tar

+

Packaging format for all systems supporting tar.

+ 
universal:packageZipTarball
+ Universal Plugin » +
+
+

*.xz

+

Packaging format for all systems supporting xz.

+ 
universal:packageXzTarball
+ Universal Plugin » +
+
+ + + +Archetypes +========== + + +.. raw:: html + +
+
+
+

Java Application

+

Creates a standalone package with an executable bash/bat script.
 

+ 
enablePlugins(JavaAppPackaging)
+ Learn more » +
+
+

Java Server

+

Creates a standalone package with an executabl bash/bat script and additional configuration and autostart.

+ 
enablePlugins(JavaServerAppPackaging)
+ Learn more » +
+
+

Akka Microkernel

+

Like a the Java Application archetype, but instantiates and runs a subclass of + Bootable
 

+ 
enablePlugins(AkkaAppPackaging)
+ Learn more » +
+
+ + + +Sitemap +======= + +.. toctree:: + :maxdepth: 2 + + archetypes/index.rst + formats/index.rst + topics/index.rst diff --git a/src/sphinx/index.rst b/src/sphinx/index.rst index b6ae8186f..12266d57e 100644 --- a/src/sphinx/index.rst +++ b/src/sphinx/index.rst @@ -1,21 +1,64 @@ -SBT - Native Packager Plugin -############################ +.. title:: SBT Native Packager -This is the documentation for the sbt-native-packager plugin. This plugin aims -to allow easy generation of native packages for all major operating systems, including: +.. raw:: html + +
+

SBT Native Packager Plugin

+

This sbt plugin provides you with everything you need to package your application. + No matter if you want to build a simple standalone application or a server application. + The JVM let's you run anywhere. SBT Native Packager let's you deploy everywhere!

+

Getting Started »

+
+ + +
+
+

Installation

+

Add the plugin to your plugins.sbt. If you use sbt 0.13.5 + or higher the you have just one line to add to your build.sbt:

+ 
enablePlugins(SbtNativePackager)
+

We provide a set of plugins. One for each supported format and for each archetype. + Just select the one you want to use and all other plugins you require are loaded + automatically.
 

+

Getting Started »

+
+
+

Archetypes

+

For common use cases we create so called Archetypes. For a standalone + application enabling is as simple + simple as

+ 
enablePlugins(JavaAppPackaging)
+

+ The most common archtypes + are JavaAppPackaging and JavaServerAppPackaging. + Each archetype adds possible new settings which you can adapt to your need.
 

+

Learn more »

+
+
+

Formats & Customize

+

SBT Native Packager comes with a rich set of packaging formats including + zip, tar.gz, debian, rpm, msi and docker. + It's as easy as:

+ 
sbt debian:packageBin
+

An archetype doesn't cover what you need? No problem. SBT Native Packager i + build on top of some simple principles and you can customize it in many ways. + Adding a custom packaging format or some special files.

+

Learn more »

+
+
+

+ +
-* Windows MSI files -* Debian DEB packages -* RedHat RPM packages -* Docker images -* Universal (Zipped) packages for easily-launchable start scripts .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - installation.rst - /GettingStartedApplications/index.rst - /GettingStartedServers/index.rst - /DetailedTopics/index.rst - documentation.rst - + gettingstarted.rst + archetypes/index.rst + formats/index.rst + topics/index.rst + +.. raw:: html + +
diff --git a/src/sphinx/installation.rst b/src/sphinx/installation.rst deleted file mode 100644 index 3063a5d06..000000000 --- a/src/sphinx/installation.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. _Installation: - -Installation -=============== - -The sbt-native-packager is a plugin. To use it, first create a ``project/plugins.sbt`` file with the following. - -.. code-block:: scala - - addSbtPlugin("com.typesafe.sbt" % "sbt-native-packager" % "0.8.0-M2") - - -Also, each operating system requires its own tools for download. - -For the native packager keys add this to your build.sbt - -.. code-block:: scala - - import com.typesafe.sbt.SbtNativePackager._ - import NativePackagerKeys._ - -Windows -------- - -Creating Windows ``msi`` packages requires the use of the Windows Installer Xml utilities. These are available for download here: http://wix.sourceforge.net/downloadv35.html. The plugin has only been tested with version 3.5+. - - -RedHat/RPM-based linux distros ------------------------------- - -Creating ``rpm`` packages requires the use of the following command line tools: - -- ``rpmbuild`` -- ``rpm`` (optional) -- ``rpmlint`` (optional) - - -Debian-based linux distros --------------------------- - -Creating ``deb`` packages requires the use of the following command line tools: - -- ``dpkg-deb`` -- ``fakeroot`` -- ``chmod`` -- ``lintian`` (optional) - -Universal ---------- - -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. diff --git a/src/sphinx/DetailedTopics/custom.rst b/src/sphinx/topics/custom.rst similarity index 100% rename from src/sphinx/DetailedTopics/custom.rst rename to src/sphinx/topics/custom.rst diff --git a/src/sphinx/DetailedTopics/deployment.rst b/src/sphinx/topics/deployment.rst similarity index 100% rename from src/sphinx/DetailedTopics/deployment.rst rename to src/sphinx/topics/deployment.rst diff --git a/src/sphinx/documentation.rst b/src/sphinx/topics/documentation.rst similarity index 100% rename from src/sphinx/documentation.rst rename to src/sphinx/topics/documentation.rst diff --git a/src/sphinx/topics/index.rst b/src/sphinx/topics/index.rst new file mode 100644 index 000000000..13c226910 --- /dev/null +++ b/src/sphinx/topics/index.rst @@ -0,0 +1,12 @@ +Advanced Topics +############### + + + +.. toctree:: + :maxdepth: 2 + + custom.rst + play.rst + deployment.rst + documentation.rst diff --git a/src/sphinx/DetailedTopics/play.rst b/src/sphinx/topics/play.rst similarity index 83% rename from src/sphinx/DetailedTopics/play.rst rename to src/sphinx/topics/play.rst index 30fdee127..bc12861ef 100644 --- a/src/sphinx/DetailedTopics/play.rst +++ b/src/sphinx/topics/play.rst @@ -9,13 +9,13 @@ Build Configuration Depending on whether you want to package your application as a deb-package or as an rpm-package, you have to setup your build configuration accordingly. -Please, refer to :doc:`Debian ` and :doc:`Redhat ` +Please, refer to :doc:`Debian ` and :doc:`Redhat ` pages for additional information. Note that **Upstart** is not supported by all available operation systems and may not always work as expected. You can always fallback to the **SystemV** service manager instead. For more information on service managers please refer -to :doc:`Getting Started With Servers ` page. +to :doc:`Getting Started With Servers ` page. Application Configuration ------------------------- @@ -41,4 +41,4 @@ One way to provide this information is create ``src/templates/etc-default`` with This way you should either store your production configuration under ``${{path_to_app_name}}/conf/production.conf`` or put it under ``/usr/share/${{app_name}}/conf/production.conf`` by hand or using some configuration management system. -See :doc:`adding configuration ` for more information on `etc-default` template. \ No newline at end of file +See :doc:`customize java server application ` for more information on `etc-default` template.