-
Notifications
You must be signed in to change notification settings - Fork 440
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.
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
Clarify and fix grammar for Formats docs #867
Changes from 72 commits
f4ffa80
89a274c
66d2c62
1f9587f
bcca9cd
4df5a78
f5a3256
4a1475d
65d2de0
c99d1c8
d5a974f
428070b
158a4a8
aaa4658
db5d835
e88eea8
ac3c54c
68b9544
ce711c7
89d4e89
1fa721f
d263c6a
3875036
e990067
06ec785
6326761
76996c1
2054a31
429c757
a8cdcec
d9d1200
a7d5c57
d99643c
aed3975
86aa18d
836f444
fa18cfe
94424c0
6b63bde
e797cf3
1e1b0ec
982641a
8e38188
57510df
1afab3f
d54ce59
96858bf
fbb45db
e70a687
7e55cb5
9342194
2be5327
b17c2c1
68d1511
cbc8ad1
6c8c2ea
f2ace76
dd715e8
c4c5104
5417965
82ca26a
9271f75
11f328b
77c1386
2fb2820
8722e68
84de452
6012bf7
1e3917d
0dc67ae
765e846
34a938e
9ddf24b
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -4,11 +4,17 @@ 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. | ||
the underlying packaging system works. `Debian Binary Package Building HOWTO`_ by Chr. Clemens Lee 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 <https://github.com/tcurdt/jdeb>`_. By default the *native* implementation | ||
is activated. | ||
.. _Debian Binary Package Building HOWTO: http://tldp.org/HOWTO/html_single/Debian-Binary-Package-Building-HOWTO/ | ||
|
||
|
||
SBT Native Packager provides two ways to build debian packages: | ||
|
||
1. A native implementation, where you need ``dpkg-deb`` installed, or | ||
2. A java, platform independent approach with `jdeb <https://github.com/tcurdt/jdeb>`_. | ||
|
||
By default the *native* implementation is activated. | ||
|
||
.. note:: The debian plugin depends on the :ref:`linux-plugin`. | ||
|
||
|
@@ -79,7 +85,7 @@ installation of the generated debian package in the following configuration: | |
|
||
- installation using python-apt module, used by Ansible and SaltStack for | ||
example, | ||
- being on python-apt 8.8 series, that's on Debian Wheezy and perhaps older | ||
- being on python-apt 8.8 series that's on Debian Wheezy and perhaps older | ||
|
||
It will fail with an error message like:: | ||
|
||
|
@@ -95,21 +101,22 @@ Solutions include: | |
Java based packaging | ||
~~~~~~~~~~~~~~~~~~~~ | ||
|
||
If you want to use the java based implementation, enable the following plugin. | ||
If you want to use the java based implementation, enable the following plugin: | ||
|
||
.. code-block:: scala | ||
|
||
enablePlugins(JDebPackaging) | ||
|
||
and this to your ``plugins.sbt`` | ||
and this to your ``plugins.sbt``: | ||
|
||
.. code-block:: scala | ||
|
||
libraryDependencies += "org.vafer" % "jdeb" % "1.3" artifacts (Artifact("jdeb", "jar", "jar")) | ||
|
||
JDeb is a provided dependency so you have to add it on your own. It brings a lot of dependencies | ||
JDeb is a provided dependency. (It is not a not an AutoPlugin_.) You have to explicitly add it on your own. It brings a lot of dependencies | ||
that could slow your build times. This is the reason the dependency is marked as provided. | ||
|
||
.. _AutoPlugin: http://www.scala-sbt.org/0.13/docs/Using-Plugins.html#Enabling+and+disabling+auto+plugins | ||
|
||
|
||
Configurations | ||
|
@@ -180,23 +187,26 @@ The Debian support grants the following commands: | |
Customize | ||
--------------- | ||
|
||
This section contains example on how you can customize your debian build. | ||
This section contains examples of how you can customize your debian build. | ||
|
||
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. | ||
This example adds a dependency on java and recommends a git installation. | ||
|
||
.. code-block:: scala | ||
|
||
debianPackageDependencies in Debian ++= Seq("java2-runtime", "bash (>= 2.05a-11)") | ||
|
||
debianPackageRecommends in Debian += "git" | ||
|
||
Hook Actions into the Debian Package Lifecycle | ||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
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``. Or you can do it programmatically in your ``build.sbt`` | ||
``src/debian/DEBIAN``. Or you can do it programmatically in your ``build.sbt``. This example adds actions to ``preinst`` and ``postinst``: | ||
|
||
.. code-block:: scala | ||
|
||
|
@@ -210,7 +220,10 @@ The helper methods can be found in `MaintainerScriptHelper Scaladocs`_. | |
|
||
If you use the ``JavaServerAppPackaging`` there are predefined ``postinst`` and | ||
``preinst`` files, which start/stop the application on install/remove calls. Existing | ||
maintainer scripts will be extended not overridden. | ||
maintainer scripts will be *extended* not overridden. | ||
|
||
Use a Different Castle Directory for your Control Scripts | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Ah :( I guess you can remove the bad jokes here as well ;) |
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
Your control scripts are in a different castle.. directory? No problem. | ||
|
||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -6,16 +6,17 @@ 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. | ||
|
||
https://docs.docker.com/introduction/understanding-docker/ provides an introduction to Docker. | ||
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. | ||
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. | ||
|
||
.. note:: The docker plugin depends on the :ref:`universal-plugin`. | ||
|
||
Requirements | ||
------------ | ||
|
||
You need the docker console client installed and version `1.3` or higher is required. | ||
You need the version 1.3 or higher of the docker console client installed. | ||
SBT Native Packager doesn't use the REST API, but instead uses the CLI directly. | ||
|
||
It is currently not possible to provide authentication for Docker repositories from within the build. | ||
|
@@ -55,9 +56,12 @@ and this to your ``plugins.sbt`` | |
|
||
libraryDependencies += "com.spotify" % "docker-client" % "3.5.13" | ||
|
||
The Docker-spotify client is a provided dependency so you have to add it on your own. | ||
It brings a lot of dependenciesthat could slow your build times. This is the reason | ||
the dependency is marked as provided. | ||
The Docker-spotify client is a provided dependency. (It is not a not an AutoPlugin_.) You have to explicitly add it on your own. It brings a lot of dependencies | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Again "It is not a not an AutoPlugin._" ? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'll remove it. |
||
that could slow your build times. This is the reason the dependency is marked as provided. | ||
|
||
.. _AutoPlugin: http://www.scala-sbt.org/0.13/docs/Using-Plugins.html#Enabling+and+disabling+auto+plugins | ||
|
||
|
||
|
||
Configuration | ||
------------- | ||
|
@@ -85,7 +89,7 @@ Informational Settings | |
The version of the package for Docker (if different from general version). Often takes the form ``x.y.z``. | ||
|
||
``maintainer in Docker`` | ||
The maintainer of the package, required by the Dockerfile format. | ||
The maintainer of the package, required by the Docker file format. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Ya. I think I let autocorrect go too far. Will fix. |
||
|
||
Environment Settings | ||
~~~~~~~~~~~~~~~~~~~~ | ||
|
@@ -130,7 +134,7 @@ Publishing Settings | |
|
||
Tasks | ||
----- | ||
The Docker support provides the following commands: | ||
The Docker plugin provides the following commands: | ||
|
||
``docker:stage`` | ||
Generates a directory with the Dockerfile and environment prepared for creating a Docker image. | ||
|
@@ -145,13 +149,13 @@ The Docker support provides the following commands: | |
Customize | ||
--------- | ||
|
||
There are some predefined settings, which you can easily customize. These | ||
There are some predefined settings which you can easily customize. These | ||
settings are explained in some detail in the next sections. If you want to | ||
describe your Dockerfile completely yourself, you can provide your own | ||
`docker commands` as described in `Custom Dockerfile`_. | ||
|
||
Docker Image Name | ||
~~~~~~~~~~~~~~~~~ | ||
Docker Image Name and Version | ||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
.. code-block:: scala | ||
|
||
|
@@ -184,11 +188,11 @@ Docker Image Customization | |
|
||
|
||
In order to work properly with `USER daemon` the exposed volumes are first | ||
created (if they do not existend) and chowned. | ||
created (if they do not existend) and then chowned. | ||
|
||
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 location setting. | ||
The files from ``mappings in Docker`` are extracted underneath this directory. | ||
|
||
.. code-block:: scala | ||
|
@@ -215,8 +219,8 @@ In your sbt console type | |
Remove Commands | ||
~~~~~~~~~~~~~~~ | ||
|
||
SBT Native Packager added some commands you may not need. For example | ||
the chowning of a exposed volume. | ||
SBT Native Packager adds commands you may not need. For example, | ||
the chowning of a exposed volume: | ||
|
||
.. code-block:: scala | ||
|
||
|
@@ -225,27 +229,30 @@ the chowning of a exposed volume. | |
// we want to filter the chown command for '/data' | ||
dockerExposedVolumes += "/data" | ||
|
||
// use filterNot to return all items that do NOT meet the criteria | ||
dockerCommands := dockerCommands.value.filterNot { | ||
|
||
// ExecCmd is a case class, and args is a varargs variable, so you need to bind it with @ | ||
case ExecCmd("RUN", args @ _*) => args.contains("chown") && args.contains("/data") | ||
|
||
// dont filter the rest | ||
// don't filter the rest; don't filter out anything that doesn't match a pattern | ||
case cmd => false | ||
} | ||
|
||
|
||
Add Commands | ||
~~~~~~~~~~~~ | ||
|
||
Adding commands is as straightforward as adding anything in a list. | ||
Since ``dockerCommands`` is just a ``Sequence``, adding commands is straightforward: | ||
|
||
.. code-block:: scala | ||
|
||
import com.typesafe.sbt.packager.docker._ | ||
|
||
// use += to add an item to a Sequence | ||
dockerCommands += Cmd("USER", daemonUser.value) | ||
|
||
// use ++= to merge a sequence with an existing sequence | ||
dockerCommands ++= Seq( | ||
// setting the run script executable | ||
ExecCmd("RUN", | ||
|
@@ -281,21 +288,25 @@ Now let's start adding some Docker commands. | |
Busybox/Ash Support | ||
~~~~~~~~~~~~~~~~~~~ | ||
|
||
The default shell support for the Java archetype (JavaAppPackaging) is bash, with a Windows | ||
bat file also generated. Busybox is a popular minimal Docker base image that uses ash, a much | ||
more limited shell than bash. The result is that if you build a Docker image for Busybox the | ||
Busybox is a popular minimal Docker base image that uses ash_, a much | ||
more limited shell than bash. By default, the Java archetype (:ref:`java-app-plugin`) generates two files for shell | ||
support: a ``bash`` file, and a Windows ``.bat`` file. If you build a Docker image for Busybox using the defaults, the | ||
generated bash launch script will likely not work. | ||
|
||
Optionally you can use an ash-compatible archetype that derives from JavaAppPacking called | ||
AshScriptPlugin. Enable this by including: | ||
.. _ash: https://en.wikipedia.org/wiki/Almquist_shell | ||
|
||
To handle this, you can use *AshScriptPlugin*, an ash-compatible archetype that is derived from the :ref:`java-app-plugin` archetype. | ||
. Enable this by including: | ||
|
||
.. code-block:: scala | ||
|
||
enablePlugins(AshScriptPlugin) | ||
|
||
With this plugin enabled an ash-compatible launch script will be generated in your Docker image. | ||
|
||
Just like for JavaAppPackaging you have the option of overriding the default script by supplying | ||
your own src/templates/ash-template file. When overriding the file don't forget to include | ||
${{template_declares}} somewhere to populate $app_classpath $app_mainclass from your sbt project. | ||
Just like for :ref:`java-app-plugin`, you have the option of overriding the default script by supplying | ||
your own ``src/templates/ash-template`` file. When overriding the file don't forget to include | ||
``${{template_declares}}`` somewhere to populate ``$app_classpath $app_mainclass`` from your sbt project. | ||
You'll likely need these to launch your program. | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"It is not a not an AutoPlugin._" ? I think you can remove that :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Will do. (I think that shows my personal learning curve. :-) )