Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/palantir/gradle-docker
a Gradle plugin for orchestrating docker builds and pushes.
https://github.com/palantir/gradle-docker
docker gradle octo-correct-managed
Last synced: 23 days ago
JSON representation
a Gradle plugin for orchestrating docker builds and pushes.
- Host: GitHub
- URL: https://github.com/palantir/gradle-docker
- Owner: palantir
- License: apache-2.0
- Created: 2015-09-17T21:24:35.000Z (about 9 years ago)
- Default Branch: develop
- Last Pushed: 2024-09-27T12:07:00.000Z (about 1 month ago)
- Last Synced: 2024-09-28T03:41:10.650Z (about 1 month ago)
- Topics: docker, gradle, octo-correct-managed
- Language: Groovy
- Size: 1.25 MB
- Stars: 748
- Watchers: 272
- Forks: 158
- Open Issues: 124
-
Metadata Files:
- Readme: readme.md
- Changelog: changelog/0.22.2/pr-296.v2.yml
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-gradle - palantir/gradle-docker - Build and push Docker images. (Plugins / VM and container)
README
Docker Gradle Plugin
====================
[](https://circleci.com/gh/palantir/gradle-docker)
[](https://plugins.gradle.org/plugin/com.palantir.docker)
Disclaimer: This Repo is now Defunct
-------------
- This repo is on life support only - although we will keep it working, no new features are accepted;
- It is no longer used internally at Palantir.
Docker Plugin
-------------
This repository provides three Gradle plugins for working with Docker containers:
- `com.palantir.docker`: add basic tasks for building and pushing
docker images based on a simple configuration block that specifies the container
name, the Dockerfile, task dependencies, and any additional file resources
required for the Docker build.
- `com.palantir.docker-compose`: adds a task for populating placeholders in a
docker-compose template file with image versions resolved from
dependencies.
- `com.palantir.docker-run`: adds tasks for starting, stopping, statusing and cleaning
up a named container based on a specified image
Apply the plugin using standard gradle convention:
````gradle
plugins {
id 'com.palantir.docker' version ''
}
````
Set the container name, and then optionally specify a Dockerfile, any task
dependencies and file resources required for the Docker build. This plugin will
automatically include outputs of task dependencies in the Docker build context.
**Docker Configuration Parameters**
- `name` the name to use for this container, may include a tag
- `tags` (deprecated) (optional) an argument list of tags to create; any tag in `name` will
be stripped before applying a specific tag; defaults to the empty set
- `tag` (optional) a tag to create with a specified task name
- `dockerfile` (optional) the dockerfile to use for building the image; defaults to
`project.file('Dockerfile')` and must be a file object
- `files` (optional) an argument list of files to be included in the Docker build context, evaluated per `Project#files`. For example, `files tasks.distTar.outputs` adds the TAR/TGZ file produced by the `distTar` tasks, and `files tasks.distTar.outputs, 'my-file.txt'` adds the archive in addition to file `my-file.txt` from the project root directory. The specified files are collected in a Gradle CopySpec which may be copied `into` the Docker build context directory. The underlying CopySpec may also be used to copy entire directories into the build context. The following example adds the aforementioned archive and text file to the CopySpec, uses the CopySpec to add all files `from` `src/myDir` into the CopySpec, then finally executes the copy into the directory `myDir` in docker build context.
````gradle
docker {
files tasks.distTar.outputs, 'my-file.txt'
copySpec.from("src/myDir").into("myDir")
}
````
The final structure will be:
```
build/
docker/
myDir/
my-file.txt
// contents of task.distTar.outputs
// files from src/myDir
```
- `buildArgs` (optional) an argument map of string to string which will set --build-arg
arguments to the docker build command; defaults to empty, which results in no --build-arg parameters
- `labels` (optional) a map of string to string which will set --label arguments
to the docker build command; defaults to empty, which results in no labels applied.
- `pull` (optional) a boolean argument which defines whether Docker should attempt to pull
a newer version of the base image before building; defaults to `false`
- `noCache` (optional) a boolean argument which defines whether Docker build should add the option --no-cache,
so that it rebuilds the whole image from scratch; defaults to `false`
- `buildx` (optional) a boolean argument which defines whether Docker build should use buildx for cross platform builds; defaults to `false`
- `platform` (optional) a list of strings argument which defines which platforms buildx should target; defaults to empty
- `builder` (optional) a string argument which defines which builder buildx should use; defaults to `null`
- `load` (optional) a boolean argument which defines whether Docker buildx builder should add --load flag,
loading the image into the local repository; defaults to `false`
- `push` (optional) a boolean argument which defines whether Docker buildx builder should add --push flag,
pushing the image into the remote registry; defaults to `false`
To build a docker container, run the `docker` task. To push that container to a
docker repository, run the `dockerPush` task.
Tag and Push tasks for each tag will be generated for each provided `tag` and `tags` entry.
**Examples**
Simplest configuration:
```gradle
docker {
name 'hub.docker.com/username/my-app:version'
}
```
Canonical configuration for building a Docker image from a distribution archive:
```gradle
// Assumes that Gradle "distribution" plugin is applied
docker {
name 'hub.docker.com/username/my-app:version'
files tasks.distTar.outputs // adds resulting *.tgz to the build context
}
```
Configuration specifying all parameters:
```gradle
docker {
name 'hub.docker.com/username/my-app:version'
tags 'latest' // deprecated, use 'tag'
tag 'myRegistry', 'my.registry.com/username/my-app:version'
dockerfile file('Dockerfile')
files tasks.distTar.outputs, 'file1.txt', 'file2.txt'
buildArgs([BUILD_VERSION: 'version'])
labels(['key': 'value'])
pull true
noCache true
}
```
Managing Docker image dependencies
----------------------------------
The `com.palantir.docker` and `com.palantir.docker-compose` plugins provide
functionality to declare and resolve version-aware dependencies between docker
images. The primary use-case is to generate `docker-compose.yml` files whose
image versions are mutually compatible and up-to-date in cases where multiple
images depend on the existence of the same Dockerized service.
### Specifying and publishing dependencies on Docker images
The `docker` plugin adds a `docker` Gradle component and a `docker` Gradle
configuration that can be used to specify and publish dependencies on other
Docker containers.
**Example**
```gradle
plugins {
id 'maven-publish'
id 'com.palantir.docker'
}
...
dependencies {
docker 'foogroup:barmodule:0.1.2'
docker project(":someSubProject")
}
publishing {
publications {
dockerPublication(MavenPublication) {
from components.docker
artifactId project.name + "-docker"
}
}
}
```
The above configuration adds a Maven publication that specifies dependencies on
`barmodule` and the `someSubProject` Gradle sub project. The resulting POM file
has two `dependency` entries, one for each dependency. Each project can declare
its dependencies on other docker images and publish an artifact advertising
those dependencies.
### Generating docker-compose.yml files from dependencies
The `com.palantir.docker-compose` plugin uses the transitive dependencies of the
`docker` configuration to populate a `docker-compose.yml.template` file with the
image versions specified by this project and all its transitive dependencies.
The plugin uses standard Maven/Ivy machanism for declaring and resolving
dependencies.
The `generateDockerCompose` task generates a `docker-compose.yml` file from a
user-defined template by replacing each version variable by the concrete version
declared by the transitive dependencies of the docker configuration. The task
performs two operations: First, it generates a mapping `group:name --> version`
from the dependencies of the `docker` configuration (see above). Second, it
replaces all occurrences of version variables of the form `{{group:name}}` in
the `docker-compose.yml.template` file by the resolved versions and writes the
resulting file as `docker-compose.yml`.
The `docker-compose` plugin also provides a `dockerComposeUp` task that starts
the docker images specified in the `dockerComposeFile` in detached mode.
You can also use the `dockerComposeDown` task to stop the containers.
**Example**
Assume a `docker-compose.yml.template` as follows:
```yaml
myservice:
image: 'repository/myservice:latest'
otherservice:
image: 'repository/otherservice:{{othergroup:otherservice}}'
```
`build.gradle` declares a dependency on a docker image published as
'othergroup:otherservice' in version 0.1.2:
```gradle
plugins {
id 'com.palantir.docker-compose'
}
dependencies {
docker 'othergroup:otherservice:0.1.2'
}
```
The `generateDockerCompose` task creates a `docker-compose.yml` as follows:
```yaml
myservice:
image: 'repository/myservice:latest'
otherservice:
image: 'repository/otherservice:0.1.2'
```
The `generateDockerCompose` task fails if the template file contains variables
that cannot get resolved using the provided `docker` dependencies. Version
conflicts between transitive dependencies of the same artifact are handled with
the standard Gradle semantics: each artifact is resolved to the highest declared
version.
**Configuring file locations**
The template and generated file locations are customizable through the
`dockerCompose` extension:
```gradle
dockerCompose {
template 'my-template.yml'
dockerComposeFile 'my-docker-compose.yml'
}
```
Docker Run Plugin
-----------------
Apply the plugin using standard gradle convention:
```gradle
plugins {
id 'com.palantir.docker-run' version ''
}
```
Use the `dockerRun` configuration block to configure the name, image and optional
command to execute for the `dockerRun` tasks:
```gradle
dockerRun {
name 'my-container'
image 'busybox'
volumes 'hostvolume': '/containervolume'
ports '7080:5000'
daemonize true
env 'MYVAR1': 'MYVALUE1', 'MYVAR2': 'MYVALUE2'
command 'sleep', '100'
arguments '--hostname=custom', '-P'
}
```
**Docker Run Configuration Parameters**
- `name` the name to use for this container, may include a tag.
- `image` the name of the image to use.
- `volumes` optional map of volumes to mount in the container. The key is the path
to the host volume, resolved using [`project.file()`](https://docs.gradle.org/current/userguide/working_with_files.html#sec:locating_files).
The value is the exposed container volume path.
- `ports` optional mapping `local:container` of local port to container port.
- `env` optional map of environment variables to supply to the running container.
These must be exposed in the Dockerfile with `ENV` instructions.
- `daemonize` defaults to true to daemonize the container after starting. However
if your container runs a command and exits, you can set this to false.
- `ignoreExitValue` (optional) to ignore the exit code returned from the execution of the docker command; defaults to `false`
- `clean` (optional) a boolean argument which adds `--rm` to the `docker run`
command to ensure that containers are cleaned up after running; defaults to `false`
- `command` the command to run.
- `arguments` additional arguments to be passed into the docker run command.
Please see https://docs.docker.com/engine/reference/run/ for possible values.
Tasks
-----
* **Docker**
* `docker`: build a docker image with the specified name and Dockerfile
* `dockerTag`: tag the docker image with all specified tags
* `dockerTag`: tag the docker image with ``
* `dockerPush`: push the specified image to a docker repository
* `dockerPush`: push the `` docker image to a docker repository
* `dockerTagsPush`: push all tagged docker images to a docker repository
* `dockerPrepare`: prepare to build a docker image by copying
dependent task outputs, referenced files, and `dockerfile` into a temporary
directory
* `dockerClean`: remove temporary directory associated with the docker build
* `dockerfileZip`: builds a ZIP file containing the configured Dockerfile
* **Docker Compose**
* `generateDockerCompose`: Populates a docker-compose file template with image
versions declared by dependencies
* `dockerComposeUp`: Brings up services defined in `dockerComposeFile` in
detacted state
* `dockerComposeDown`: Stops services defined in `dockerComposeFile`
* **Docker Run**
* `dockerRun`: run the specified image with the specified name
* `dockerStop`: stop the running container
* `dockerRunStatus`: indicate the run status of the container
* `dockerRemoveContainer`: remove the container
License
-------
This plugin is made available under the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0).
Contributing
------------
Contributions to this project must follow the [contribution guide](CONTRIBUTING.md).