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

Данная конфигурация подходит если проект использует окружение 
node.js и пакетный менеджер npm. В этом случае проект может быть 
написан на таких языках как JavaScript или TypeScript. 
Данная конфигурация предназначена для серверных приложений. 
Для браузерных приложений см. [Node.JS Browser](https://docs.amvera.ru/books/amvera/page/nodejs-browser).

#### Секция meta

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

```
meta:
  environment: node
  toolchain:
    name: npm
    version: 18
```

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

Как для фазы сборки, так и для фазы запуска используется образ
 `node:${meta.toolchain.version}`. Так как для обеих фаз используется 
один и тот же образ, `meta.toolchain.version` может быть любым 
тегом этого образа на [докер хабе](https://hub.docker.com/_/node/tags).

#### Секция build

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

 - `skip`
 - `additionalCommands`
 - `artifacts`

Параметр `skip` может использоваться если у проекта нет зависимостей 
и/или отсутствует файл `package.json`. Указание `skip: yes` будет означать,
что фаза сборки будет целиком пропущена.

Во время сборки скрипт выполняет команду `npm install`. 
Если нужно выполнить дополнительные команды (например, `npm run build`), 
используется параметр `additionalCommands`:

```
build:
  additionalCommands: npm run build
```

В этом случае во время сборки будет выполнена команда `npm install && npm run build`.

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

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

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

```
build:
  artifacts:
    "*": /
```

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

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

Секция `run` может содержать следующие параметры:

 - `scriptName`
 - `scriptArguments`
 - `nodeArguments`
 - `command`
 - `persistenceMount`
 - `persistenceMount`

Параметр `scriptName` является обязательным.

Для запуска используется команда `node ${run.nodeArguments} ${run.scriptName} ${run.scriptArguments}`.

Параметр `scriptName` это путь до скрипта, который нужно запустить, относительно 
корня репозитория.

```
run:
  scriptName: index.js
```

Если нужно передать дополнительные аргументы `node` для запуска, их нужно указать в параметре `nodeArguments`.

Если нужно передать дополнительные аргументы сприкту для запуска, их нужно 
указать в параметре `scriptArguments`.

Параметр `command` это альтернативный способ запустить приложение. 
При использовании этого параметра игнорируются параметры `scriptName`, 
`scriptArguments` и `nodeArguments`. Он должен содержать полную команду запуска:

```
run:
  command: npm run start
```

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

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

### Рецепты

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

```
meta:
  environment: node
  toolchain:
    name: npm
    version: 18

run:
  scriptName: index.js
```

#### Приложение на Express.JS

```
meta:
  environment: node
  toolchain:
    name: npm
    version: 18

run:
  scriptName: index.js
  containerPort: 3000
```

#### Приложение с фазой сборки (Webpack, tsc и т.п.)

Данный файл предполагает, что скрипт запуска сборки прописан в задаче `build`, 
а также скрипт запуска приложения прописан в задаче `start` в файле `package.json`

```
meta:
  environment: node
  toolchain:
    name: npm
    version: 18

build:
  additionalCommands: npm run build

run:
  command: npm run start
  containerPort: 3000
```

Данная конфигурация подходит если проект использует окружение node.js 
и пакетный менеджер npm для сборки приложения для работы в браузере. 
В этом случае проект может быть написан на таких языках как JavaScript или TypeScript. 
Данная конфигурация предназначена для браузерных приложений. 
Для серверных приложений см. 
[Node.JS Server](https://docs.amvera.ru/books/amvera/page/nodejs-server).

#### Секция meta

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

```
meta:
  environment: node
  toolchain:
    name: browser
    version: 18
```

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

Для фазы сборки используется образ `node:${meta.toolchain.version}`. 
Так как для фазы запуска node.js вообще не используется,
 `meta.toolchain.version` может быть любым тегом этого образа на [докер хабе](https://hub.docker.com/_/node/tags).

#### Секция build

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

 - `additionalCommands`
 - `artifacts`

Во время сборки скрипт выполняет команду `npm install && npm run build`. 
Если будет задан параметр `additionalCommands`, то будет выполнена команда 
`npm install && ${build.additionalCommands}`. Это может пригодиться, 
если в проекте команда сборки называется не `build`.

```
build:
  additionalCommands: npm run amvera:build
```

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

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

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

```
build:
  artifacts:
    "build/*": /
```

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

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

#### Секция run

Для запуска используется модифицированный образ `nginx:1.23.2` для 
поддержки маршрутизации в SPA приложениях.

В секции `run` нет настраиваемых параметров.

### Рецепты

#### React

```
meta:
  environment: node
  toolchain:
    name: browser
    version: 18
```

#### Vue

```
meta:
  environment: node
  toolchain:
    name: browser
    version: 18

build:
  artifacts:
    "dist/*": /
```

#### Angular

```
meta:
  environment: node
  toolchain:
    name: browser
    version: 18

build:
  artifacts:
    "dist/my-app/*": /
```