diff --git a/project/plugins.sbt b/project/plugins.sbt index 7d62a5711..249ff6a24 100644 --- a/project/plugins.sbt +++ b/project/plugins.sbt @@ -6,7 +6,7 @@ addSbtPlugin("com.typesafe.sbt" % "sbt-ghpages" % "0.5.2") addSbtPlugin("com.typesafe.sbt" % "sbt-git" % "0.6.2") -addSbtPlugin("com.typesafe.sbt" % "sbt-site" % "0.7.1") +addSbtPlugin("com.typesafe.sbt" % "sbt-site" % "0.7.2") libraryDependencies <+= (sbtVersion) { sv => "org.scala-sbt" % "scripted-plugin" % sv diff --git a/src/sphinx/archetypes.rst b/src/sphinx/DetailedTopics/archetypes.rst similarity index 100% rename from src/sphinx/archetypes.rst rename to src/sphinx/DetailedTopics/archetypes.rst diff --git a/src/sphinx/debian.rst b/src/sphinx/DetailedTopics/debian.rst similarity index 99% rename from src/sphinx/debian.rst rename to src/sphinx/DetailedTopics/debian.rst index f1c3c73d7..143943572 100644 --- a/src/sphinx/debian.rst +++ b/src/sphinx/DetailedTopics/debian.rst @@ -37,8 +37,6 @@ Debian requires the following specific settings: are placed in the ``DEBIAN`` file when building. Some of these files can be autogenerated, for example when using a package archetype, like server_application. Howeve, any autogenerated file can be overridden by placing your own files in the ``src/debian/DEBIAN`` directory. - - `` Tasks diff --git a/src/sphinx/DetailedTopics/index.rst b/src/sphinx/DetailedTopics/index.rst new file mode 100644 index 000000000..a179f4272 --- /dev/null +++ b/src/sphinx/DetailedTopics/index.rst @@ -0,0 +1,14 @@ +Advanced Topics +############### + + + +.. toctree:: + :maxdepth: 2 + + archetypes.rst + universal.rst + linux.rst + redhat.rst + debian.rst + windows.rst \ No newline at end of file diff --git a/src/sphinx/linux.rst b/src/sphinx/DetailedTopics/linux.rst similarity index 100% rename from src/sphinx/linux.rst rename to src/sphinx/DetailedTopics/linux.rst diff --git a/src/sphinx/redhat.rst b/src/sphinx/DetailedTopics/redhat.rst similarity index 100% rename from src/sphinx/redhat.rst rename to src/sphinx/DetailedTopics/redhat.rst diff --git a/src/sphinx/universal.rst b/src/sphinx/DetailedTopics/universal.rst similarity index 97% rename from src/sphinx/universal.rst rename to src/sphinx/DetailedTopics/universal.rst index 04323d10c..d3cd0987b 100644 --- a/src/sphinx/universal.rst +++ b/src/sphinx/DetailedTopics/universal.rst @@ -161,10 +161,10 @@ Mapping a complete directory. } This maps the ``api`` folder directly to the generate universal zip. ``dir.***`` is a short way for -``dir ** "*"``, which means _select all files including dir_. ``relativeTo(dir.getParentFile)`` +``dir ** "*"``, which means _select all files including *dir*. ``relativeTo(dir.getParentFile)`` generates a function with a ``file -> Option[String]`` mapping, which tries to generate a relative string path from ``dir.getParentFile`` to the passed in file. ``pair`` uses the ``relativeTo`` -function to generate a mapping ``File -> String``, which is _your file_ to _relative destination_. +function to generate a mapping ``File -> String``, which is *your file* to *relative destination*. It exists some helper methods to map a complete directory in more human readable way. diff --git a/src/sphinx/windows.rst b/src/sphinx/DetailedTopics/windows.rst similarity index 100% rename from src/sphinx/windows.rst rename to src/sphinx/DetailedTopics/windows.rst diff --git a/src/sphinx/GettingStartedApplications/AddingConfiguration.rst b/src/sphinx/GettingStartedApplications/AddingConfiguration.rst new file mode 100644 index 000000000..1ba35d730 --- /dev/null +++ b/src/sphinx/GettingStartedApplications/AddingConfiguration.rst @@ -0,0 +1,134 @@ +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 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 + +Now, if we run the ``stage`` task, we'll see this file show up in the distribution :: + + $ sbt stage + $ ls target/universal/stage + bin/ + conf/ + lib/ + $ ls target/unviersal/stage/conf + jvmopts + +By default, any file in the ``src/universal`` directory is packaged. This is a convenient way to include things like licenses, and readmes. + +Now, we need to modify the script templates to load this configuration. To do so, add the following +to ``build.sbt`` :: + + bashScriptConfigLocation := Some("${app_home}/../conf/jvmopts") + +Here, we define the configuration location for the BASH script too look for the ``conf/jvmopts`` file. Now, let's run ``sbt stage`` and then execute the script in debug mode to see what command line it executes :: + + ./target/universal/stage/bin/example-cli -d + # Executing command line: + java + -Xms1024m + -Xmx1024m + -XX:MaxPermSize=256m + -XX:ReservedCodeCacheSize=128m + -DsomeProperty=true + -cp + /home/jsuereth/projects/sbt/sbt-native-packager/tutorial-example/target/universal/stage/lib/example-cli.example-cli-1.0.jar:/home/jsuereth/projects/sbt/sbt-native-packager/tutorial-example/target/universal/stage/lib/org.scala-lang.scala-library-2.10.3.jar:/home/jsuereth/projects/sbt/sbt-native-packager/tutorial-example/target/universal/stage/lib/com.typesafe.config-1.2.0.jar + TestApp + + +The configuration file for bash scripts takes arguments for the BASH file on each line, and allows comments which start with the ``#`` character. Essentially, this provides a set of default arguments when calling the script. + +Now that we have ability to configure the JVM, let's add in a more robust method of customizing the applciation. We'll be using the `Typesafe Config `_ library for this purpose. + +First, let's add it as a dependency in ``build.sbt`` :: + + libraryDependencies += "com.typesafe" % "config" % "1.2.0" + +Next, let's create the configuration file itself. Add the following to ``src/universal/conf/app.config`` :: + + example { + greeting = "Hello, World!" + } + +Now, we need a means of telling the typesafe config library where to find our configuration. The library supports +a JVM property "``config.file``" which it will use to look for configuration. Let's expose this file +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 :: + + import com.typesafe.config.ConfigFactory + + object TestApp extends App { + val config = ConfigFactory.load() + println(config.getString("example.greeting")) + } + +Now, let's try it out on the command line :: + + $ sbt stage + $ ./target/universal/stage/bin/example-cli + Hello, World! + + +Finally, let's see what this configuration looks like in a linux distribution. Let's run the debian packaging again :: + + $ sbt debian:packageBin + +The resulting structure is the following :: + + /usr/ + share/example-cli/ + conf/ + app.config + jvmopts + bin/ + example-cli + lib/ + example-cli.example-cli-1.0.jar + org.scala-lang.scala-library-2.10.3.jar + bin/ + example-cli -> ../share/example-cli/bin/example-cli + /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. + +Configuring for Windows +~~~~~~~~~~~~~~~~~~~~~~~ +While we just covered how to do configuration for linux/mac, windows offers some subtle differences. + +First, while the BASH file allows you to configure where to load JVM options and default arguments, in +windows we can only configure JVM options. The path is hardcoded, as well to: + +``/@@APP_ENV_NAME@@_config.txt`` + +where ``@@APP_ENV_NAME@@`` is replaced with an environment friendly name for your app. In this example, that would be: ``EXAMPLE_CLI``. + +We can provide a configuration for JVM options on windows by creating a ``src/universal/EXAMPLE_CLI_config.txt`` file with the following contents :: + + -Xmx512M + -Xms128M + +This will add each line of the file as arguments to the JVM when running your application. + + +Now, if we want to add the typesafe config library again, we need to write the ``config.file`` property into the JVM options again. + +One means of doing this is hooking the ``batScriptExtraDefines`` key. This allows us to insert various BAT settings/commands into the script. Let's use this to hook the config file location, using the other variables in the BASH script. Modify your ``build.sbt`` as follows :: + + batScriptExtraDefines += """set _JAVA_OPTS=%_JAVA_OPTS% -Dconfig.file=%EXAMPLE_CLI_HOME%\\conf\\app.config""" + +Now, the windows version will also load the configuration from the ``conf/`` directory of the package. + + +Next, let's :doc:`add some generated files `. \ No newline at end of file diff --git a/src/sphinx/GettingStartedApplications/GeneratingFiles.rst b/src/sphinx/GettingStartedApplications/GeneratingFiles.rst new file mode 100644 index 000000000..50f219b83 --- /dev/null +++ b/src/sphinx/GettingStartedApplications/GeneratingFiles.rst @@ -0,0 +1,51 @@ +Generating files for the package +################################ + +Let's dynamically (in the build) construct some files that should be included in the package. + + +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 :: + + val downloadLicense = taskKey[File]("Downloads the latest license file.") + + downloadLicense := { + val location = target.value / "downloads" / "LICENSE" + location.getParentFile.mkdirs() + IO.download(url("http://www.schillmania.com/projects/soundmanager2/license.txt?txt"), location) + location + } + +Now, we have a taks that will download the BSD license when run. Note: We assume that the license file is +something you host on your own website and keep up to date separately form the package. + +Next, let's wire this license into the package. The native package, by default, works with **mappings**. +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 +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`` :: + + mappings in Universal += downloadLicense.value -> "LICENSE" + +This is appending a new mapping to those used for packaging. In this case, we reference the file returned by +the ``downloadLicense`` task and put it in the root directory of the package, calling it ``LICENSE``. We +can verify this by checking the ``stage`` task :: + + $ sbt stage + $ ls target/universal/stage + bin conf lib LICENSE + +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 be 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. diff --git a/src/sphinx/GettingStartedApplications/MyFirstProject.rst b/src/sphinx/GettingStartedApplications/MyFirstProject.rst new file mode 100644 index 000000000..81522b9e5 --- /dev/null +++ b/src/sphinx/GettingStartedApplications/MyFirstProject.rst @@ -0,0 +1,136 @@ +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 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/plguins.sbt`` file with the following contents :: + + addSbtPlugin("com.typesafe.sbt" % "sbt-native-packager" % "0.7.0-RC1") + +Now, the build needs to be configured for packaging. Let's define the ``build.sbt`` file as follows + +.. code-block:: scala + + name := "example-cli" + + version := "1.0" + + packageArchetype.java_application + +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 +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 +``src/main/scala/TestApp.scala`` + +.. code-block:: scala + + object TestApp extends App { + println("IT LIVES!") + } + +Once this is created, start ``sbt`` on the console and run the ``stage`` command :: + + $ sbt + > stage + +Now, in another terminal, let's look at what was generated :: + + target/universal/stage/ + bin/ + example-cli + example-cli.bat + lib/ + example-cli.example-cli-1.0.jar + org.scala-lang.scala-library-2.10.3.jar + +By default, the plugin has created both a windows BAT file and a linux/mac bash script for running the application. +In addition, all the dependent jars are added into the ``lib/`` folder. Let's try out the script in a terminal :: + + $ ./target/universal/stage/bin/example-cli + IT LIVES! + $ + +Now that the package has been verified, let's work on the generic or "universal" packaging. This is when +the plugin packages your application in a simple format that should be consumable from most operating systems or +platforms. There are two ways to do this in the sbt console :: + + > universal:packageBin + [info] /home/jsuereth/projects/sbt/sbt-native-packager/tutorial-example/target/universal/example-cli-1.0.zip + + > universal:packageZipTarabell + [info] /home/jsuereth/projects/sbt/sbt-native-packager/tutorial-example/target/universal/example-cli-1.0.tgz + +This task simple constructs either a tgz or zip file with the exact same contents we found in the staged directory. + +While this is a great first step towards deploying our application, we'd like to make it even simpler. Our target +deployment platform is Ubuntu. The command line tool should be usable by all our developers with a very simple +installation and update mechanism. So, let's try to make a debian out of our package. Try the ``debian:packageBin`` task in the sbt console :: + + > debian:packageBin + [trace] Stack trace suppressed: run last debian:debianControlFile for the full output. + [error] (debian:debianControlFile) packageDescription in Debian cannot be empty. Use + [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 genreate 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 + + packageDescription in Debian := "Example Cli" + + maintainer in Debian := "Josh Suereth" + +Now, let's try to run the ``debian:packageBin`` command in the sbt console again :: + + $ sbt + > debian:PacakgeBin + [info] Altering postrm/postinst files to add user example-cli and group example-cli + [info] dpkg-deb: building package `example-cli' in `/home/jsuereth/projects/sbt/sbt-native-packager/tutorial-example/target/example-cli-1.0.deb' + +This generates a debian file that will install the following owners and files :: + + root:root /usr/ + examplecli:examplecli share/example-cli/ + examplecli:examplecli bin/ + examplecli:examplecli example-cli + examplecli:examplecli lib/ + examplecli:examplecli example-cli.example-cli-1.0.jar + examplecli:examplecli org.scala-lang.scala-library-2.10.3.jar + root:root bin/ + root:root example-cli -> ../share/example-cli/bin/example-cli + +So, the default packaing takes the "universal" distribution and places it inside a ``/usr/share`` directory, owned by a user for the application. In addition, there is a a symlink in ``/usr/bin`` to the distributed bin script. This allows users on the platform to run the ``example-cli`` as a native install. + +We can generate other packages via the following tasks. Here's a complete list of current options. + +* ``universal:packageBin`` - Generates a universal zip file +* ``universal:packageZipTarball`` - Generates a universal tgz file +* ``debian:packageBin`` - Generates a deb +* ``rpm:packageBin`` - Generates an rpm +* ``universal::packageOsxDmg`` - Generates a DMG file with the same contents as the universal zip/tgz. +* ``windows:packageBin`` - Generates an MSI + +While we only covered the necessary configuration for ``debian``, each package type beyond ``universal`` requires some additonal +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. + + diff --git a/src/sphinx/GettingStartedApplications/OverridingTemplates.rst b/src/sphinx/GettingStartedApplications/OverridingTemplates.rst new file mode 100644 index 000000000..f02dfda18 --- /dev/null +++ b/src/sphinx/GettingStartedApplications/OverridingTemplates.rst @@ -0,0 +1,70 @@ +Overriding templates +#################### + +While the native packager tries to provide robust BASH/BAT scripts for your applications, they may not always be enough. +The native packager provides a mechanism where the template used to create each script can be directly overridden. + +Let's override the default BASH template. To do so, we'll 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 `. \ No newline at end of file diff --git a/src/sphinx/GettingStartedApplications/WritingDocumentation.rst b/src/sphinx/GettingStartedApplications/WritingDocumentation.rst new file mode 100644 index 000000000..f1d0279f2 --- /dev/null +++ b/src/sphinx/GettingStartedApplications/WritingDocumentation.rst @@ -0,0 +1,54 @@ +Writing Documentation +##################### + +There are many ways to document your projects, and many ways to expose them. While the native packager places +no limit on WHAT is included in a package, there are some things which receive special treatment. + +Specifically: linux man pages. + + +To create a linux man page for the application, let's create a ``src/linux/usr/share/man/man1/example-cli.1`` file :: + + + .\" Process this file with + .\" groff -man -Tascii example-cli.1 + .\" + .TH EXAMPLE_CLI 1 "NOVEMBER 2011" Linux "User Manuals" + .SH NAME + example-cli \- Example CLI + .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). + +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 :: + + $ sbt + > generateManPages + [info] Generated man page for[/home/jsuereth/projects/sbt/sbt-native-packager/tutorial-example/src/linux/usr/share/man/man1/example-cli.1] = + [info] EXAMPLE_CLI(1) User Manuals EXAMPLE_CLI(1) + [info] + [info] + [info] + [info] NAME + [info] example-cli - Example CLI + [info] + [info] SYNOPSIS + [info] example-cli [-h] + [info] + [info] + [info] + [info] Linux NOVEMBER 2011 EXAMPLE_CLI(1) + + +We can use this task to work on the man pages and ensure they'll look ok. You can also directly use ``groff`` to view changes in +your man pages. + +In addition to providing the means to view the man page, the native packager will also automatically ``gzip`` man pages for the +distribution. The resulting man page is stored in ``/usr/share/man/man1/example-cli.1.gz`` in linux distributions. + + +TODO - A bit more on other documentation methods. + + +That's the end fo the getting started guide for Java Applications! Feel free to read the guide on Java Servers, which offers a few differences in how configuration is done, necessary for packaging to underlying systems. \ No newline at end of file diff --git a/src/sphinx/gettingstarted.rst b/src/sphinx/GettingStartedApplications/gettingstarted.rst similarity index 100% rename from src/sphinx/gettingstarted.rst rename to src/sphinx/GettingStartedApplications/gettingstarted.rst diff --git a/src/sphinx/GettingStartedApplications/index.rst b/src/sphinx/GettingStartedApplications/index.rst new file mode 100644 index 000000000..4e1497e06 --- /dev/null +++ b/src/sphinx/GettingStartedApplications/index.rst @@ -0,0 +1,19 @@ +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. + +.. 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 new file mode 100644 index 000000000..9b48ec704 --- /dev/null +++ b/src/sphinx/GettingStartedServers/AddingConfiguration.rst @@ -0,0 +1,78 @@ +Adding configuration +#################### + +After :doc:`creating a package `, the very next thing needed, usually, is the ability for users/ops to customize the application once it's deployed. Let's add some configuration to the newly deployed application. + +There are generally two types of configurations: + +* Configuring the JVM and the process +* Configuring the Application itself. + +The server archetype provides you with a special feature to configure your application +with a single file. As this file is OS dependend, each OS gets section. + +Linux +***** + +Create ``src/templates/etc-default`` with the following template + +.. code-block :: bash + + # Available replacements + # ------------------------------------------------ + # ${{author}} debian author + # ${{descr}} debian package description + # ${{exec}} startup script name + # ${{chdir}} app directory + # ${{retries}} retries for startup + # ${{retryTimeout}} retry timeout + # ${{app_name}} normalized app name + # ${{daemon_user}} daemon user + # ------------------------------------------------- + + # Setting -Xmx and -Xms in Megabyte + # -mem 1024 + + # Setting -X directly (-J is stripped) + # -J-X + # -J-Xmx1024 + + # Add additional jvm parameters + # -Dkey=val + + # For play applications you may set + # -Dpidfile.path=/var/run/${{app_name}}/play.pid + + # Turn on JVM debugging, open at the given port + # -jvm-debug + + # Don't run the java version check + # -no-version-check + + # enabling debug and sending -d as app argument + # the '--' prevents app-parameter swalloing when + # using a reserved parameter. See #184 + # -d -- -d + +The file will be installed to ``/etc/default/`` and read from there +by the startscript. + +Environment variables +===================== + +The usual ``JAVA_OPTS`` can be used to override settings. This is a nice way to test +different jvm settings with just restarting the jvm. + +Windows +***** + +Support planned for 0.8.0 + +Example Configurations +###################### + +A list of very small configuration settings can be found at `sbt-native-packager-examples`_ + + .. _sbt-native-packager-examples: https://github.com/muuki88/sbt-native-packager-examples + +Next, let's :doc:`how to override start templates `. diff --git a/src/sphinx/GettingStartedServers/MyFirstProject.rst b/src/sphinx/GettingStartedServers/MyFirstProject.rst new file mode 100644 index 000000000..3b86b7684 --- /dev/null +++ b/src/sphinx/GettingStartedServers/MyFirstProject.rst @@ -0,0 +1,90 @@ +My First Packaged Server Project +################################ + +Follow the instructions for the basic ``java_application`` setup in :doc:`../GettingStartedApplications/index` to get a working build and +understand the core concepts of sbt-native-packager. Based on this configuration we exchange +in our ``build.sbt`` + +.. code-block:: scala + + packageArchetype.java_application + +with + +.. code-block:: scala + + packageArchetype.java_server + + +which will activate all server specific settings. As the server settings are dependent +on which OS your using the following sections will provide details for each supported +OS. + +Linux +***** + +A basic ``build.sbt`` for the supported ``rpm`` and ``deb`` packaging systems +require the following information: + +.. code-block:: scala + + maintainer in Linux := "John Smith " + + packageSummary in Linux := "A small package summary" + + packageDescription := "A longer description of your application" + + +There are additional parameters available to configure. + +.. code-block:: scala + + daemonUser in Linux := normalizedName.value // user which will execute the application + + daemonGroup in Linux := daemonUser.value // group which will execute the application + + +Debian (.deb) +============= + +A basic ``build.sbt`` for debian requires only the Linuxs settings. You can build your +server application with + +:: + + debian:packageBin + + +Ubuntu provides two different bootsystems, SystemV and Upstart (default). To switch between +both you can add this to your ``build.sbt`` + +.. code-block:: scala + + import com.typesafe.sbt.packager.archetypes.ServerLoader.{SystemV, Upstart} + + serverLoading in Debian := SystemV + +RPM (.rpm) +========== + +A basic ``build.sbt`` for rpm requires the Linuxs settings and + +.. code-block:: scala + + rpmVendor := "Your organization Inc." + +Build your rpm package with :: + + rpm:packageBin + +The output is partially on ``stderr`` which is a bit confusing. If the build +ends with *success* you are fine. + +Windows +******* + +Planned for 0.8.0 + +Next, let's look at how to :doc:`Add configuration files ` to use with our script. + + diff --git a/src/sphinx/GettingStartedServers/OverrdingTemplates.rst b/src/sphinx/GettingStartedServers/OverrdingTemplates.rst new file mode 100644 index 000000000..8f9683cc0 --- /dev/null +++ b/src/sphinx/GettingStartedServers/OverrdingTemplates.rst @@ -0,0 +1,5 @@ +Overriding templates +#################### + +This works the same way as for the standard application type. Read more on :doc:`../GettingStartedApplications/OverridingTemplates` + diff --git a/src/sphinx/GettingStartedServers/index.rst b/src/sphinx/GettingStartedServers/index.rst new file mode 100644 index 000000000..e7c550b51 --- /dev/null +++ b/src/sphinx/GettingStartedServers/index.rst @@ -0,0 +1,50 @@ +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. + +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. + +Currently the native package supports the following installation targets for servers: + ++---------------+--------------------+-----------+ +| Platform | Service Manager | Working | ++===============+====================+===========+ +| Ubuntu | Upstart | X | ++---------------+--------------------+-----------+ +| Ubuntu | System V | X | ++---------------+--------------------+-----------+ +| CentOS | System V | X | ++---------------+--------------------+-----------+ +| Fedora | System V | X | ++---------------+--------------------+-----------+ +| Windows | Windows Services | | ++---------------+--------------------+-----------+ + +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/conf.py b/src/sphinx/conf.py index b3d5d65b7..111d47238 100644 --- a/src/sphinx/conf.py +++ b/src/sphinx/conf.py @@ -12,6 +12,7 @@ # serve to show the default. import sys, os +import sphinx_bootstrap_theme # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -41,7 +42,7 @@ # General information about the project. project = u'sbt-native-packager' -copyright = u'2011, Josh Suereth' +copyright = u'2014 sbt-native-packager team' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -91,15 +92,20 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'sphinxdoc' +html_theme = 'bootstrap' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. #html_theme_options = {} +html_theme_options = { + 'bootstrap_version': "3", + 'bootswatch_theme': "yeti", +} # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = [] +html_theme_path = sphinx_bootstrap_theme.get_html_theme_path() # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". diff --git a/src/sphinx/index.rst b/src/sphinx/index.rst index 6b2446235..1b7ec73a3 100644 --- a/src/sphinx/index.rst +++ b/src/sphinx/index.rst @@ -12,12 +12,10 @@ to allow native packages to be created for all major operating systems, includin .. toctree:: - :maxdepth: 4 + :maxdepth: 1 installation.rst - gettingstarted.rst - universal.rst - linux.rst - windows.rst - archetypes.rst + /GettingStartedApplications/index.rst + /GettingStartedServers/index.rst + /DetailedTopics/index.rst