Документация по развертыванию приложений на JVM

Данная конфигурация подходит, если проект собирается при помощи 
Gradle и запускается на JVM. В этом случае проект может быть написан
на таких языках как Java или Kotlin.

#### Секция meta

Секция `meta` файла `amvera.yml` будет выглядеть следующим образом:

```
meta:
  environment: jvm
  toolchain:
    name: gradle
    version: 17
```

Из параметров, которые можно здесь менять это `meta.toolchain.version`. 
Логически это версия JDK, который нужно использовать для сборки. 
Технически значение `version` подставляется в имя образа Docker, 
который будет использован.

Для фазы сборки это `gradle:jdk${meta.toolchain.version}`. 
Допустимые значения можно увидеть на странице [докер хаба](https://hub.docker.com/_/gradle/tags?page=1&name=jdk).

Для фазы запуска это `bellsoft/liberica-openjre-debian:${meta.toolchain.version}`. 
Допустимые значения можно увидеть на странице [докер хаба](https://hub.docker.com/r/bellsoft/liberica-openjre-debian/tags).

> ##### Важно
>
> Значение `meta.toolchain.version` должно быть допустимым как для фазы сборки, 
так и для фазы запуска. Лучше всего подходит простой номер LTS версии JDK.

#### Секция build

В секции `build` могут быть указаны следующие параметры:

 - `image`
 - `args`
 - `artifacts`

Параметр `image` позволяет использовать другой образ для сборки, а не тот, который предлагается Amvera. Образ должен удовлетворять следующим требованиям:

 - исходный код для сборки ожидается в папке /app (или образу без разницы, где будет находиться исходный код);
 - в образе присутствует команда `gradle`, которую можно вызвать по имени 
(без указания абсолютного пути) с параметром `build`.

Параметр `args` позволяет указать дополнительные параметры команде 
`gradle build ${build.args}`. Например, чтобы задать свойство `server.port`:

```
build:
  args: -Dserver.port=80
```

В этом случае для сборки будет выполнена команда `gradle build -Dserver.port=80`.

Параметр `artifacts` позволяет указать какие файлы должны попасть 
в итоговое приложение. По умолчанию будут скопированы все файлы 
с расширением `jar` из папки `build/libs` в корень папки приложения.

Параметр `artifacts` в отличие от других параметров это не строка, а словарь. 
Ключ в нем это маска файлов источника копирования, а значение: папка, 
в которую будут скопированы файлы.

Так, значение `artifacts` по умолчанию:

```
build:
  artifacts:
    "build/libs/*.jar": /
```

Мы используем следующие правила копирования:

 - в качестве источника указываются только относительные пути (без / в начале);
 - если под маску попал файл, файл будет скопирован в папку назначения 
без исходного пути;
 - если под маску попала папка, она будет скопирована целиком в папку 
назначения вместе со всем содержимым.

#### Секция run

В сети `run` могут быть использованы следующие параметры:

 - `jarName`
 - `image`
 - `persistenceMount`
 - `containerPort`

Параметр `jarName` является обязательным. Он указывает путь до файла 
с расширением `jar`, который нужно запустить командой `java -jar ${run.jarName}`. 
Пример:

```
run:
  jarName: bin/bag-end.jar
```

Параметр `image` позволяет использовать другой образ для сборки, а не тот, 
который предлагается Amvera. Образ должен удовлетворять следующим 
требованиям:

 - результат сборки ожидается в папке /app (или образу без разницы, 
где будет находиться результат сборки);
 - в образе присутствует команда `java`, которую можно вызвать по имени 
(без указания абсолютного пути) с параметрами `-jar имя_образа`.

Параметр `persistenceMount` позволяет указать, в какую директорию будет 
примонтирована папка с постоянным хранилищем. 
По умолчанию имеет значение `/data`.

Параметр `containerPort` позволяет указать какой порт слушает приложение. 
По умолчанию имеет значение `80`.

### Рецепты

#### Минимальный файл amvera.yml

```
meta:
  environment: jvm
  toolchain:
    name: gradle
    version: 17

run:
  jarName: bag-end.jar
```

#### Spring Boot

```
meta:
  environment: jvm
  toolchain:
    name: gradle
    version: 17

run:
  jarName: bag-end-1.0.0.jar
  containerPort: 8080
```

Данная конфигурация подходит, если проект собирается при помощи Maven 
и запускается на JVM. В этом случае проект может быть написан на таких языках 
как Java или Kotlin.

#### Секция meta

Секция `meta` файла `amvera.yml` будет выглядеть следующим образом:

```
meta:
  environment: jvm
  toolchain:
    name: maven
    version: 17
```

Из параметров, которые можно здесь менять это `meta.toolchain.version`. 
Логически это версия JDK, который нужно использовать для сборки. 
Технически значение `version` подставляется в имя образа Docker, 
который будет использован.

Для фазы сборки это `maven:3-openjdk-${meta.toolchain.version}`. 
Допустимые значения можно увидеть на странице [докер хаба](https://hub.docker.com/_/maven/tags?page=1&name=3-openjdk).

Для фазы запуска это `bellsoft/liberica-openjre-debian:${meta.toolchain.version}`. 
Допустимые значения можно увидеть на странице [докер хаба](https://hub.docker.com/r/bellsoft/liberica-openjre-debian/tags).

> ##### Важно
>
> Значение `meta.toolchain.version` должно быть допустимым как для фазы сборки, 
так и для фазы запуска. Лучше всего подходит простой номер LTS версии JDK.

#### Секция build

В секции `build` могут быть указаны следующие параметры:

 - `image`
 - `args`
 - `artifacts`

Параметр `image` позволяет использовать другой образ для сборки, а не тот, который предлагается Amvera. Образ должен удовлетворять следующим требованиям:

 - исходный код для сборки ожидается в папке /app (или образу без разницы, где будет находиться исходный код);
 - в образе присутствует команда `mvn`, которую можно вызвать по имени (без указания абсолютного пути) с параметрами `clean package`.

Параметр `args` позволяет указать дополнительные параметры команде `mvn clean package ${build.args}`. Например, если в проекте используется Spring Boot, может потребоваться следующий параметр:

```
build:
  args: spring-boot:repackage
```

В этом случае для сборки будет выполнена команда `mvn clean package spring-boot:repackage`.

Указывать можно несколько параметров, все они будут подставлены в команду. 
Например, если нужно указать еще и профиль мавен:

```
build:
  args: spring-boot:repackage -Pproduction
```

Параметр `artifacts` позволяет указать какие файлы должны попасть в итоговое приложение. 
По умолчанию будут скопированы все файлы с расширением `jar` из папки `target` в 
корень папки приложения.

Параметр `artifacts` в отличие от других параметров это не строка, а словарь. 
Ключ в нем это маска файлов источника копирования, а значение: папка, 
в которую будут скопированы файлы.

Так, значение `artifacts` по умолчанию:

```
build:
  artifacts:
    "target/*.jar": /
```

Мы используем следующие правила копирования:

 - в качестве источника указываются только относительные пути (без / в начале);
 - если под маску попал файл, файл будет скопирован в папку назначения без 
исходного пути;
 - если под маску попала папка, она будет скопирована целиком в папку назначения 
вместе со всем содержимым.

#### Секция run

В секции `run` могут быть использованы следующие параметры:

 - `jarName`
 - `image`
 - `persistenceMount`
 - `containerPort`

Параметр `jarName` является обязательным. Он указывает путь до файла с 
расширением `jar`, который нужно запустить командой `java -jar ${run.jarName}`. 
Пример:

```
run:
  jarName: bin/bag-end.jar
```

Параметр `image` позволяет использовать другой образ для сборки, а не тот, который предлагается Amvera. Образ должен удовлетворять следующим требованиям:

 - результат сборки ожидается в папке /app (или образу без разницы, где будет находиться результат сборки);
 - в образе присутствует команда `java`, которую можно вызвать по имени (без указания абсолютного пути) с параметрами `-jar имя_файла`.

Параметр `persistenceMount` позволяет указать, в какую директорию будет 
примонтирована папка с постоянным хранилищем. По умолчанию имеет значение `/data`.

Параметр `containerPort` позволяет указать какой порт слушает приложение. 
По умолчанию имеет значение `80`.

### Рецепты

#### Минимальный файл amvera.yml

```
meta:
  environment: jvm
  toolchain:
    name: maven
    version: 17

run:
  jarName: bag-end.jar
```

#### Spring Boot

```
meta:
  environment: jvm
  toolchain:
    name: maven
    version: 17

build:
  args: spring-boot:repackage -Pproduction

run:
  jarName: bag-end-1.0.0.jar
  containerPort: 8080
```