implab/gradle-container-plugin Commit - r14:ab28d6aa054e

More documentation, TagImage task supports multiple tags, set COMPOSE_PROJECT_NAME to project.group by default

cin -

r14:ab28d6aa054e v1.2.1 default

parent child

Context file:

r14:ab28d6aa054e

Collapse all files

bundle.md created 644 +57 0

@@ -0,0 +1,57
	1	# Creating bundle from images
	2
	3	## NAME
	4
	5	Save set of images to the single archive.
	6
	7	## SYNOPSIS
	8
	9	```gradle
	10	plugins {
	11	// task types and base extension
	12	id "org.implab.gradle-container-base"
	13	}
	14
	15	container {
	16	cliCmd = "podman"
	17	}
	18
	19	// create configuration
	20	configurations {
	21	bundleImages {
	22	canBeResolved = true
	23	canBeConsumed = false
	24	}
	25	}
	26
	27	// add dependencies to the project
	28	dependencies {
	29	bundleImages project(":images:foo"), project(":images:bar")
	30	}
	31
	32	// create task to export bundle
	33	task bundle(type: SaveImage) {
	34	// add image refs from artifacts
	35	imageRefs configurations.bundleImages
	36
	37	// add image name
	38	exportImages.add "nginx:latest"
	39	}
	40	```
	41
	42	## DESCRIPTION
	43
	44	To create an archive with images the task of type `SaveImage` can be used. This
	45	task has the following properties:
	46
	47	\| Property \| Description \|
	48	\|-\|-\|
	49	\| `archiveFileName` \| The file name of the bundle archive, defaults to `{archiveBaseName}-{archiveVersion}-{archiveClassifier}.{archiveExtension}`.\|
	50	\| `archiveBaseName` \| The base name of the archive, defaults to `{project.group}-{project.name}`. \|
	51	\| `archiveVersion` \| The archive version, defaults to `{project.version}`. \|
	52	\| `exportImages` \| A set of image names to include in the bundle. \|
	53
	54	\| Method \| Description \|
	55	\|-\|-\|
	56	\| `imageRefs(FileCollection)` \| Adds a set of files with image refs to add to the bundle. \|
	57	\| `imageRef(File)` \| Adds an image name from the file with image reference. \|

compose.md created 644 +148 0

