Gunicorn - Gerenciamento

📚 Sobre este manual: Gerenciamento do servidor WSGI Gunicorn para aplicações Python (Flask/Django).

📑 Índice Rápido

🔧 Comandos Básicos 🚀 Iniciar Site ⏹️ Parar Site 🔄 Reiniciar Site 👥 Workers 🔍 Verificar 🔄 Inicialização Automática ❌ Erros Comuns

🔧 Comandos Básicos

Estrutura padrão do comando Gunicorn:

/var/www/nome-do-site/venv/bin/gunicorn --workers 3 --bind unix:/var/www/nome-do-site/nome-do-site.sock app:app --daemon

📌 Explicação dos parâmetros:

--workers 3 - Número de processos (workers)
--bind unix:/caminho/socket.sock - Socket Unix para comunicação com Nginx
app:app - Para Flask: arquivo app.py com variável app
meusite.wsgi:application - Para Django
--daemon - Roda em background (modo serviço)

🚀 Iniciar um Site

Flask:

cd /var/www/nome-do-site
sudo -u www-data /var/www/nome-do-site/venv/bin/gunicorn --workers 3 --bind unix:/var/www/nome-do-site/nome-do-site.sock app:app --daemon

Django:

cd /var/www/nome-do-site
sudo -u www-data /var/www/nome-do-site/venv/bin/gunicorn --workers 3 --bind unix:/var/www/nome-do-site/nome-do-site.sock meusite.wsgi:application --daemon

⏹️ Parar um Site

Parar um site específico:

sudo pkill -f "nome-do-site.*gunicorn"

Parar todos os sites:

sudo pkill -f gunicorn

Parar de forma mais agressiva (se não parar):

sudo pkill -9 -f "nome-do-site.*gunicorn"

⚠️ Atenção: O -9 força a parada imediata. Use apenas se o comando normal não funcionar.

🔄 Reiniciar um Site

# 1. Parar
sudo pkill -f "nome-do-site.*gunicorn"

# 2. Aguardar 2 segundos
sleep 2

# 3. Iniciar novamente
cd /var/www/nome-do-site
sudo -u www-data /var/www/nome-do-site/venv/bin/gunicorn --workers 3 --bind unix:/var/www/nome-do-site/nome-do-site.sock app:app --daemon

# 4. Verificar
ps aux | grep nome-do-site | grep -v grep

👥 Configuração de Workers

A quantidade de workers depende do servidor (CPU + RAM):

# Regra geral: workers = (2 x CPU) + 1
# Exemplo: 2 CPUs = 5 workers

# Servidor pequeno (1-2GB RAM)
--workers 3

# Servidor médio (4GB RAM)
--workers 5

# Servidor grande (8GB+ RAM)
--workers 7-9

💡 Dica: Workers demais consomem RAM. Workers de menos podem deixar o site lento. Comece com 3 e ajuste conforme necessidade.

🔍 Verificar se está rodando

# Ver processos Gunicorn
ps aux | grep gunicorn | grep -v grep

# Verificar socket (deve existir)
ls -la /var/www/nome-do-site/nome-do-site.sock

# Testar comunicação com o socket
curl --unix-socket /var/www/nome-do-site/nome-do-site.sock http://localhost/

# Verificar se o site responde via Nginx
curl -I http://seudominio.com.br
curl -I https://seudominio.com.br

🔄 Inicialização Automática (Reboot)

Para o Gunicorn iniciar automaticamente quando o servidor reiniciar, use o crontab:

# Editar crontab
sudo crontab -e

Adicionar a linha (substitua nome-do-site):

@reboot sleep 30 && cd /var/www/nome-do-site && sudo -u www-data /var/www/nome-do-site/venv/bin/gunicorn --workers 3 --bind unix:/var/www/nome-do-site/nome-do-site.sock app:app --daemon

✅ Para múltiplos sites: Adicione uma linha para cada site, com sleep diferente:

@reboot sleep 30 && cd /var/www/site1 && ...
@reboot sleep 45 && cd /var/www/site2 && ...
@reboot sleep 60 && cd /var/www/site3 && ...

❌ Erros Comuns e Soluções

No such file or directory (gunicorn)

O Gunicorn não está instalado no ambiente virtual.

# Instalar Gunicorn no venv
sudo -u www-data /var/www/nome-do-site/venv/bin/pip install gunicorn

Address already in use / Socket exists

O socket já existe (outro processo rodando).

# Parar o processo antigo
sudo pkill -f "nome-do-site.*gunicorn"

# Remover socket antigo
sudo rm -f /var/www/nome-do-site/nome-do-site.sock

# Iniciar novamente

Permission denied (socket)

O usuário www-data não tem permissão.

# Ajustar permissões
sudo chown -R www-data:www-data /var/www/nome-do-site
sudo chmod -R 755 /var/www/nome-do-site

ImportError: No module named 'app'

O nome do arquivo ou variável está incorreto.

# Verificar o arquivo principal
ls -la /var/www/nome-do-site/*.py

# Para Flask: app:app (arquivo app.py com variável app)
# Para Django: meusite.wsgi:application

Worker timeout (ou site lento)

O worker demorou mais que o tempo limite.

# Aumentar o timeout
gunicorn --workers 3 --timeout 300 --bind unix:/var/www/nome-do-site/nome-do-site.sock app:app --daemon

502 Bad Gateway (Nginx)

Nginx não consegue se comunicar com o Gunicorn.

# Verificar se Gunicorn está rodando
ps aux | grep nome-do-site

# Verificar se socket existe
ls -la /var/www/nome-do-site/nome-do-site.sock

# Verificar permissões do socket
# O socket deve ser legível pelo Nginx

💡 Boas práticas:

✅ Sempre rode o Gunicorn como usuário www-data
✅ Use sockets Unix em vez de portas TCP (mais rápido)
✅ Após atualizar código, sempre reinicie o Gunicorn
✅ Configure workers baseado na sua RAM (monitore com htop)
✅ Mantenha o timeout alto (300s) para queries SQL demoradas

📌 Estrutura de arquivos após iniciar:

/var/www/nome-do-site/
├── nome-do-site.sock     # Socket criado automaticamente
├── app.py                # Seu código Flask
├── venv/                 # Ambiente virtual
│   └── bin/gunicorn      # Executável do Gunicorn
└── static/               # Arquivos estáticos

🔗 Links úteis:
Documentação oficial do Gunicorn
Guia de Workers

Manual Técnico - Última atualização: Março 2026

📚 Manual Técnico