readme.md
220 lines
| 5.9 KiB
| text/x-minidsrc
|
MarkdownLexer
cin
|
r1 | # Build and publish images with docker/podman | ||
| ## SYNOPSIS | ||||
| ```gradle | ||||
| plugins { | ||||
|
cin
|
r14 | id 'org.implab.gradle-container' | ||
|
cin
|
r1 | } | ||
| container { | ||||
| // if you want to use podman | ||||
| cliCmd = "podman" | ||||
| } | ||||
| configurations { | ||||
| app | ||||
| } | ||||
| dependencies { | ||||
| // the application that needs to be built and packed | ||||
| app project(":server") | ||||
| } | ||||
| // add custom task to copy application files | ||||
| // to the docker build context. | ||||
| task copyApp(type: Copy) { | ||||
| processResources.dependsOn it | ||||
| into container.contextDirectory.dir("root/opt/myapp") | ||||
| from configurations.app | ||||
| } | ||||
| task printVersion { | ||||
| doLast { | ||||
| println "tag: ${buildImage.imageTag.get()}" | ||||
| println "archive: ${saveImage.archiveFileName.get()}" | ||||
| } | ||||
| } | ||||
| ``` | ||||
| ## Description | ||||
| This plugin is a simple wrapper around docker CLI. All the image | ||||
|
cin
|
r14 | building process is delegated to the `Dockerfile` which will run | ||
| in the prepared build context. | ||||
|
cin
|
r1 | |||
|
cin
|
r14 | ## Project structure | ||
|
cin
|
r1 | |||
|
cin
|
r14 | * `build/` - this folder will be created during build, it can be useful while | ||
| solving Dockerfile problems | ||||
| * `context/` - the build context where `docker build` command will run. | ||||
| * `imageid` - the file storing the id of the image has been built. | ||||
| * `image-name-1.2.3.tgz` - the exported image if `saveImage` has been executed. | ||||
|
cin
|
r1 | * `src` | ||
|
cin
|
r14 | * `main` - the source files which will be copied to the build context. | ||
| ## Global properties | ||||
|
cin
|
r1 | |||
|
cin
|
r14 | There are several global properties recognized by this plugin in the project. | ||
| These properties affect images naming and publication and they are useful in | ||||
| multi-project environment. | ||||
|
cin
|
r1 | |||
| `imagesAuthority` - the registry where the image should be published. | ||||
| for example `docker.io` | ||||
| `imagesGroup` - the path to the image in the repository. | ||||
|
cin
|
r14 | `containerCli` - the command line cli, this property corresponds to | ||
| `container.cliCmd` in the project. | ||||
| Properties defined in the project takes precedence over global properties. | ||||
| ## Image names | ||||
| ```gradle | ||||
| plugins { | ||||
| id "org.implab.gradle-container" | ||||
| } | ||||
| container { | ||||
| // image authority, the repository for your images | ||||
| // defaults to global imagesAuthority property or none | ||||
| imageAuthority = "my.registry.org" | ||||
| // the image path | ||||
| // defaults to global imagesGroup property or none | ||||
| imageGroup = "my/project" | ||||
| // the name of the image | ||||
| // defaults to project.name | ||||
| imageLocalName = "foo" | ||||
| } | ||||
| // provider for imageName, returns ImageName object | ||||
| // ImageName consists of "{imageAuthority}/{imageGroup}/{imageLocalName}" | ||||
| def imageNameProvider = container.imageName | ||||
| ``` | ||||
|
cin
|
r1 | ## Tasks | ||
|
cin
|
r14 | Some tasks support passing additional options as additional command line | ||
| parameters. These task has the property `options` and some additional methods. | ||||
| | Property | Description | | ||||
| |--|--| | ||||
| | `options` | A list of additional arguments passed to `docker build` command. | | ||||
| | Method | Description | | ||||
| |---|---| | ||||
| | `option(String)` | Adds option to `options`. | | ||||
| | `option(Closure)` | Converts the parameter to provider and adds it to `options`. | | ||||
| | `option(Callable)` | Converts the parameter to provider and adds it to `options`. | | ||||
| | `options(String...)` | Adds specified options to `options`. | | ||||
| | `options(Closure)`| Converts the parameter to provider and adds it to `options`. | | ||||
| | `options(Callable)`| Converts the parameter to provider and adds it to `options` | | ||||
|
cin
|
r1 | ### buildImage | ||
|
cin
|
r14 | `type: BuildImage` | ||
|
cin
|
r1 | The task builds the image. Wrapper around the `docker build` command. | ||
|
cin
|
r14 | | Property | Description | | ||
| |---|---| | ||||
| | `contextDirectory` | A Dockerfile context directory. Set to `container.context`. | | ||||
| | `buildArgs` | A dictionary with environment variables which are set during build. | | ||||
| | `buildTarget` | A target image for the multi-stage builds. Defaults to none. | | ||||
| | `imageName` | A name (tag) for the resulting image. | | ||||
| | `imageIdFIle` | Output file name where image ref will be written. | | ||||
| This task also supports additional command line options. | ||||
|
cin
|
r1 | ### saveImage | ||
|
cin
|
r14 | `type: SaveImage` | ||
|
cin
|
r1 | The task exports image as the .tar archive. | ||
|
cin
|
r14 | | Property | Description | | ||
| |-|-| | ||||
| | `archiveFileName` | The file name of the bundle archive, defaults to `{archiveBaseName}-{archiveVersion}-{archiveClassifier}.{archiveExtension}`.| | ||||
| | `archiveBaseName` | The base name of the archive, defaults to `{project.group}-{project.name}`. | | ||||
| | `archiveVersion` | The archive version, defaults to `{project.version}`. | | ||||
| | `exportImages` | A set of image names to include in the bundle. | | ||||
| | Method | Description | | ||||
| |-|-| | ||||
| | `imageRefs(FileCollection)` | Adds a set of files with image refs to add to the bundle. | | ||||
| | `imageRef(File)` | Adds an image name from the file with image reference. | | ||||
|
cin
|
r1 | ### pushImage | ||
|
cin
|
r14 | The task pushes the image to the remote repository (imageAuthority). | ||
| [Since v1.2] This task also supports additional command line options. You can use them to | ||||
| push all tags for the image. | ||||
| ```gradle | ||||
| pushImage { | ||||
| option "--all-tags" | ||||
| } | ||||
| ``` | ||||
|
cin
|
r1 | |||
| ### processResources | ||||
|
cin
|
r14 | The copy task, it prepares the build context. Use this task to customize | ||
|
cin
|
r2 | the build context. | ||
|
cin
|
r4 | |||
| ### tagImage | ||||
|
cin
|
r14 | `type: TagImage` | ||
|
cin
|
r4 | since: 1.1 | ||
| ```gradle | ||||
| task tagLatest(type: TagImage) { | ||||
|
cin
|
r14 | pushImage.dependsOn it | ||
|
cin
|
r4 | srcImage = container.imageName | ||
|
cin
|
r14 | |||
| tags.add(container.imageName.map { it.tag("latest") }) | ||||
|
cin
|
r4 | } | ||
| ``` | ||||
|
cin
|
r14 | | Property | Description | | ||
| |-|-| | ||||
| | `srcImage` | The source image name to add tag to. | | ||||
| | `tags` | The set of tags to add to the image. | | ||||
| ## See also | ||||
| * Creating [compose](compose.md) project | ||||
| * Creating [bundle](bundle.md) project | ||||
|
cin
|
r4 | ## Changes | ||
|
cin
|
r14 | ### 1.2 | ||
| Added `org.implab.gradle-container-base`, `org.implab.gradle-container-compose` | ||||
| plugins. | ||||
| * `org.implab.gradle-container-base` registers base extension and task types. | ||||
| * `org.implab.gradle-container-compose` registers conventional tasks. | ||||
|
cin
|
r4 | ### 1.1 | ||
| Warning! This version isn't fully backward compatible with 1.0 version. | ||||
| * Added `TagImage` task type | ||||
| * `ImageTag` class is replaced with `ImageName` class | ||||
| * `BuildImage`, `PushImage` tasks are now accepting only `imageName` property | ||||
| * Added `imageName`, `imageShortName`, `imageTag` properties to `container` extension | ||||
| ### 1.0 | ||||
| Initial release. Default tasks to build and publish container images. | ||||