@@ -0,0 +1,148
	1	# Compose project
	2
	3	## NAME
	4
	5	`org.implab.gradle-container-compose` - docker compose project.
	6
	7	## SYNOPSIS
	8
	9	```gradle
	10	plugins {
	11	id "org.implab.gradle-container-compose"
	12	}
	13
	14	dependencies {
	15	composeImages project(":images:foo") {
	16	ext {
	17	// imageName from :images:foo will be written to .env as FOO_IMAGE var
	18	composeVar = "FOO_IMAGE"
	19	}
	20	}
	21	}
	22
	23	writeEnv {
	24	// write additional variables to .env
	25	env "DEBUG_JAVA" put "yes"
	26
	27	// set compose name, this variable is set to that value by default
	28	env "COMPOSE_PROJECT_NAME" put project.group
	29	}
	30
	31	// base container extension
	32	container {
	33	cliCmd = "podman"
	34	}
	35
	36	// compose parameters
	37	compose {
	38	// add compose profiles
	39	profiles.add("dev")
	40
	41	// set compose file name
	42	// defaults to compose.yaml
	43	composeFileName = "docker-compose.yaml"
	44	}
	45
	46	```
	47
	48	## DESCRIPTION
	49
	50	This plugin creates a set of conventional tasks to prepare and start compose
	51	project. This can be used to create and run sandbox.
	52
	53	These tasks are:
	54
	55	* `build` - prepares the context for the compose file, depends on `processResources`
	56	and `writeEnv` tasks.
	57	* `up` - invokes `compose up -d` in the built context and starts up the project
	58	in the background.
	59	* `stop` - invokes `compose stop` and stops the projects.
	60	* `rm` - invokes `compose rm` and removes containers, by default temporary volumes
	61	are removed with containers.
	62	* `clean` - cleanups the build directory and removes built context.
	63
	64	Special configuration `composeImages` should be used to add a dependencies to the
	65	images needed by this project. The dependencies must provide a single artifact
	66	a json file containing `tag` property. This configuration well be resolved and
	67	tag for each dependency will be stored in the environment variable specified with
	68	`composeVar` property.
	69
	70	```gradle
	71	configuration {
	72	composeImages file("nginx.json") {
	73	ext {
	74	composeVar = "NGINX_IMAGE"
	75	}
	76	}
	77	composeImage project(":images:foo") {
	78	ext {
	79	composeVar = "FOO_IMAGE"
	80	}
	81	}
	82	}
	83	```
	84
	85	The compose environment variables are written to the `.env` file inside the
	86	context directory and will be used by `compose up` command.
	87
	88	## Tasks
	89
	90	### writeEnv
	91
	92	`type: WriteEnv, dependsOn: [configurations.composeImages, processResources]`
	93
	94	Inspects configuration `composeImages`, adds default `COMPOSE_PROJECT_NAME`
	95	variable and writes `.env` file to the context directory.
	96
	97	This task provides a property `environment` of type `MapProperty<String, String>`
	98	which can be used to customize the compose environment.
	99
	100	```gradle
	101	writeEnv {
	102	// direct environment property access
	103	environment.put("VAR_1", valueOrProvider)
	104
	105	// syntax sugar to modify environment property
	106	env "VAR_2" put "value" // simple value
	107	env "VAR_3" put provider { getSomeValue() } // provider
	108
	109	// map provider will be merged into the
	110	env {
	111	VAR_4 = "val1"
	112	VAR_5 = getAnotherValue()
	113	}
	114	}
	115	```
	116
	117	### processResources
	118
	119	`type: Copy`
	120
	121	Copies resources from the source directory `src/main` into the context directory `build/context`
	122
	123	### up
	124
	125	`type: ComposeUp, dependsOn: [buildTask]`
	126
	127	Starts the compose project. The project is started in the background.
	128
	129	### build
	130
	131	`type: DefaultTask, dependsOn: [writeEnvTask]`
	132
	133	This is a meta task used to group the set of tasks related to the build target.
	134
	135	### stop
	136
	137	`type: ComposeStop`
	138
	139	Stops the current compose project.
	140
	141	### rm
	142
	143	`type: ComposeRm`
	144
	145	Removes containers created from this compose project.
	146
	147	`removeValues` - boolean property, if set to true the task will remove all
	148	temporary volumes left from containers.

container/src/main/java/org/implab/gradle/containers/ComposePlugin.java +8 0

             package org.implab.gradle.containers;
             import java.io.IOException;
             import java.util.HashMap;
             import java.util.Map;
