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:

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:

[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:

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:

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:

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:

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:

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").

Atualizado em: 03/07/2026