Configurar um arquivo de inicialização personalizado para aplicativos Python no Serviço de Aplicativo do Azure

Neste artigo, você aprenderá quando e como configurar um arquivo de inicialização personalizado para um aplicativo Web Python hospedado no Serviço de Aplicativo do Azure. Embora um arquivo de inicialização não seja necessário para o desenvolvimento local, Serviço de Aplicativo do Azure executa seu aplicativo Web implantado em um contêiner do Docker que pode usar comandos de inicialização se você for fornecê-los.

Você precisa de um arquivo de inicialização personalizado nas seguintes situações:

• Argumentos gunicorn personalizados: você deseja iniciar o servidor Web padrão gunicorn com argumentos extras além de seus padrões, que são --bind=0.0.0.0 --timeout 600.

• Estruturas alternativas ou servidores: seu aplicativo é criado com uma estrutura diferente de Flask ou Django, ou você deseja usar um servidor Web diferente em vez de Gunicorn.

• Estrutura não padrão de aplicativo Flask: você tem um aplicativo Flask cujo arquivo de código principal tem um nome diferente de app.py ou application.py, ou o objeto do aplicativo tem um nome diferente de app.

Em outras palavras, você precisa de um comando de inicialização personalizado, a menos que seu projeto tenha um arquivo app.py ou application.py na pasta raiz com um objeto de aplicativo Flask chamado app.

Para obter mais informações, consulte Configurar aplicativos Python – processo de inicialização de contêiner.

Pré-requisitos

Antes de configurar um arquivo de inicialização personalizado, você precisa de um Serviço de Aplicativo no Linux existente executando Python. Para criar um App Service, siga o guia de início rápido do Python para o App Service. Você também pode criar um Serviço de Aplicativo usando o CLI do Azure:

az webapp create --resource-group <group> --plan <plan> --name <app-name> --runtime "PYTHON:3.12"

Criar um arquivo de inicialização

Quando precisar de um arquivo de inicialização personalizado, use as seguintes etapas:

1. Crie um arquivo em seu projeto chamado startup.txt, startup.sh ou outro nome de sua escolha que contenha seus comandos de inicialização. Consulte as seções posteriores neste artigo para obter detalhes sobre Django, Flask e outras estruturas.

   Um arquivo de inicialização pode incluir vários comandos, se necessário.

2. Confirme o arquivo no repositório de código para que ele possa ser implantado com o restante do aplicativo.

3. No Visual Studio Code, selecione o ícone do Azure na Barra de Atividades, expanda RECURSOS, localize e expanda sua assinatura, expanda os Serviços de Aplicativo e clique com o botão direito do mouse no Serviço de Aplicativo e selecione Abrir no Portal.

4. No Portal do Azure, no menu de serviços à esquerda, escolha Configurações>Configuração. Na página Configuração do Serviço de Aplicativo, selecione Configurações gerais, insira o nome do arquivo de inicialização (como startup.txt ou startup.sh) em Configurações de pilha>Comando de inicialização e, em seguida, selecione Salvar.

   Como alternativa, você pode usar o CLI do Azure para definir o comando de inicialização:

   az webapp config set --resource-group <group> --name <app-name> --startup-file "<startup-command>"
   

   Observação

   Em vez de usar um arquivo de comando de inicialização, você pode colocar o próprio comando de inicialização diretamente no campo Comando de Inicialização no portal do Azure. É recomendável usar um arquivo de comando de inicialização porque ele armazena sua configuração em seu repositório. Isso permite que o controle de versão acompanhe as alterações e simplifica a reimplantação para outras instâncias do Serviço de Aplicativo do Azure.

5. Selecione Continuar quando solicitado a reiniciar o Serviço de Aplicativo.

   Se você acessar o site do Serviço de Aplicativo do Azure antes de implantar o código do aplicativo, um "Erro de Aplicativo" será exibido porque nenhum código está disponível para processar a solicitação.

Comandos de inicialização do Django

Por padrão, o Serviço de Aplicativo do Azure localiza a pasta que contém o arquivo wsgi.py e inicia o Gunicorn com o seguinte comando:

