template-web-backend-python/README.md

APP_NAME — Web Backend Python (FastAPI + Alembic)

App generada desde el Golden Path web-backend/python de Coralware Cove IDP.

Este repositorio contiene el scaffold completo: aplicación FastAPI, migraciones Alembic, frontend estático en /demo, Helm chart, workflow de CI y manifiesto de contrato con la plataforma. Cuando se materializa este template para tu tenant, los placeholders en mayúsculas se sustituyen automáticamente.

Contrato del shape: ver coralware-shape.yaml en la raíz. Define los endpoints obligatorios, la BD esperada y la versión del shape. No elimines ese archivo — la plataforma lo lee.

---

Estructura

.
├── coralware-shape.yaml          ← contrato con la plataforma
├── catalog-info.yaml             ← entidad Backstage
├── code/
│   ├── app/                      ← FastAPI app
│   ├── alembic/                  ← migraciones DB
│   ├── tests/                    ← pytest + cobertura
│   ├── pyproject.toml
│   ├── requirements.txt
│   └── Dockerfile
├── helm/__APP_NAME__/            ← Helm chart con hook Alembic pre-upgrade
├── claim-mariadb.yaml            ← AddonClaim de la BD (ver §Base de datos)
└── .gitea/workflows/             ← CI: tests + build + deploy

---

Ciclo de vida

1. Tú escribes código — endpoints en code/app/routers/, modelos en code/app/models/, migraciones con alembic revision --autogenerate.
2. git push a main dispara el workflow Gitea Actions.
3. El CI corre black, ruff, bandit, pytest --cov. Si algo falla, el pipeline aborta.
4. Si pasa, builda la imagen linux/amd64 con BuildKit y la publica en el proyecto Harbor de tu tenant.
5. helm upgrade --install aplica el chart al cluster de tu tenant. Antes del rollout, un Job pre-upgrade corre alembic upgrade head. Si Alembic falla, Helm aborta y la app vieja queda intacta.
6. Tras rollout exitoso, smoke check valida /health 200.

---

Endpoints obligatorios

Path	Auth	Propósito
/health	none	Liveness + readiness; devuelve {status: ok, db: up|down}
/docs	configurable (OPENAPI_REQUIRE_AUTH)	Swagger UI
/openapi.json	igual que /docs	Schema OpenAPI
/demo	none	Frontend estático servido desde code/app/static/demo/
/metrics	restringido vía NetworkPolicy	Métricas Prometheus

/health, /docs, /demo son contrato del shape — NO renombres.

---

Base de datos

Tu app espera un Secret __APP_NAME__-db-creds en su namespace con las claves DATABASE_URL y MIGRATION_DATABASE_URL. El Secret lo provisiona la plataforma:

• PoC / MVP — Coralware lo crea manualmente siguiendo el runbook docs/runbook-mariadb-poc.md en el repo IDP. Tú no haces nada.
• Producción (Fase 5.5+) — claim-mariadb.yaml lo materializa automáticamente cuando esté disponible el controller addon-provisioner (ver ADR-052).

---

Variables de entorno

Variable	Origen	Default	Descripción
DATABASE_URL	Secret	—	Connection string runtime
MIGRATION_DATABASE_URL	Secret	= DATABASE_URL	Connection para Alembic
LOG_LEVEL	ConfigMap	INFO	DEBUG para troubleshooting
CORRELATION_ID_HEADER	ConfigMap	X-Correlation-ID	Header de trazabilidad
OPENAPI_REQUIRE_AUTH	ConfigMap	false	Activar JWT en /docs
KEYCLOAK_ISSUER	ConfigMap	—	URL del realm cuando auth activado
STATIC_DEMO_PATH	ConfigMap	/app/static/demo	Path al frontend estático

---

Migraciones Alembic

Migración base vacía en code/alembic/versions/0001_initial.py. Para crear una nueva tras agregar modelos:

cd code
alembic revision --autogenerate -m "agregar tabla users"

---

Desarrollo local

cd code
pip install -r requirements-dev.txt

docker run --rm -d --name mariadb-dev \
  -e MARIADB_ROOT_PASSWORD=dev -e MARIADB_DATABASE=app \
  -p 3306:3306 mariadb:11

export DATABASE_URL="mysql+pymysql://root:dev@127.0.0.1:3306/app"
export MIGRATION_DATABASE_URL="$DATABASE_URL"

alembic upgrade head
uvicorn app.main:app --reload --port 8000

---

Plan de salida

Si decides migrar fuera de Cove, todo lo que necesitas vive en formato estándar:

Componente	Cómo lo exportas
Código	git remote add github && git push github main
Imagen	docker pull desde Harbor + push a tu registry
Manifests	Ya están en helm/ — helm template genera YAML aplicable
Datos	Coralware ejecuta mariadb-dump y entrega .sql.gz

Sin lock-in técnico.

---

Referencias

• docs/adr-053-shape-web-backend-python.md — anatomía del shape
• docs/adr-052-tenant-addon-claim-model.md — modelo de add-ons (BD)
• docs/adr-038-ci-estandar-reusable-workflow.md — pipeline Python