![]() |
Flask+jinja2 na criação web: Reprodução |
Preparamos um pequeno projeto de site com flask e jinja2 para renderização do projeto.
você pode instalar e editar no próprio computador e colocar "online" em modo de teste, também deixamos algumas instruções para deixar online em uma VM Windows Server.
Você pode baixar o projeto e testar através deste link 🔗>Download_do_projeto_mostrado
Dentro do diretório contém todos os arquivos e requirements.txt para as libs.
- abra o prompt após ter instalado o python > 3.10 e inicie com esses comandos
- Acesse o diretório raiz do projeto pelo Prompt CMD.
- cd C:\Users\User\Downloads\fantasia_rota\site_exemplo_flask
- #instale o python no projeto
- python -m venv venv
- :: Ative o ambiente virtual
- venv\Scripts\activate.bat
- instale as bibliotecas
- pip install -r requirements.txt
- Ative o projeto
- python app.py
- cd C:\Users\User\Downloads\fantasia_rota\site_exemplo_flask #sempre use cd no prompt mantenha o nome de pastas e arquivos dentro dos projetos sempre em letra minúscula
- venv\Scripts\activate
- python app.py
aqui nosso site esta ligado e abre na porta localhost http://127.0.0.1:5000 padrão do flask
![]() |
pagina termos de uso |
para desligar o projeto e voltar a editar use CTRL + C veja na imagem abaixo ::
Assim desligamos o projeto e voltamos ao modo edição e codificação sempre testando após cada novo código inserido com ::
-
cd C:\Users\User\Downloads\fantasia_rota\site_exemplo_flask #sempre use cd no prompt mantenha o nome de pastas e arquivos
dentro dos projetos sempre em letra minúscula
- venv\Scripts\activate
- python app.py
Visão Geral
Este artigo oferece um panorama abrangente sobre como transformar um projeto Flask/Jinja2 em um serviço web robusto em produção.
Abordaremos a organização de arquivos, módulos fundamentais, erros de instalação recorrentes, técnicas de depuração e práticas de deploy em ambientes Windows e Linux.
1. Estrutura de Diretórios do Projeto de Exemplo
site_exemplo_flask/
├── app.py # Entrada principal WSGI
├── run.py # Script para ativar venv e subir o servidor local (Windows)
├── requirements.txt # Dependências do projeto
├── README.md # Documentação de uso
├── static/
│ └── style.css # Folha de estilos global
└── templates/
├── index.html # Página inicial
├── politica.html # Política de Privacidade
└── termos.html # Termos de Uso
Boas práticas: adicione um diretório
tests/
para casos de teste unitário e
config.py
para variáveis de ambiente.
2. Módulos Essenciais
Módulo | Propósito | Observações |
---|---|---|
Flask | Núcleo do micro‑framework | Versão 2.3+ recomendada |
Jinja2 | Motor de templates | Incluso como dependência de Flask |
python-dotenv | Carregar variáveis de ambiente | Evita hardcodear segredos |
Werkzeug | Servidor WSGI interno e utilities | Já incluso em Flask |
Waitress | WSGI server estável (Windows) | Substitui flask run em produção |
Gunicorn | WSGI server performático (Linux) | Requer Linux/WSL |
3. Instalação e Ambiente
Requisito mínimo: Python ³·¹⁰.
Acesse > https://www.python.org/
Siga para > https://www.python.org/downloads/release/python-3135/
# 1. Criar e ativar venv
python -m venv venv
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windows
# 2. Instalar dependências
pip install -r requirements.txt
# 3. Rodar localmente
python app.py # Debug=True apenas em dev
Erros de Instalação Comuns
Sintoma | Causa Provável | Solução |
---|---|---|
ModuleNotFoundError: No module named 'flask'
|
Venv não ativado | Execute activate antes do pip |
ValueError: attempted relative import |
Estrutura de pacotes mal definida |
Converta diretório em package usando
__init__.py
|
RuntimeError: Working outside of application context
|
Uso de objetos Flask fora da view |
Utilize with app.app_context(): ou refatore
|
4. Depuração (Debug) e Logging
-
Flask Debug Toolbar – plug‑in que exibe consultas SQL, tempo de resposta e cabeçalhos HTTP.
-
Logging nativo – configure
logging.basicConfig(level=logging.INFO)
emapp.py
. -
Breakpoint remoto – use
pip install debugpy
e anexe IDE (VS Code ou PyCharm) em containers/VMs.
Cuidado: nunca ative
debug=True
em produção; ele expõe stack‑trace público e variáveis de ambiente.
5. Deploy em Produção
5.1 Windows (Waitress + NSSM)
pip install waitress
waitress-serve --port=8000 app:app # Teste local
Para criar um serviço Windows:
-
Baixe NSSM (Non‑Sucking Service Manager).
-
nssm install MinhaApp
➜ Path:venv\Scripts\python.exe
Args:-m waitress --port 8000 app:app
. -
Inicie o serviço via services.msc.
5.2 Linux (Gunicorn + Nginx)
sudo apt update && sudo apt install nginx python3-venv
pip install gunicorn
# systemd unit
sudo tee /etc/systemd/system/minhaapp.service > /dev/null << EOF
[Unit]
Description=Gunicorn instance for minhaapp
After=network.target
[Service]
User=www-data
Group=www-data
WorkingDirectory=/var/www/minhaapp
Environment="PATH=/var/www/minhaapp/venv/bin"
ExecStart=/var/www/minhaapp/venv/bin/gunicorn -w 3 -b unix:minhaapp.sock app:app
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl enable --now minhaapp
Configure Nginx como reverse proxy para
unix:minhaapp.sock
.
5.3 Docker (Imutabilidade)
FROM python:3.12
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD gunicorn -w 3 -b 0.0.0.0:8000 app:app
6. Bugs Frequentes Pós‑Deploy
Manifestação | Diagnóstico | Mitigação |
---|---|---|
Página branca (502) | Gunicorn não inicializou / Socket incorreto |
Verifique logs systemctl status ; confirme
caminho do socket
|
Encoding incorreto | Falta de charset=UTF‑8 no template |
Defina <meta charset="UTF-8"> e force
env LC_ALL=C.UTF-8
|
CSRF token missing (Django) |
Formulário sem {{ csrf_token }} |
Incluir token ou desabilitar proteção conforme contexto |
7. Checklist de Produção
-
Variáveis de ambiente carregadas com python‑dotenv ou serviço secreto.
-
Logs rotacionados (
logrotate
ou Windows Event Viewer). -
Backup automatizado do banco de dados.
-
Monitoramento de uptime (UptimeRobot, Grafana).
Conclusão
Compreender cada fase—da instalação local ao deploy profissional—reduz drasticamente o ciclo de feedback e a incidência de bugs em produção. Ao aplicar as práticas acima, seu backend Python ganhará confiabilidade, desempenho e segurança alinhados às exigências de ambientes corporativos.
Próximos passos: explore CI/CD (GitHub Actions), teste de carga (Locust) e observabilidade com Prometheus + Grafana.