+            import java.util.Optional;
             import org.gradle.api.DefaultTask;
             import org.gradle.api.Plugin;
             import org.gradle.api.Project;
             import org.gradle.api.artifacts.Configuration;
             import org.gradle.api.artifacts.Configuration.State;
             import org.gradle.api.logging.Logger;
             import org.gradle.api.tasks.Copy;
             import org.gradle.api.tasks.Delete;
             import org.implab.gradle.containers.cli.Utils;
             import org.implab.gradle.containers.tasks.ComposeRm;
             import org.implab.gradle.containers.tasks.ComposeStop;
             import org.implab.gradle.containers.tasks.ComposeUp;
             import org.implab.gradle.containers.tasks.WriteEnv;
             public abstract class ComposePlugin implements Plugin<Project>, ProjectMixin {
                 public final String COMPOSE_IMAGES_CONFIGURATION = "composeImages";
+                public final String COMPOSE_PROJECT_NAME = "COMPOSE_PROJECT_NAME";
                 public final String COMPOSE_EXTENSION = "compose";
                 public final String COMPOSE_UP_TASK = "up";
                 public final String COMPOSE_STOP_TASK = "stop";
                 public final String COMPOSE_RM_TASK = "rm";
                 public final String CLEAN_TASK = "clean";
                 public final String BUILD_TASK = "build";
                 public final String PROCESS_RESOURCES_TASK = "processResources";
                 public final String WRITE_ENV_TASK = "writeEnv";
                 public final String COMPOSE_VAR = "composeVar";
                 public final String ENV_FILE_NAME = ".env";
                 public Logger getLogger() {
                     return getProject().getLogger();
                 }
                 @Override
                 public void apply(Project project) {
                     var containerImages = configuration(COMPOSE_IMAGES_CONFIGURATION, Configurations.RESOLVABLE);
                     // basic configuration, register extension
                     var basePlugin = plugin(ContainerBasePlugin.class);
                     var containerExtension = basePlugin.getContainerExtension();
                     var composeExtension = extension(COMPOSE_EXTENSION, ComposeExtension.class);
                     var composeFile = containerExtension.getContextDirectory()
                         .file(composeExtension.getComposeFileName());
                     var composeProfiles = composeExtension.getProfiles();
                     var cleanTask = task(CLEAN_TASK, Delete.class, t -> {
                         t.delete(containerExtension.getContextDirectory());
                     });
                     // copy task from src/main
                     var processResources = task(PROCESS_RESOURCES_TASK, Copy.class, t -> {
                         t.mustRunAfter(cleanTask);
                         t.from(projectDirectory().dir("src/main"));
                         t.into(containerExtension.getContextDirectory());
                     });
                     // write .env
                     var writeEnvTask = task(WRITE_ENV_TASK, WriteEnv.class, t -> {
                         t.dependsOn(processResources, containerImages);
                         t.getEnvFile().set(containerExtension.getContextDirectory().file(ENV_FILE_NAME));
+                        var group = project.getGroup();
+                        if (group != null && group.toString().length() > 0) {
+                            t.getEnvironment().put(COMPOSE_PROJECT_NAME, group.toString());
+                        }
                         t.getEnvironment().putAll(containerImages.map(this::extractComposeEnv));
                     });
                     var buildTask = task(BUILD_TASK, DefaultTask.class, t -> {
                         t.dependsOn(writeEnvTask);
                     });
                     var stopTask = task(COMPOSE_STOP_TASK, ComposeStop.class, t -> {
                         // stop must run after build
                         t.mustRunAfter(buildTask);
                         t.getProfiles().addAll(composeProfiles);
                         t.getComposeFile().set(composeFile);
                     });
                     var rmTask = task(COMPOSE_RM_TASK, ComposeRm.class, t -> {
                         // rm must run after build and stop
                         t.mustRunAfter(buildTask, stopTask);
                         t.getProfiles().addAll(composeProfiles);
                         t.getComposeFile().set(composeFile);
                     });
                     task(COMPOSE_UP_TASK, ComposeUp.class, t -> {
                         t.dependsOn(buildTask);
                         // up must run after stop and rm
                         t.mustRunAfter(stopTask, rmTask);
                         t.getProfiles().addAll(composeProfiles);
                         t.getComposeFile().set(composeFile);
                     });
                 }
                 /**
                  * Processed the configurations, extracts composeVar extra property from
                  * each dependency in this configuration and adds a value to the resulting
                  * map. The values in the nap will contain image tags.
                  */
                 private Map<String, String> extractComposeEnv(Configuration config) {
                     if (config.getState() != State.UNRESOLVED) {
                         getLogger().error("extractComposeEnv: The configuration {} isn't resolved.", config.getName());
                         throw new IllegalStateException("The specified configuration isn't resolved");
                     }
                     getLogger().info("extractComposeEnv {}", config.getName());
                     var map = new HashMap<String, String>();
                     for (var dependency : config.getDependencies()) {
                         // get extra composeVar if present
                         extra(dependency, COMPOSE_VAR, String.class).optional().ifPresent(varName -> {
                             // if we have a composeVar extra attribute on this dependency
                             // get files for the dependency
                             var files = config.files(dependency);
                             if (files.size() == 1) {
                                 // should bw exactly 1 file
                                 var file = files.stream().findAny().get();
                                 getLogger().info("Processing {}: {}", dependency, file);
                                 try {
                                     // try read imageRef
                                     Utils.readImageRef(file).getTag()
                                             .ifPresentOrElse(
                                                     tag -> map.put(varName, tag),
                                                     () -> getLogger().error("ImageRef doesn't have a tag: {}", file));
                                 } catch (IOException e) {
                                     getLogger().error("Failed to read ImageRef {}: {}", file, e);
                                 }
                             } else {
                                 getLogger().warn("Dependency {} must have exactly 1 file", dependency);
                             }
                         });
                     }
                     return map;
                 }
             }

