> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.squarecloud.app/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Gunicorn: Webserver de produção para aplicações WSGI

# Como Configurar o Gunicorn em Produção na Square Cloud

Se você vem desenvolvendo aplicações web com Python utilizando frameworks como Django ou Flask, sabe que rodar o servidor embutido de desenvolvimento (`flask run` ou `python app.py`) não é uma opção para o mundo real. Eles não aguentam o tranco de múltiplas requisições simultâneas.

Para colocar sua aplicação no ar com performance e estabilidade, você precisa de um servidor WSGI pronto para o campo de batalha: o **Gunicorn** (Green Unicorn). 

Abaixo, veja como orquestrar o Gunicorn perfeitamente dentro do ambiente da Square Cloud, que já lida com o host `0.0.0.0` e a porta padrão `80` para você.

---

## 1. Declarar as Dependências

Como a Square cuida da instalação para você de forma automática, o seu único trabalho é garantir que o Gunicorn esteja listado como uma dependência do projeto.

Se você utiliza o **`requirements.txt`**, adicione a linha:
```text
gunicorn
```

Se o seu projeto utiliza o padrão oficial do **`pyproject.toml`** (PEP 621), adicione-o na seção de dependências do projeto:
```toml
[project]
dependencies = [
    "gunicorn>=23.0.0",
]
```

Ao subir o projeto, a Square lerá esses arquivos e deixará o módulo do Gunicorn pronto para uso.

---

## 2. Entendendo o comando

Para garantir que o Gunicorn seja executado exatamente pelo interpretador Python isolado do seu container na Square, a boa prática é chamá-lo como um módulo utilizando a flag `-m`:

```bash
python -m gunicorn [opções] nome_do_modulo:atributo_da_aplicacao
```

* **`nome_do_modulo`**: É o nome do arquivo `.py` onde está a sua aplicação (ex: `main` ou `wsgi`).
* **`atributo_da_aplicacao`**: É a variável que recebe a instância do seu framework (geralmente chamada de `app` ou `application`).

### Exemplo Prático com Flask
Se você tem um arquivo na raiz chamado `wsgi.py`:

```python
from meu_projeto import app

if __name__ == "__main__":
    app.run()
```

O comando para o Gunicorn gerenciar esse app será `python -m gunicorn wsgi:app`.

---

## 3. Configurando Host, Porta e Workers para a Square

Para que o container da Square consiga receber o tráfego de internet e distribuí-lo para o seu app, você deve obrigatoriamente apontar o servidor para o host `0.0.0.0` e para a porta `80`.

O comando de inicialização ideal fica assim:

```bash
python -m gunicorn --bind 0.0.0.0:80 --workers 3 wsgi:app
```

### O que cada parâmetro faz aqui?
* **`--bind 0.0.0.0:80` (ou `-b`)**: Vincula o Gunicorn a todas as interfaces de rede do container na porta HTTP padrão (`80`), permitindo que a Square entregue as requisições externas diretamente ao seu app.
* **`--workers 3` (ou `-w`)**: Define a quantidade de processos trabalhadores simultâneos. 

> 💡 **Dica de Ouro para a Square:** O número de workers depende do plano do seu container. A recomendação padrão do Gunicorn é `(2 × número de cores da CPU) + 1`. Se o seu plano na Square disponibiliza 1 core de CPU, configure para `3` workers para extrair o máximo de concorrência sem estourar o limite de memória.

---

## 4. Automatizando o Início no `squarecloud.app`

Para que tudo isso funcione de forma 100% automatizada, você só precisa mapear o comando de inicialização dentro do arquivo de configuração da Square, o `squarecloud.app`, localizado na raiz do seu projeto.

Adicione a diretiva `START` apontando para o comando que estruturamos:

```ini
MAIN=wsgi.py
MEMORY=512
VERSION=recommended
START=python -m gunicorn --bind 0.0.0.0:80 --workers 3 wsgi:app
```

Se preferir usar um arquivo de configuração separado para o Gunicorn (como um `gunicorn.conf.py` para regras de timeout ou logs mais avançados), você pode simplificar a linha de início:

```ini
START=python -m gunicorn -c gunicorn.conf.py wsgi:app
```
*(Lembrando que, dentro do seu* *`gunicorn.conf.py`**, a variável `bind` deve obrigatoriamente ser `"0.0.0.0:80"`).*