# <module> is the folder that contains wsgi.py. If you need to use a subfolder,
# specify the parent of <module> using --chdir.
gunicorn --bind=0.0.0.0 --timeout 600 <module>.wsgi

Se você quiser modificar argumentos gunicorn, como aumentar o valor do tempo limite para 1.200 segundos (--timeout 1200), crie um arquivo de comando de inicialização personalizado. Esse método substitui as configurações padrão com seus requisitos específicos. Para obter mais informações, consulte o processo de inicialização do contêiner – aplicativo Django.

Comandos de inicialização do Flask

Por padrão, Serviço de Aplicativo no Linux pressupõe que seu aplicativo Flask atenda aos seguintes critérios:

• O chamável WSGI é chamado app.
• O código do aplicativo está contido em um arquivo chamado application.py ou app.py.
• O arquivo de aplicativo está localizado na pasta raiz do aplicativo.

Se o projeto for diferente dessa estrutura, o comando de inicialização personalizado deverá identificar a localização do objeto de aplicativo no arquivo de formato:app_object:

• Nome de arquivo diferente e/ou nome do objeto do aplicativo: se o arquivo de código principal do aplicativo for hello.py e o objeto do aplicativo for nomeado myapp, o comando de inicialização será o seguinte:

  gunicorn --bind=0.0.0.0 --timeout 600 hello:myapp
  

• O arquivo de inicialização está em uma subpasta: se o arquivo de inicialização for myapp/website.py e o objeto do aplicativo estiverapp, use o argumento do --chdir Gunicorn para especificar a pasta e nomeie o arquivo de inicialização e o objeto de aplicativo como de costume:

  gunicorn --bind=0.0.0.0 --timeout 600 --chdir myapp website:app
  

• O arquivo de inicialização está dentro de um módulo: no código python-sample-vscode-flask-tutorial, o arquivo de inicialização webapp.py está contido na pasta hello_app, que é um módulo com um arquivo __init__.py. O objeto do aplicativo é nomeado app e definido em __init__.py. webapp.py usa uma importação relativa.

  Devido a essa disposição, apontar o Gunicorn para webapp:app produz o erro "Tentativa de importação relativa em um não-pacote" e o aplicativo não é iniciado.

  Nessa situação, crie um arquivo shim que importe o objeto app do módulo, e em seguida, faça o Gunicorn iniciar o app usando o shim. O código python-sample-vscode-flask-tutorial , por exemplo, contém startup.py com o seguinte conteúdo:

  from hello_app.webapp import app
  

  O comando de inicialização é:

  gunicorn --bind=0.0.0.0 --workers=4 startup:app
  

Para obter mais informações, consulte o processo de inicialização do contêiner – aplicativo Flask.

Outras estruturas e servidores Web

O contêiner do Serviço de Aplicativo que executa aplicativos Python tem o Django e o Flask instalados por padrão, juntamente com o servidor Web Gunicorn.

Para usar uma estrutura diferente de Django ou Flask (como Falcon, FastAPI e outros), ou para usar um servidor Web diferente:

• Inclua a estrutura e o servidor Web no arquivo requirements.txt .

• No comando de inicialização, identifique o callable WSGI, conforme descrito na seção anterior para Flask.

• Para iniciar um servidor Web diferente do Gunicorn, use um python -m comando em vez de invocar o servidor diretamente. Por exemplo, o comando a seguir inicia o servidor uvicorn , supondo que o chamado WSGI seja nomeado app e encontrado em application.py:

  python -m uvicorn application:app --host 0.0.0.0
  

  Você usa python -m porque os servidores Web instalados por requirements.txt não são adicionados ao ambiente global Python e, portanto, não podem ser invocados diretamente. O python -m comando invoca o servidor de dentro do ambiente virtual atual.

Implante seu aplicativo

Depois de configurar o arquivo de inicialização, você precisará implantar o código do aplicativo no Serviço de Aplicativo. Use o CLI do Azure ou o método de implantação de sua escolha:

az webapp up --name <app-name>

Para obter mais opções de implantação, consulte as práticas recomendadas de implantação.