# Python Pip

Данная конфигурация подходит, если проект написан на языке Python и либо не имеет зависимостей, либо они прописаны в файле `requirements.txt`.

Создать yml-файл можно в интерфейсе, воспользоваться нашим генератором yaml, перейдя по [ссылке](https://manifest.amvera.ru/), либо самостоятельно, используя инструкции ниже.

Инструкция по заполнению конфигурации через интерфейс находится во второй половине данной статьи.

## Конфигурационный файл

### Секция meta

В секции мета задается версия Python, которую вы используете.

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

``` yaml
meta:
  environment: python
  toolchain:
    name: pip
    version: 3.10
```

Как для сборки, так и для запуска используется образ Docker `python:${meta.toolchain.version}`. Параметр `meta.toolchain.version` 
необязательный. Если его не указать, будет использоваться образ `python:3`.

Так как значение параметра `meta.toolchain.version` является тегом образа python, можно в качестве его значения использовать 
произвольный тег на [докер-хабе](https://hub.docker.com/_/python/tags). Однако из-за того, что мы вызываем интерпретатор как `python3`, а также пользуемся 
модулем `venv` в команде `python3 -m venv`, образ Python должен поддерживать эти возможности.

### Секция build

В секции build указывается имя файла с зависимостями (библиотеками, которые система должна установить через pip).

В секции `build` может быть указан один необязательный параметр: `requirementsPath`. Он определяет путь до файла 
`requirements.txt` относительно корня репозитория. Если этот параметр не задан, он по умолчанию равен `requirements.txt`.

Если, например, этот файл находится в папке build, то значение этого параметра необходимо указать следующим образом:

``` yaml
build:
  requirementsPath: build/requirements.txt
```

Если в проекте вообще не используется файл `requirements.txt` или скрипт сборки не сможет его обнаружить по указанному 
пути, то фаза установки зависимостей будет пропущена.

### Секция run

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

 - `scriptName`
 - `command`
 - `persistenceMount`
 - `containerPort`

Параметры `scriptName` и `command` взаимоисключающие. Один из них должен быть указан для успешного запуска приложения.

Параметр `scriptName` указывает путь до файла с расширением `py`. Он используется в команде `python3 ${run.scriptName}`:

``` yaml
run:
  scriptName: app.py
```

В случае, если запуск осуществляется другой командой, например, `gunicorn`, то можно использовать параметр `command`:

``` yaml
run:
  command: gunicorn --bind 0.0.0.0:80 app:app
```

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

Постоянное хранилище и папка data в репозитории, это разные директории. Рекомендуется использовать именно постоянное хранилище.

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

### Рецепты

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

``` yaml
meta:
  environment: python
  toolchain:
    name: pip
    version: 3.10

run:
  scriptName: app.py
```

#### WSGI-приложение (напр., приложение на Flask)

Данный файл предполагает, что `gunicorn` прописан в файле `requirements.txt`.

``` yaml
meta:
  environment: python
  toolchain:
    name: pip
    version: 3.10

run:
  command: gunicorn --bind 0.0.0.0:5000 app:app
  containerPort: 5000
```

#### ASGI-приложение (напр., приложение на FastAPI)

Данный файл предполагает, что `uvicorn[standard]` прописан в файле `requirements.txt`.

``` yaml
meta:
  environment: python
  toolchain:
    name: pip
    version: 3.10

run:
  command: uvicorn --host 0.0.0.0 --port 5000 app:app
  containerPort: 5000
```

## Форма графического интерфейса

Задать конфигурацию вы можете в интерфейсе личного кабинета при создании приложения, либо в разделе "Конфигурация" в созданном приложении.

![python_config](../../img/python_config.png)

### Секция meta

В данной секции доступно только указание версии python, которую требуется использовать.

### Секция build

В данной секции возможно указать имя файла с зависимостями. Чаще всего это requirements.txt.
Если файл находится не в корне, то следует указать название, включающее относительный путь до него. 

В файле зависимостей указываются библиотеки, которые использует приложение (устанавливалось на компьютер через pip, когда запускался проект локально). Указывать стандартные библиотеки не нужно. 
Частой ошибкой является использование в файле requirements.txt - имени telebot, а не pyTelegramBotAPI для телеграм-ботов на Python, правильно - pyTelegramBotAPI.

Если, например, файл с зависимостями находится не в корне, а в папке (в примере ниже в папке в build), то в значение этого поля необходимо указать:

```
build/requirements.txt
```

Если файл находится в корне:

```
requirements.txt
```

### Секция run

Параметры `scriptName` и `command` взаимоисключающие. Один из них должен быть указан для успешного запуска приложения.

#### scriptName

В данном поле указывается имя файла, который содержит точку входа в программу (функцию main). Так, в случае если проект
состоит из одного файла с названием `myApp.py` достаточно в это поле вписать:

```
myApp.py
```

#### command

Если проект запускается командой, укажите вместо scriptName требуемую команду запуска.

Примером может являться команда из статьи “Быстрый старт” 

``` shell
gunicorn --bind 0.0.0.0:5000 app:app
```

Либо в зависимости от порта

``` shell
command: gunicorn --bind 0.0.0.0:80 app:app
```

Заполняется либо scriptName, либо command.


#### persistenceMount

Это папка постоянного хранилища. В нашем сервисе она по умолчанию /data

```{eval-rst}
.. admonition:: Важно
   :class: warning

   Файлы в /data не затираются при пересборке проекта, в отличие от репозитория, где они откатятся к версии коммита. 
   Поэтому, мы рекомендуем использовать именно /data для баз данных и других получаемых в процессе работы приложения файлов.
```

```{eval-rst}
.. admonition:: Частая ошибка
   :class: error

   Если вы создадите в репозитории папку data, это не то-же самое, что папка /data у нас. Папка data в репозитории, 
   это просто папка в репозитории, которая может быть затерта при пересборке проекта.
```

В коде проекта следует указать /data как место для сохранения файлов.

Если вам неудобно использовать каталог /data, обычно, вы можете его изменить в файле amvera.yml. Например:

persistenceMount: /var/myapp/data

Задание значение persistenceMount равной /app или его подпапке может приводить к некорректному поведению.


#### conteinerPort

Указывается порт, который слушает приложение. По умолчанию это 80 порт.

Если ваше приложение работает по протоколу HTTP, но использует номер порта, отличный от 80, требуется указать номер этого порта в данное поле.
Например, если приложение слушает порт 3000, то в поле вписывается значение:

```
3000
```
### Применение конфигурации

```{eval-rst}
.. admonition:: Важно
   :class: warning

   После заполнения соответствующих полей нажмите кнопки "применить" (для раздела "Конфигурация") или "завершить", если вы задаете параметры при создании проекта.
```

Конфигурационный файл будет добавлен в корень репозитория и отобразится в папке "Code" раздела "Репозиторий". Не забудьте добавить его в свой локальный репозиторий, склонировав репозиторий из Amvera, либо скачав папку из личного кабинета.

После нажатия кнопки "Собрать" в конфигурации, либо пуше в репозиторий, либо при нажатии кнопки "Завершить" в рамках создания приложения начнется процесс [сборки](../build.md).