jlengrand/jreleaser.github.io
1
0
Fork 0
mirror of https://github.com/jlengrand/jreleaser.github.io.git synced 2026-03-10 08:31:25 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
477ef26de93eec98bfd60cea3556d6fd7509fd39
jreleaser.github.io/docs/modules/configuration/pages/packagers/docker.adoc
Andres Almiray 477ef26de9 Document latest changes
2021-05-30 23:26:19 +02:00

895 lines
25 KiB
Plaintext
Raw Blame History

= Docker
Creates link:https://www.docker.com/[Docker] images.
NOTE: Only artifacts with `.zip`, `.jar` extension may be packaged with Docker.
WARNING: Snapshots are *not* supported.
IMPORTANT: Building and publishing docker images requires the `docker` command and a running Docker deamon.
JReleaser will not install these tools.
include::partial$legend.adoc[]
[tabs]
====
YAML::
+
[source,yaml]
[subs="+macros"]
----
# icon:dot-circle[]
packagers:
# icon:dot-circle[]
docker:
# Enables or disables Docker.
# Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
# Defaults to `NEVER`.
# icon:dot-circle[]
active: ALWAYS
# Directory with file templates used to prepare the Docker distribution.
# Defaults to `src/jreleaser/distributions/${distribution.name}/docker`.
# If specified, path must exist.
# icon:dot-circle[]
templateDirectory: path/to/docker/templates
# The base Docker image to use.
# icon:dot-circle[] icon:file-alt[]
baseImage: "alpine:latest"
# A list of image names.
# If unspecified, a single image `{{repoOwner}}/{{distributionName}}:{{tagName}}`
# will be created.
# icon:dot-circle[] icon:file-alt[]
imageNames:
- "{{repoOwner}}/{{distributionName}}:{{tagName}}"
- "duke/app:latest"
# A list of build arguments.
# icon:dot-circle[] icon:file-alt[]
buildArgs:
- "--pull"
# Dockerfile commands to run before the assembly.
# icon:dot-circle[] icon:file-alt[]
preCommands:
- "RUN apt-get update -y"
- "RUN apt-get install unzip"
# Dockerfile commands to run after the assembly, before ENTRYPOINT.
# icon:dot-circle[] icon:file-alt[]
postCommands:
- "VOLUME /workspace"
# A map of Docker labels.
# icon:dot-circle[]
labels:
foo: bar
# Additional properties used when evaluating templates.
# icon:dot-circle[] icon:file-alt[]
extraProperties:
# Key will be capitalized and prefixed with `docker`, i.e, `dockerFoo`.
foo: bar
# A list of docker registries where images will be published.
# Image publication will be disabled if no registries are configured.
# icon:dot-circle[]
registries:
# The name of the registry. Must be unique.
# Use `DEFAULT` to match the default registry
# provided by the Docker daemon.
# icon:exclamation-triangle[]
- serverName: myRegistry
# The address of the docker registry.
# icon:exclamation-triangle[] if `serverName != DEFAULT`.
server: pass:[https://myregistry.com]
# The user that can publish images.
# Defaults to the same username as the release repository.
# icon:dot-circle[]
username: duke
# Password for login into the registry
# If left unspecified, the `JRELEASER_DOCKER_${serverName}_PASSWORD`
# environment variable must be defined.
# icon:dot-circle[] icon:eye-slash[]
password: __DO_NOT_SET_HERE__
# The name of the repository
# Defaults to the same owner as the release repository.
# icon:dot-circle[]
repositoryName: duke
----
TOML::
+
[source,toml]
[subs="+macros"]
----
# icon:dot-circle[]
[packagers.docker]
# Enables or disables Docker.
# Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
# Defaults to `NEVER`.
# icon:dot-circle[]
active = "ALWAYS"
# Directory with file templates used to prepare the Docker distribution.
# Defaults to `src/jreleaser/distributions/${distribution.name}/docker`.
# If specified, path must exist.
# icon:dot-circle[]
templateDirectory = "path/to/docker/templates"
# The base Docker image to use.
# icon:dot-circle[] icon:file-alt[]
baseImage = "alpine:latest"
# A list of image names.
# If unspecified, a single image `{{repoOwner}}/{{distributionName}}:{{tagName}}`
# will be created.
# icon:dot-circle[] icon:file-alt[]
imageNames = [
"{{repoOwner}}/{{distributionName}}:{{tagName}}",
"duke/app:latest"]
# A list of build arguments.
# icon:dot-circle[] icon:file-alt[]
buildArgs = ["--pull"]
# Dockerfile commands to run before the assembly.
# icon:dot-circle[] icon:file-alt[]
preCommands = [
"RUN apt-get update -y",
"RUN apt-get install unzip"]
# Dockerfile commands to run after the assembly, before ENTRYPOINT.
# icon:dot-circle[] icon:file-alt[]
postCommands = ["VOLUME /workspace"]
# A map of Docker labels.
# icon:dot-circle[]
labels.foo = "bar"
# Additional properties used when evaluating templates.
# icon:dot-circle[] icon:file-alt[]
extraProperties.foo = "bar"
# Key will be capitalized and prefixed with `docker`, i.e, `dockerFoo`.
# A list of docker registries where images will be published.
# Image publication will be disabled if no registries are configured.
# icon:dot-circle[]
pass:[[[packagers.docker.registries]]]
# The name of the registry. Must be unique.
# Use `DEFAULT` to match the default registry
# provided by the Docker daemon.
# icon:exclamation-triangle[]
serverName = "myRegistry"
# The address of the docker registry.
# icon:exclamation-triangle[] if `serverName != DEFAULT`.
server = "pass:[https://myregistry.com]"
# The user that can publish images.
# Defaults to the same username as the release repository.
# icon:dot-circle[]
username = "duke"
# Password for login into the registry
# If left unspecified, the `JRELEASER_DOCKER_${serverName}_PASSWORD`
# environment variable must be defined.
# icon:dot-circle[] icon:eye-slash[]
password = "__DO_NOT_SET_HERE__"
# The name of the repository
# Defaults to the same owner as the release repository.
# icon:dot-circle[]
repositoryName = "duke"
----
JSON::
+
[source,json]
[subs="+macros"]
----
{
// icon:dot-circle[]
"packagers": {
// icon:dot-circle[]
"docker": {
// Enables or disables Docker.
// Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
// Defaults to `NEVER`.
// icon:dot-circle[]
"active": "ALWAYS",
// Directory with file templates used to prepare the Docker distribution.
// Defaults to `src/jreleaser/distributions/${distribution.name}/docker`.
// If specified, path must exist.
// icon:dot-circle[]
"templateDirectory": "path/to/docker/templates",
// The base Docker image to use.
// icon:dot-circle[] icon:file-alt[]
"baseImage": "alpine:latest",
// A list of image names.
// If unspecified, a single image `{{repoOwner}}/{{distributionName}}:{{tagName}}`
// will be created.
// icon:dot-circle[] icon:file-alt[]
"imageNames": [
"{{repoOwner}}/{{distributionName}}:{{tagName}}",
"duke/app:latest"
],
// A list of build arguments.
// icon:dot-circle[] icon:file-alt[]
"buildArgs": [
"--pull"
],
// Dockerfile commands to run before the assembly.
// icon:dot-circle[] icon:file-alt[]
"preCommands": [
"RUN apt-get update -y",
"RUN apt-get install unzip"
],
// Dockerfile commands to run after the assembly, before ENTRYPOINT.
// icon:dot-circle[] icon:file-alt[]
"postCommands": [
"VOLUME /workspace"
],
// A map of Docker labels.
// icon:dot-circle[]
"labels": {
"foo": "bar"
},
// Additional properties used when evaluating templates.
// icon:dot-circle[] icon:file-alt[]
"extraProperties": {
// Key will be capitalized and prefixed with `docker`, i.e, `dockerFoo`.
"foo": "bar"
},
// A list of docker registries where images will be published.
// Image publication will be disabled if no registries are configured.
// icon:dot-circle[]
"registries": [
{
// The name of the registry. Must be unique.
// Use `DEFAULT` to match the default registry
// provided by the Docker daemon.
// icon:exclamation-triangle[]
"serverName": "someName",
// The address of the docker registry.
// icon:exclamation-triangle[] if `serverName != DEFAULT`.
"server": "pass:[https://myregistry.com]",
// The user that can publish images.
// Defaults to the same username as the release repository.
// icon:dot-circle[]
"username": "duke",
// Password for login into the registry
// If left unspecified, the `JRELEASER_DOCKER_${serverName}_PASSWORD`
// environment variable must be defined.
// icon:dot-circle[] icon:eye-slash[]
"password": "__DO_NOT_SET_HERE__",
// The name of the repository
// Defaults to the same owner as the release repository.
// icon:dot-circle[]
"repositoryName": "duke"
}
]
}
}
}
----
Maven::
+
[source,xml]
[subs="+macros,verbatim"]
----
<jreleaser>
<!--
icon:dot-circle[]
-->
<packagers>
<!--
icon:dot-circle[]
-->
<docker>
<!--
Enables or disables Docker.
Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
Defaults to `NEVER`.
icon:dot-circle[]
-->
<active>ALWAYS</active>
<!--
Directory with file templates used to prepare the Docker distribution.
Defaults to `src/jreleaser/distributions/${distribution.name}/docker`.
If specified, path must exist.
icon:dot-circle[]
-->
<templateDirectory>>path/to/docker/templates</templateDirectory>
<!--
The base Docker image to use.
icon:dot-circle[] icon:file-alt[]
-->
<baseImage>alpine:latest</baseImage>
<!--
A list of image names.
If unspecified, a single image `{{repoOwner}}/{{distributionName}}:{{tagName}}`
will be created.
icon:dot-circle[] icon:file-alt[]
-->
<imageNames>
<imageName>{{repoOwner}}/{{distributionName}}:{{tagName}}</imageName>
<imageName>duke/app:latest</imageName>
</imageNames>
<!--
A list of build arguments.
icon:dot-circle[] icon:file-alt[]
-->
<buildArgs>
<buildArg>--pull</buildArg>
</buildArgs>
<!--
Dockerfile commands to run before the assembly.
icon:dot-circle[] icon:file-alt[]
-->
<preCommands>
<preCommand>RUN apt-get update -y</preCommand>
<preCommand>RUN apt-get install unzip</preCommand>
</preCommands>
<!--
Dockerfile commands to run after the assembly, before ENTRYPOINT.
icon:dot-circle[] icon:file-alt[]
-->
<postCommands>
<postCommand>VOLUME /workspace</postCommand>
</postCommands>
<!--
A map of Docker labels.
icon:dot-circle[]
-->
<labels>
<foo>bar</foo>
</labels>
<!--
Additional properties used when evaluating templates.
icon:dot-circle[] icon:file-alt[]
-->
<extraProperties>
<!--
Key will be capitalized and prefixed with `docker`, i.e, `dockerFoo`.
-->
<foo>bar</foo>
</extraProperties>
<!--
A list of docker registries where images will be published.
Image publication will be disabled if no registries are configured.
icon:dot-circle[]
-->
<registries>
<registry>
<!--
The name of the registry. Must be unique.
Use `DEFAULT` to match the default registry
provided by the Docker daemon.
icon:exclamation-triangle[]
-->
<serverName>myRegistry</serverName>
<!--
The address of the docker registry.
icon:exclamation-triangle[] if `serverName != DEFAULT`.
-->
<server>pass[https: myregistry.com]</server>
<!--
The user that can publish images.
Defaults to the same username as the release repository.
icon:dot-circle[]
-->
<username>duke</username>
<!--
Password for login into the registry
If left unspecified, the `JRELEASER_DOCKER_${serverName}_PASSWORD`
environment variable must be defined.
icon:dot-circle[] icon:eye-slash[]
-->
<password>__DO_NOT_SET_HERE__</password>
<!--
The name of the repository
Defaults to the same owner as the release repository.
icon:dot-circle[]
-->
<repositoryName>duke</repositoryName>
</registry>
</registries>
</docker>
</packagers>
</jreleaser>
----
Gradle::
+
[source,groovy]
[subs="+macros"]
----
jreleaser {
// icon:dot-circle[]
packagers {
// icon:dot-circle[]
docker {
// Enables or disables Docker.
// Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
// Defaults to `NEVER`.
// icon:dot-circle[]
active = 'ALWAYS'
// Directory with file templates used to prepare the Docker distribution.
// Defaults to `src/jreleaser/distributions/${distribution.name}/docker`.
// If specified, path must exist.
// icon:dot-circle[]
templateDirectory = 'path/to/docker/templates'
// The base Docker image to use.
// icon:dot-circle[] icon:file-alt[]
baseImage = 'alpine:latest'
// A list of image names.
// If unspecified, a single image `{{repoOwner}}/{{distributionName}}:{{tagName}}`
// will be created.
// icon:dot-circle[] icon:file-alt[]
addImageName('{{repoOwner}}/{{distributionName}}:{{tagName}}')
addImageName('duke/app:latest')
// A list of build arguments.
// icon:dot-circle[] icon:file-alt[]
addBuildArg('--pull')
// Dockerfile commands to run before the assembly.
// icon:dot-circle[] icon:file-alt[]
addPreCommand('RUN apt-get update -y')
addPreCommand('RUN apt-get install unzip')
// Dockerfile commands to run after the assembly, before ENTRYPOINT.
// icon:dot-circle[] icon:file-alt[]
addPostCommand('VOLUME /workspace')
// A map of Docker labels.
// The key `openjdk@${java.version}` will be added automatically if not defined.
// icon:dot-circle[]
addLabel('foo', 'bar')
// Additional properties used when evaluating templates.
// Key will be capitalized and prefixed with `scoop`, i.e, `scoopFoo`.
// icon:dot-circle[] icon:file-alt[]
extraProperties.put('foo', 'bar')
// A list of docker registries where images will be published.
// Image publication will be disabled if no registries are configured.
// icon:dot-circle[]
registries {
// The name of the registry. Must be unique.
// Use `DEFAULT` to match the default registry
// provided by the Docker daemon.
// icon:exclamation-triangle[]
someName {
// The address of the docker registry.
// icon:exclamation-triangle[] if `serverName != DEFAULT`.
server = 'pass:[https://myregistry.com]'
// The user that can publish images.
// Defaults to the same username as the release repository.
// icon:dot-circle[]
username = 'duke'
// Password for login into the registry
// If left unspecified, the `JRELEASER_DOCKER_${serverName}_PASSWORD`
// environment variable must be defined.
// icon:dot-circle[] icon:eye-slash[]
password = '__DO_NOT_SET_HERE__'
// The name of the repository
// Defaults to the same owner as the release repository.
// icon:dot-circle[]
repositoryName = 'duke'
}
}
}
}
}
----
====
Template files may be initialized using the `template` command.
Assuming that the current version is `1.2.3`, and a distribution named `app`, the above configuration will generate
a Dockerfile like the following one:
[source,dockerfile]
----
FROM azul/zulu-openjdk-alpine:8-jre
LABEL "org.opencontainers.image.title"="app"
LABEL "org.opencontainers.image.description"="Awesome App"
LABEL "org.opencontainers.image.url"="https://acme.com/app"
LABEL "org.opencontainers.image.licenses"="Apache-2.0"
LABEL "org.opencontainers.image.version"="1.2.3"
LABEL "org.opencontainers.image.revision"="de0266d314b91dd201765616e207d0a8706d0b99"
COPY assembly/app-1.2.3.zip /app-1.2.3.zip
RUN unzip app-1.2.3.zip && \
rm app-1.2.3.zip && \
chmod +x app-1.2.3/bin/app
ENV PATH="${PATH}:/app-1.2.3/bin"
ENTRYPOINT ["/app-1.2.3/bin/app"]
----
== Base Images
Different values for the default base image will be used depending on the distribution type:
* `azul/zulu-openjdk-alpine:${distribution.java.version}-jre` for JAVA_BINARY and SINGLE_JAR distributions.
* `alpine:latest` for JLINK distributions.
* `scratch` for NATIVE_IMAGE distributions.
== Default Labels
JReleaser will add the following labels if they are not explicitly defined:
* org.opencontainers.image.title = {{distributionName}}
* org.opencontainers.image.description = {{projectDescription}}
* org.opencontainers.image.url = {{projectWebsite}}
* org.opencontainers.image.licenses = {{projectLicense}}
* org.opencontainers.image.version = {{projectVersion}}
* org.opencontainers.image.revision = {{commitFullHash}}
You may use any xref:configuration:name-templates.adoc[] as part of the label value.
== Generic Image Names
Some users might want to keep their image name as generic as possible. That can be accomplished simply by adding
a template to the `imageNames` field.
[tabs]
====
YAML::
+
[source,yaml]
[subs="+macros"]
----
project:
name: app
packagers:
docker:
active: ALWAYS
imageNames:
- "myuser/{{projectName}}"
----
TOML::
+
[source,toml]
[subs="+macros"]
----
[project]
name = "app"
[packagers.docker]
active = "ALWAYS"
imageNames = ["myuser/{{projectName}}"]
----
JSON::
+
[source,json]
[subs="+macros"]
----
{
"project": {
"name": "app"
},
"packagers": {
"docker": {
"active": "ALWAYS",
"imageNames": [
"myuser/{{projectName}}"
]
}
}
}
----
Maven::
+
[source,xml]
[subs="+macros,verbatim"]
----
<!-- project.artifactId = app -->
<jreleaser>
<packagers>
<docker>
<active>ALWAYS</active>
<imageNames>
<imageName>myuser/{{projectName}}</imageName>
</imageNames>
</docker>
</packagers>
</jreleaser>
----
Gradle::
+
[source,groovy]
[subs="+macros"]
----
// project.name = app
jreleaser {
packagers {
docker {
active = 'ALWAYS'
addImageName('myuser/{{projectName}}')
}
}
}
----
====
This will build the following images:
* `myuser/app`
== Prerelease Image Names
A different set of images names will be automatically configured when the project is snapshot, to avoid possible clashes
with production images.
JReleaer will look for the first image name that ends with `:{{tagName}}` and discard the rest.
It will use `{{repoOwner}}/{{distributionName}}:{{tagName}}` if no matching image name is found.
== Keeping docker images updated for current major
Some users might want to when version to push docker tags `:v1`, `:v1.6`, `:v1.6.4` and `:latest` when `v1.6.4`
(for example) is built. That can be accomplished by using multiple image names:
[tabs]
====
YAML::
+
[source,yaml]
[subs="+macros"]
----
project:
name: app
packagers:
docker:
active: ALWAYS
imageNames:
- "myuser/myimage:{{tagName}}"
- "myuser/myimage:v{{projectVersionMajor}}"
- "myuser/myimage:v{{projectVersionMajor}}.{{projectVersionMinor}}"
- "myuser/myimage:latest"
----
TOML::
+
[source,toml]
[subs="+macros"]
----
[project]
name = "app"
[packagers.docker]
active = "ALWAYS"
imageNames = [
"myuser/myimage:{{tagName}}",
"myuser/myimage:v{{projectVersionMajor}}",
"myuser/myimage:v{{projectVersionMajor}}.{{projectVersionMinor}}",
"myuser/myimage:latest"]
----
JSON::
+
[source,json]
[subs="+macros"]
----
{
"project": {
"name": "app"
},
"packagers": {
"docker": {
"active": "ALWAYS",
"imageNames": [
"myuser/myimage:{{tagName}}",
"myuser/myimage:v{{projectVersionMajor}}",
"myuser/myimage:v{{projectVersionMajor}}.{{projectVersionMinor}}",
"myuser/myimage:latest"
]
}
}
}
----
Maven::
+
[source,xml]
[subs="+macros,verbatim"]
----
<!-- project.artifactId = app -->
<jreleaser>
<packagers>
<docker>
<active>ALWAYS</active>
<imageNames>
<imageName>myuser/myimage:{{tagName}}</imageName>
<imageName>myuser/myimage:v{{projectVersionMajor}}</imageName>
<imageName>myuser/myimage:v{{projectVersionMajor}}.{{projectVersionMinor}}</imageName>
<imageName>myuser/myimage:latest</imageName>
</imageNames>
</docker>
</packagers>
</jreleaser>
----
Gradle::
+
[source,groovy]
[subs="+macros"]
----
// project.name = app
jreleaser {
packagers {
docker {
active = 'ALWAYS'
addImageName('myuser/myimage:{{tagName}}')
addImageName('myuser/myimage:v{{projectVersionMajor}}')
addImageName('myuser/myimage:v{{projectVersionMajor}}.{{projectVersionMinor}}')
addImageName('myuser/myimage:latest')
}
}
}
----
====
This will build the following images:
* `myuser/myimage:v1.6.4`
* `myuser/myimage:v1`
* `myuser/myimage:v1.6`
* `myuser/myimage:latest`
== Additional Files
Any files placed inside `${docker.templateDirectory}/assembly` will be copied into the container at the root.
== Multiple Dockerfile per Distribution
The previous sections explain how a single or multiple Docker images may be created for a single distribution using the
same Dockerfile. However should you need to use several Dockerfiles with the same distribution then just add a `specs`
section and configure each `spec` to your liking. Each `spec` takes the same arguments as the `docker` section plus an
extra element named `matchers` that determines which distribution artifact should be used with that particular `spec`.
Matchers are key/value pairs that can match the artifact's `platform` property and any of its `extraProperties`.
This feature is useful when paired with an assembled Jlink distribution that defines more than one artifact that may be
packaged with Docker. Here's for example how JReleaser handles the case of generating cross-platform Java Runtimes with
Jlink; there are 2 artifacts (the linux variants) that may be distributed with Docker, each one requiring different
settings:
[tabs]
====
YAML::
+
[source,yaml]
[subs="+macros"]
----
environment:
properties:
jdkPathPrefix: 'apps/jreleaser/build/jdks/zulu11.48.21-ca-jdk11.0.11'
assemble:
jlinks:
jreleaser-standalone:
active: always
extraProperties:
sdkmanSkip: true
java:
version: 11
mainClass: 'org.jreleaser.cli.Main'
imageName: '{{distributionName}}-{{projectEffectiveVersion}}'
executable: 'jreleaser'
moduleNames:
- java.base
- java.desktop
- java.management
- java.naming
- java.rmi
- java.security.jgss
- java.sql
targetJdks:
- path: '{{jdkPathPrefix}}-macosx_x64/zulu-11.jdk/Contents/Home'
platform: 'osx'
- path: '{{jdkPathPrefix}}-linux_x64'
platform: 'linux'
- path: '{{jdkPathPrefix}}-linux_musl_x64'
platform: 'linux_musl'
- path: '{{jdkPathPrefix}}-win_x64'
platform: 'windows'
mainJar:
path: 'apps/jreleaser/build/libs/jreleaser-{{projectVersion}}.jar'
jars:
- directory: 'apps/jreleaser/build/dependencies/flat'
include: '*.jar'
distributions:
# name must match!
jreleaser-standalone:
docker:
# inherited by specs
active: always
# inherited by specs
registries:
- serverName: DEFAULT
# inherited by specs
labels:
'org.opencontainers.image.title': 'jreleaser'
# inherited by specs
postCommands:
- 'VOLUME /workspace'
# configure 2 specs
specs:
slim:
imageNames:
- 'jreleaser/jreleaser-{{dockerSpecName}}:{{tagName}}'
- 'jreleaser/jreleaser-{{dockerSpecName}}:latest'
# match by platform
matchers:
platform: 'linux'
preCommands:
- 'RUN apt-get update -y'
- 'RUN apt-get install unzip'
alpine:
imageNames:
- 'jreleaser/jreleaser-{{dockerSpecName}}:{{tagName}}'
- 'jreleaser/jreleaser-{{dockerSpecName}}:latest'
# match by platform
matchers:
platform: 'linux_musl'
preCommands:
- 'RUN apk add unzip'
----
====
This generates two different images:
* `jreleaser/jreleaser-slim:<tag>` with `ubuntu:latest` as base image. Packages
`jreleaser-standalone-<version>-linux.zip` because of the matching platform.
* `jreleaser/jreleaser-alpine:<tag>` with `alpine:latest` as base image. Packages
`jreleaser-standalone-<version>-linux_musl.zip` because of the matching platform.
Reference in New Issue View Git Blame Copy Permalink