Python Web Boilerplate

Fundacao executavel para aplicacoes web server-side com FastAPI, Jinja2, SQLAlchemy assincrono, PostgreSQL, Alembic e Docker Compose.

O repositorio resolve a infraestrutura inicial sem impor um dominio de negocio. Depois do clone, o trabalho comeca pela funcionalidade que diferencia o projeto.

Stack

• Python 3.12+
• FastAPI e Uvicorn
• Jinja2
• SQLAlchemy async e asyncpg
• PostgreSQL 17
• Alembic
• uv, pytest e Ruff
• Dockerfile e Docker Compose

Inicio rapido com Docker

git clone git@github.com:fabricioveronez/boilerplate-python-web.git
cd boilerplate-python-web
cp .env.example .env
./scripts/up

Acesse:

• Aplicacao: http://localhost:8000
• OpenAPI: http://localhost:8000/docs
• Health check: http://localhost:8000/api/health
• Readiness: http://localhost:8000/api/ready

O script espera os health checks. O container da aplicacao aplica as migrations antes de iniciar o servidor.

Operacao

./scripts/up
./scripts/test
./scripts/exec .venv/bin/alembic current
./scripts/down

• up: constroi e inicia aplicacao e PostgreSQL de forma idempotente.
• test: prepara o banco e executa Ruff e toda a suite de testes.
• exec: executa um comando nao interativo dentro do container da aplicacao.
• down: encerra os containers sem apagar o volume do PostgreSQL.

Desenvolvimento local

Para executar o servidor no host durante o desenvolvimento:

cp .env.example .env
docker compose up -d postgres
uv sync
uv run alembic upgrade head
uv run uvicorn app.main:app --app-dir src --reload

Qualidade

./scripts/test

Os testes de integracao usam o DATABASE_URL configurado no ambiente.

Estrutura

src/app/
├── api/             # endpoints JSON
├── core/            # configuracao e banco
├── models/          # modelos SQLAlchemy
├── static/          # CSS e outros assets
├── templates/       # paginas Jinja2
├── main.py          # composicao FastAPI
└── web.py           # rotas HTML
src/Dockerfile       # imagem unica da aplicacao
alembic/             # migrations
tests/               # testes unitarios e de integracao
scripts/             # interface operacional

Leia AGENTS.md antes de delegar uma alteracao a um agente de codificacao.

Primeira funcionalidade

Crie um modulo de dominio com modelo, migration, regras, rotas e templates. O boilerplate nao inclui um CRUD de exemplo de proposito: exemplos ficticios costumam virar dependencias acidentais do produto.