Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adding some documentation to the debian package. #127

Merged
merged 4 commits into from
Jan 21, 2014
Merged

Adding some documentation to the debian package. #127

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
dacc9be
Adding some documentation to the debian package.
muuki88 Jan 10, 2014
5fd2121
Fixed some layout issues
muuki88 Jan 10, 2014
ade1889
Adding a additional information
muuki88 Jan 11, 2014
8532b35
Fixing typo
muuki88 Jan 12, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion src/sphinx/archetypes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,11 @@ Java Server

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.
immediately upon startup. To activate this archetype replace ``packageArchetype.java_application`` with

.. code-block:: scala

packageArchetype.java_server

Currently supported operating systems:

Expand Down
103 changes: 103 additions & 0 deletions src/sphinx/debian.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,8 @@ 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.

``
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what is this fixing up?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, no idea. Will remove this.



Tasks
Expand All @@ -49,3 +51,104 @@ The Debian support grants the following commands:

``debian:lintian``
Generates the ``.deb`` file and runs the ``lintian`` command to look for issues in the package. Useful for debugging.


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 <[email protected]>"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A nice generic name. I like it. However, Max Fightmaster is a real person, and I feel would make this example pop :)


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 Packagin with Debian
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/Packagin/Packaging

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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 <[email protected]>"

maintainer in Windows := "Jane Smith <[email protected]>"

packageSummary in Debian := "Hello World Debian Package"

packageSummary in Windows := "Hello World Windows Package"

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.

Customizing Debian Packaging
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

A Debian package provides metadata, which includes **dependencies** and **recommendations**.
A basic example to depend on java and recommend a git installation.

.. code-block:: scala

debianPackageDependencies in Debian ++= Seq("java2-runtime", "bash (>= 2.05a-11)")

debianPackageRecommends in Debian += "git"

To hook into the debian package lifecycle (https://wiki.debian.org/MaintainerScripts) you
can add ``preinst`` , ``postinst`` , ``prerm`` and/or ``postrm`` scripts. Just place them into
``src/debian/DEBIAN``.

If you use the ``packageArchetype.java_server`` there are predefined ``postinst`` and
``preinst`` files, which start/stop the application on install/remove calls.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might be worth stating the packageArchetype.java_server predefined scripts modif/extends any user defined src/debian/DEBIAN scripts and does not replace them


Your control scripts are in a different castle.. directory? No problem.

.. code-block:: scala

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

daemonUser := "root"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It might be worth adding information about the postrm and postinst scripts generated when daemonUser is not the root user.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

also the example should probably not be root, as to encourage folks not to use root...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well this is the default, but I get the point people will copy'n'paste-code this (even they don't have too as mentioned one sentence above).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I'm debating making it not the default as well (just for server archetype)... WDYT?

we should try to promote "best" (good) practices in the default configurations....

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, didn't get that :)
IMHO root is the only practical default as this will always work out-of-the-box.

Is there a way to enforce configuration settings in sbt? The idea would be to add a setting appUser which has to be set.
This setting is used to set default daemonUser, user and group permissions for all packageMappings. The API could
look like this

appUser := "player"

// This would be the defaults
appGroup <<= appUser

daemonUser <<= appUser

defaultPackageUser <<= appUser

defaultPackageGroup <<= appGroup

useDefaultPackagePermissions := true

This would create a lot of new configuration settings and essentially a bunch of new features.
However we can enforce the user not using root as default.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I'd love to see normalized name used, if we can. Anyone have a link to user name restrictions?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From the user add man page

"It is usually recommended to only use usernames that begin with a lower case letter or an underscore, followed by lower case letters, digits, underscores, or dashes. They can end with a dollar sign. In regular expression terms: [a-z_][a-z0-9_-]*[$]?

On Debian, the only constraints are that usernames must neither start with a dash (-) nor contain a colon (:) or a whitespace (space: , end of line: \n, tabulation: \t, etc.). Note that using a slash (/) may break the default algorithm for the definition of the users home directory.

Usernames may only be up to 32 characters long."

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the 32-character thing we may need to enforce, otherwise I think normalizedName fits....

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The configuration can actually be found here /usr/share/adduser/adduser.conf in the NAME_REGEX key. Should we use this regex for debian:packageBin to check the normalized name, at least to give a warning "this username may not work on a debian system"

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds great to me!


Change these values as you need. For more informations look at the :ref:`Archetypes` page