container/src/main/java/org/implab/gradle/containers/cli/DockerTraits.java +1 -1

             package org.implab.gradle.containers.cli;
             import java.io.File;
             import java.io.IOException;
             import java.util.ArrayList;
             import java.util.Arrays;
             import java.util.List;
             import java.util.Optional;
             import java.util.Set;
             import org.gradle.api.logging.Logger;
             public abstract class DockerTraits {
                 public final String BUILD_COMMAND = "build";
                 public final String PUSH_COMMAND = "push";
                 public final String RUN_COMMAND = "run";
                 public final String SAVE_COMMAND = "save";
                 public final String INSPECT_COMMAND = "inspect";
                 public final String IMAGE_COMMAND = "image";
                 public final String TAG_COMMAND = "tag";
                 public final String COMPOSE_COMMAND = "compose";
                 public final String UP_COMMAND = "up";
                 public final String STOP_COMMAND = "stop";
                 public final String RM_COMMAND = "rm";
                 public abstract Logger getLogger();
                 public abstract Optional<File> getWorkingDir();
                 public abstract String getCliCmd();
                 Process startProcess(ProcessBuilder builder) throws IOException {
                     getLogger().info("Starting: {}", builder.command());
                     return builder.start();
                 }
                 protected boolean checkRetCode(Process proc, int code) throws InterruptedException {
                     if (getLogger().isInfoEnabled()) {
                         Utils.redirectIO(proc.getInputStream(), getLogger()::info);
                         Utils.redirectIO(proc.getErrorStream(), getLogger()::info);
                     }
                     return proc.waitFor() == code;
                 }
                 protected void complete(Process proc) throws InterruptedException, IOException {
                     if (getLogger().isInfoEnabled())
                         Utils.redirectIO(proc.getInputStream(), getLogger()::info);
                     if (getLogger().isErrorEnabled())
                         Utils.redirectIO(proc.getErrorStream(), getLogger()::error);
                     var code = proc.waitFor();
                     if (code != 0) {
                         getLogger().error("The process exited with code {}", code);
                         throw new IOException("The process exited with error code " + code);
                     }
                 }
                 protected ProcessBuilder builder(String... args) {
                     var argsList = new ArrayList<String>(args.length + 1);
                     Arrays.stream(args).forEach(argsList::add);
                     return builder(argsList);
                 }
                 protected ProcessBuilder builder(List<String> args) {
                     var command = new ArrayList<String>(args.size() + 1);
                     command.add(getCliCmd());
                     args.forEach(command::add);
                     var builder = new ProcessBuilder(command);
                     getWorkingDir().ifPresent(builder::directory);
                     return builder;
                 }
                 public void buildImage(String imageName, File contextDirectory, List<String> options)
                         throws IOException, InterruptedException {
                     var args = new ArrayList<String>();
                     args.add(BUILD_COMMAND);
                     args.addAll(options);
                     args.add("-t");
                     args.add(imageName);
                     args.add(contextDirectory.getAbsolutePath());
                     complete(startProcess(builder(args)));
                 }
                 public void pushImage(String image, List<String> options) throws InterruptedException, IOException {
                     var args = new ArrayList<String>();
                     args.add(PUSH_COMMAND);
                     args.addAll(options);
                     args.add(image);
                     complete(startProcess(builder(args)));
                 }
                 public void runImage(String image, List<String> options, List<String> command)
                         throws InterruptedException, IOException {
                     var args = new ArrayList<String>();
                     args.add(RUN_COMMAND);
                     args.addAll(options);
                     args.add(image);
                     args.addAll(command);
                     complete(startProcess(builder(args)));
                 }
-                public void saveImage(List<String> images, File output) throws InterruptedException, IOException {
+                public void saveImage(Set<String> images, File output) throws InterruptedException, IOException {
                     if (output.exists())
                         output.delete();
                     var args = new ArrayList<String>();
                     args.add(SAVE_COMMAND);
                     args.add("-o");
                     args.add(output.getAbsolutePath());
                     images.forEach(args::add);
                     complete(startProcess(builder(args)));
                 }
                 public void tagImage(String source, String target) throws InterruptedException, IOException {
                     complete(startProcess(builder(TAG_COMMAND, source, target)));
                 }
                 public boolean imageExists(String imageId) throws InterruptedException, IOException {
                     getLogger().info("Check image {} exists", imageId);
                     return checkRetCode(
                             startProcess(builder(IMAGE_COMMAND, INSPECT_COMMAND, "--format", "image-exists", imageId)),
 );
                 }
                 public boolean imageExists(File imageIdFile) {
                     if (imageIdFile.exists()) {
                         try {
                             var imageId = Utils.readImageRef(imageIdFile);
                             return imageExists(imageId.getId());
                         } catch (IOException | InterruptedException e) {
                             getLogger().error("Failed to read imageId {}: {}", imageIdFile, e);
                             return false;
                         }
                     }
                     return false;
                 }
                 List<String> composeArgs(File primaryCompose, Set<String> profiles, String... extra) {
                     var args = new ArrayList<String>();
                     args.add(COMPOSE_COMMAND);
                     args.add("--file");
                     args.add(primaryCompose.getAbsolutePath());
                     if (profiles.size() > 0) {
                         for (var profile : profiles) {
                             args.add("--profile");
                             args.add(profile);
                         }
                     }
                     args.addAll(List.of(extra));
                     return args;
                 }
                 public void composeUp(File primaryCompose, Set<String> profiles) throws InterruptedException, IOException {
                     var args = composeArgs(primaryCompose, profiles, UP_COMMAND, "--detach");
                     complete(startProcess(builder(args)));
                 }
                 public void composeStop(File primaryCompose, Set<String> profiles) throws InterruptedException, IOException {
                     var args = composeArgs(primaryCompose, profiles, STOP_COMMAND);
                     complete(startProcess(builder(args)));
                 }
                 public void composeRm(File primaryCompose, Set<String> profiles, boolean removeVolumes)
                         throws InterruptedException, IOException {
                     var args = composeArgs(primaryCompose, profiles, RM_COMMAND, "--force", "--stop");
                     if (removeVolumes)
                         args.add("--volumes");
                     complete(startProcess(builder(args)));
                 }
             }

container/src/main/java/org/implab/gradle/containers/tasks/SaveImage.java +2 -2

             package org.implab.gradle.containers.tasks;
             import java.io.File;
             import java.io.IOException;
             import java.util.ArrayList;
             import java.util.Optional;
             import org.gradle.api.file.DirectoryProperty;
             import org.gradle.api.file.FileCollection;
             import org.gradle.api.file.RegularFile;
-            import org.gradle.api.provider.ListProperty;
             import org.gradle.api.provider.Property;
             import org.gradle.api.provider.Provider;
+            import org.gradle.api.provider.SetProperty;
             import org.gradle.api.tasks.Input;
             import org.gradle.api.tasks.Internal;
             import org.gradle.api.tasks.OutputFile;
             import org.gradle.api.tasks.TaskAction;
             import org.gradle.api.tasks.TaskExecutionException;
             import org.implab.gradle.containers.cli.Utils;
             public abstract class SaveImage extends DockerCliTask {
                 @Input
-                public abstract ListProperty<String> getExportImages();
+                public abstract SetProperty<String> getExportImages();
                 @OutputFile
                 public Provider<RegularFile> getArchiveFile() {
                     return getDestinationDirectory().file(getArchiveFileName());
                 }
                 @Internal
                 public abstract DirectoryProperty getDestinationDirectory();
                 @Internal
                 public abstract Property<String> getArchiveFileName();
                 @Internal
                 public abstract Property<String> getArchiveBaseName();
                 @Internal
                 public abstract Property<String> getArchiveVersion();
                 @Internal
                 public abstract Property<String> getArchiveClassifier();
                 @Internal
                 public abstract Property<String> getArchiveExtension();
                 String readImageRefTag(File file) throws Exception {
                     getLogger().info("Reading image ref from {}", file);
                     var imageRef = Utils.readImageRef(file);
                     return imageRef.getTag().orElseThrow(() -> new Exception("The image tag is required to save image"));
                 }
                 public void imageRef(File file) {
                     getExportImages().add(provider(() -> {
                         return readImageRefTag(file);
                     }));
                 }
                 public void imageRefs(FileCollection files) {
                     dependsOn(files);
                     getExportImages().addAll(provider(() -> {
                         var tags = new ArrayList<String>();
                         for (File file : files) {
                             tags.add(readImageRefTag(file));
                         }
                         return tags;
                     }));
                 }
                 public SaveImage() {
                     getArchiveFileName().convention(provider(this::conventionalArchiveFileName));
                     getArchiveBaseName().convention(provider(this::conventionalArchiveBaseName));
                     getArchiveVersion().convention(provider(() -> getProject().getVersion()).map(x -> x.toString()));
                     getDestinationDirectory().convention(getProject().getLayout().getBuildDirectory());
                     getArchiveExtension().convention("tar");
                 }
                 private String conventionalArchiveBaseName() {
                     ArrayList<String> parts = new ArrayList<>();
                     Optional.of(getProject().getGroup()).map(x -> x.toString()).ifPresent(parts::add);
                     parts.add(getProject().getName());
                     return String.join("-", parts);
                 }
                 private String conventionalArchiveFileName() {
                     ArrayList<String> parts = new ArrayList<>();
                     if (getArchiveBaseName().isPresent())
                         parts.add(getArchiveBaseName().get());
                     if (getArchiveVersion().isPresent())
                         parts.add(getArchiveVersion().get());
                     if (getArchiveClassifier().isPresent())
                         parts.add(getArchiveClassifier().get());
                     if (parts.size() == 0)
                         throw new TaskExecutionException(this, new Exception("The archiveFileName ism't specified"));
                     return String.join("-", parts) + "." + getArchiveExtension().get();
                 }
                 @TaskAction
                 public void run() throws InterruptedException, IOException {
                     docker().saveImage(
                             getExportImages().get(),
                             getArchiveFile().map(RegularFile::getAsFile).get());
                 }
             }

container/src/main/java/org/implab/gradle/containers/tasks/TagImage.java +28 -3

@@ -1,21 +1,46
1	package org.implab.gradle.containers.tasks;	1	package org.implab.gradle.containers.tasks;
2		2
3	import java.io.IOException;	3	import java.io.IOException;
		4	import java.util.HashSet;
		5	import java.util.Set;
		6
4	import org.gradle.api.provider.Property;	7	import org.gradle.api.provider.Property;
		8	import org.gradle.api.provider.SetProperty;
5	import org.gradle.api.tasks.Input;	9	import org.gradle.api.tasks.Input;
6	import org.gradle.api.tasks.TaskAction;	10	import org.gradle.api.tasks.TaskAction;
7		11
8	public abstract class TagImage extends DockerCliTask {	12	public abstract class TagImage extends DockerCliTask {
9	@Input	13	@Input
10	public abstract Property<String> getSrcImage();	14	public abstract Property<String> getSrcImage();
11		15
12	@Input	16	@Input
		17	public abstract SetProperty<String> getTags();
		18
		19	@Input
		20	@Deprecated
13	public abstract Property<String> getDestImage();	21	public abstract Property<String> getDestImage();
14		22
		23	private Set<String> getImageTags() {
		24	var tags = new HashSet<>(getTags().get());
		25	tags.add(getDestImage().get());
		26	return tags;
		27	}
		28
		29	public TagImage() {
		30	this.setOnlyIf("No tags were specified", self -> getImageTags().size() > 0);
		31	}
		32
15	@TaskAction	33	@TaskAction
16	public void run() throws InterruptedException, IOException {	34	public void run() throws InterruptedException, IOException {
17	~~docker~~().~~tagImage~~(	35	var tags = getImageTags();
18	getSrcImage().get(),	36	var src = getSrcImage().get();
19	getDestImage().get());	37
		38	if (tags.size() == 0)
		39	getLogger().info("No tags were specified");
		40
		41	for (var tag : tags) {
		42	getLogger().info("Tag: {}", tag);
		43	docker().tagImage(src, tag);
20	}	44	}
21	}	45	}
		46	}

readme.md +119 -9

             # Build and publish images with docker/podman
             ## SYNOPSIS
             ```gradle
             plugins {
-                id 'org.implab.gradle-container' version '1.1'
+                id 'org.implab.gradle-container'
             }
             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
-            building process is deligated to the `Dockerfile` which will run
+            building process is delegated to the `Dockerfile` which will run
-            in the prepeared build context.
+            in the prepared build context.
-            ### Project structure
+            ## Project structure
-            * `build/`
+            * `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.
             * `src`
               * `main` - the source files which will be copied to the build context.
-            ## Properties
+            ## Global properties
+            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.
             `imagesAuthority` - the registry where the image should be published.
             for example `docker.io`
             `imagesGroup` - the path to the image in the repository.
+            `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
+            ```
             ## Tasks
+            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` |
             ### buildImage
+            `type: BuildImage`
             The task builds the image. Wrapper around the `docker build` command.
+            | 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.
             ### saveImage
+            `type: SaveImage`
             The task exports image as the .tar archive.
+            | 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. |
             ### pushImage
-            The task pushes the image to the remote repository.
+            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"
+            }
+            ```
             ### processResources
-            The copy task, it prepares the build context. Use it to customize
+            The copy task, it prepares the build context. Use this task to customize
             the build context.
             ### tagImage
+            `type: TagImage`
             since: 1.1
             ```gradle
             task tagLatest(type: TagImage) {
+                pushImage.dependsOn it
                 srcImage = container.imageName
-                destImage = container.imageName.map { it.tag("latest") }
+                tags.add(container.imageName.map { it.tag("latest") })
             }
             ```
+            | 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
             ## Changes
+            ### 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.
             ### 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.

General Comments 0

Write
Preview

You need to be logged in to leave comments. Login now

No TODOs yet

	Site-wide shortcuts
/	Use quick search box
g h	Goto home page
g g	Goto my private gists page
g G	Goto my public gists page
g 0-9	Goto bookmarked items from 0-9
n r	New repository page
n g	New gist page

	Repositories
g s	Goto summary page
g c	Goto changelog page
g f	Goto files page
g F	Goto files page with file search activated
g p	Goto pull requests page
g o	Goto repository settings
g O	Goto repository access permissions settings
t s	Toggle sidebar on some pages