compose.md
148 lines
| 3.5 KiB
| text/x-minidsrc
|
MarkdownLexer
cin
|
r14 | # Compose project | ||
| ## NAME | ||||
| `org.implab.gradle-container-compose` - docker compose project. | ||||
| ## SYNOPSIS | ||||
| ```gradle | ||||
| plugins { | ||||
| id "org.implab.gradle-container-compose" | ||||
| } | ||||
| dependencies { | ||||
| composeImages project(":images:foo") { | ||||
| ext { | ||||
| // imageName from :images:foo will be written to .env as FOO_IMAGE var | ||||
| composeVar = "FOO_IMAGE" | ||||
| } | ||||
| } | ||||
| } | ||||
| writeEnv { | ||||
| // write additional variables to .env | ||||
| env "DEBUG_JAVA" put "yes" | ||||
| // set compose name, this variable is set to that value by default | ||||
| env "COMPOSE_PROJECT_NAME" put project.group | ||||
| } | ||||
| // base container extension | ||||
| container { | ||||
| cliCmd = "podman" | ||||
| } | ||||
| // compose parameters | ||||
| compose { | ||||
| // add compose profiles | ||||
| profiles.add("dev") | ||||
| // set compose file name | ||||
| // defaults to compose.yaml | ||||
| composeFileName = "docker-compose.yaml" | ||||
| } | ||||
| ``` | ||||
| ## DESCRIPTION | ||||
| This plugin creates a set of conventional tasks to prepare and start compose | ||||
| project. This can be used to create and run sandbox. | ||||
| These tasks are: | ||||
| * `build` - prepares the context for the compose file, depends on `processResources` | ||||
| and `writeEnv` tasks. | ||||
| * `up` - invokes `compose up -d` in the built context and starts up the project | ||||
| in the background. | ||||
| * `stop` - invokes `compose stop` and stops the projects. | ||||
| * `rm` - invokes `compose rm` and removes containers, by default temporary volumes | ||||
| are removed with containers. | ||||
| * `clean` - cleanups the build directory and removes built context. | ||||
| Special configuration `composeImages` should be used to add a dependencies to the | ||||
| images needed by this project. The dependencies must provide a single artifact | ||||
| a json file containing `tag` property. This configuration well be resolved and | ||||
| tag for each dependency will be stored in the environment variable specified with | ||||
| `composeVar` property. | ||||
| ```gradle | ||||
| configuration { | ||||
| composeImages file("nginx.json") { | ||||
| ext { | ||||
| composeVar = "NGINX_IMAGE" | ||||
| } | ||||
| } | ||||
| composeImage project(":images:foo") { | ||||
| ext { | ||||
| composeVar = "FOO_IMAGE" | ||||
| } | ||||
| } | ||||
| } | ||||
| ``` | ||||
| The compose environment variables are written to the `.env` file inside the | ||||
| context directory and will be used by `compose up` command. | ||||
| ## Tasks | ||||
| ### writeEnv | ||||
| `type: WriteEnv, dependsOn: [configurations.composeImages, processResources]` | ||||
| Inspects configuration `composeImages`, adds default `COMPOSE_PROJECT_NAME` | ||||
| variable and writes `.env` file to the context directory. | ||||
| This task provides a property `environment` of type `MapProperty<String, String>` | ||||
| which can be used to customize the compose environment. | ||||
| ```gradle | ||||
| writeEnv { | ||||
| // direct environment property access | ||||
| environment.put("VAR_1", valueOrProvider) | ||||
| // syntax sugar to modify environment property | ||||
| env "VAR_2" put "value" // simple value | ||||
| env "VAR_3" put provider { getSomeValue() } // provider | ||||
| // map provider will be merged into the | ||||
| env { | ||||
| VAR_4 = "val1" | ||||
| VAR_5 = getAnotherValue() | ||||
| } | ||||
| } | ||||
| ``` | ||||
| ### processResources | ||||
| `type: Copy` | ||||
| Copies resources from the source directory `src/main` into the context directory `build/context` | ||||
| ### up | ||||
| `type: ComposeUp, dependsOn: [buildTask]` | ||||
| Starts the compose project. The project is started in the background. | ||||
| ### build | ||||
| `type: DefaultTask, dependsOn: [writeEnvTask]` | ||||
| This is a meta task used to group the set of tasks related to the build target. | ||||
| ### stop | ||||
| `type: ComposeStop` | ||||
| Stops the current compose project. | ||||
| ### rm | ||||
| `type: ComposeRm` | ||||
| Removes containers created from this compose project. | ||||
| `removeValues` - boolean property, if set to true the task will remove all | ||||
| temporary volumes left from containers. | ||||