# Python Pip

This configuration is suitable if the project is written in Python and either has no dependencies or they are specified in the `requirements.txt` file.

You can create a yml file in the interface, use our yaml generator by clicking on [link](https://manifest.amverum.ru/), or independently, using the instructions below.

Instructions for filling out the configuration through the interface are in the second half of this article.

## Configuration file

### Meta section

The meta section specifies the version of Python you are using.

The meta section of the amverum.yml file will look like this:

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

The Docker image `python:${meta.toolchain.version}` is used for both building and running. The `meta.toolchain.version` parameter is optional. If it is not specified, the `python:3` image will be used.

Since the value of the `meta.toolchain.version` parameter is a python image tag, you can use an arbitrary tag on [docker hub](https://hub.docker.com/_/python/tags) as its value. However, since we call the interpreter as `python3`, and also use the
`venv` module in the `python3 -m venv` command, the Python image must support these features.

### The build section

The build section specifies the name of the file with dependencies (libraries that the system should install via pip).

The `build` section may contain one optional parameter: `requirementsPath`. It defines the path to the file
`requirements.txt` relative to the repository root. If this parameter is not specified, it defaults to `requirements.txt`.

If, for example, this file is in the build folder, then the value of this parameter must be specified as follows:

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

If the project does not use the `requirements.txt` file at all or the build script cannot find it at the specified
path, then the dependency installation phase will be skipped.

### The run section

The following parameters can be specified in the `run` section:

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

The `scriptName` and `command` parameters are mutually exclusive. One of them must be specified to successfully run the application.

The `scriptName` parameter specifies the path to a file with the `ru` extension. It is used in the `python3 ${run.scriptName}` command:

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

If the launch is performed by another command, for example, `gunicorn`, then the `command` parameter can be used:

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

The `persistenceMount` parameter allows you to specify the directory to which the folder with [persistent storage](../storage.md#data) will be mounted.

The default value is `/data`.

The persistent storage and the data folder in the repository are different directories. It is recommended to use persistent storage.

The `containerPort` parameter allows you to specify the port the application listens on. The default value is `80`.

### Recipes

#### Minimal amverum.yml file

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

run:
  scriptName: app.py
```

#### WSGI application (e.g. Flask application)

This file assumes that `gunicorn` is specified in the `requirements.txt` file.

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

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

#### ASGI application (eg FastAPI application)

This file assumes that `uvicorn[standard]` is specified in `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 Section

This section only allows you to specify the version of Python you want to use.

### Build Section

This section allows you to specify the name of the file with dependencies. Most often, this is requirements.txt.
If the file is not in the root, then you should specify the name, including the relative path to it.

The dependency file specifies the libraries that the application uses (installed on the computer via pip when the project was launched locally). You do not need to specify standard libraries.

A common mistake is to use the name telebot in the requirements.txt file, and not pyTelegramBotAPI for telegram bots in Python, the correct one is pyTelegramBotAPI.

If, for example, the file with dependencies is not in the root, but in a folder (in the example below in the folder in build), then the value of this field must be specified:

```
build/requirements.txt
```

If the file is in the root:

```
requirements.txt
```

### Section run

The `scriptName` and `command` parameters are mutually exclusive. One of them must be specified to successfully launch the application.

#### scriptName

This field specifies the name of the file that contains the entry point to the program (the main function). So, if the project
consists of one file named `myApp.py`, it is enough to enter in this field:

```
myApp.py
```

#### command

If the project is launched by a command, specify the required launch command instead of scriptName.

An example would be the command from the article “Quick Start” 

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

Or depending on the port

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

Either scriptName or command is filled in.


#### persistenceMount

This is the persistent storage folder. In our service it is /data by default.

```{eval-rst}
.. admonition:: Important
   :class: warning

   Files in /data are not overwritten when the project is rebuilt, unlike in the repository, where they are rolled back to the commit version. 
   Therefore, we recommend using /data for databases and other files received during the application's operation.
```

```{eval-rst}
.. admonition:: A common mistake
   :class: error

   If you create a data folder in the repository, it is not the same as the /data folder we have. The data folder in the repository is just a folder in the repository that can be overwritten when rebuilding the project.
```

In the project code, you should specify /data as the location to save files.

If you are not comfortable using the /data directory, you can usually change it in the amverum.yml file. For example:

persistenceMount: /var/myapp/data

Setting the persistenceMount value to /app or its subfolder may cause incorrect behavior.

#### containerPort

Specifies the port that the application listens to. By default, this is port 80.

If your application works via HTTP, but uses a port number other than 80, you must specify this port number in this field.
For example, if the application listens to port 3000, then the value entered in the field is:

```
3000
```
### Applying the configuration

```{eval-rst}
.. admonition:: Important
   :class: warning

   After filling in the appropriate fields, click the "Apply" button (for the "Configuration" section) or "Finish" if you set the parameters when creating a project.
```

The configuration file will be added to the root of the repository and will be displayed in the "Code" folder of the "Repository" section. Don't forget to add it to your local repository by cloning the repository from Amverum or downloading the folder from your personal account.

After clicking the "Build" button in the configuration, or pushing to the repository, or when clicking the "Finish" button as part of creating the application, the [build] process will begin(../build.md).