# 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.