# platform-templates: dar de alta una app nueva

!!! info "Qué problema resuelve"
    Antes de este repo, cada app nueva significaba escribir un
    Dockerfile, un pipeline con los 5 pasos de DevSecOps (Gitleaks,
    Trivy, Semgrep, Syft, Cosign), y los manifiestos de Kubernetes —
    todo desde cero, copiando y adaptando a mano lo que ya existía en
    otra app. `platform-templates` es el repo donde ese trabajo repetido
    quedó hecho una sola vez: copiás una plantilla, completás unos
    pocos valores (nombre, imagen, puerto), y tenés el mismo nivel de
    seguridad y buenas prácticas que ya tienen `ecommerce-frontend`,
    `commerce-backend` y `docs-portal` — sin tener que redescubrirlas.

Repo: [`devops/platform-templates`](https://gitea.cruzcloud.net/devops/platform-templates)

## De "tengo código" a "está corriendo en producción"

```mermaid
flowchart TD
    A["Tengo código<br/>(una app nueva)"] --> B["Elegir arquetipo:<br/>Next.js / API Node / sitio estático"]
    B --> C["Copiar Dockerfile de<br/>platform-templates/dockerfiles/"]
    C --> D["Agregar .gitea/workflows/build.yaml<br/>que llama al reusable workflow del arquetipo"]
    D --> E["Copiar k8s-manifests/overlays-ejemplo/<br/>y ajustar nombre/imagen/puerto"]
    E --> F["Generar par de llaves Cosign<br/>(cosign.pub commiteado, privada como secret)"]
    F --> G["git push"]
    G --> H["Pipeline: Gitleaks → build →<br/>Trivy → Semgrep → Syft → Cosign"]
    H -->|"CRITICAL o firma inválida"| I["❌ Pipeline se detiene<br/>(nada llega al registry)"]
    H -->|"todo pasa"| J["Imagen firmada<br/>sube al registry"]
    J --> K["Pipeline actualiza el<br/>manifiesto GitOps automáticamente"]
    K --> L["Argo CD detecta el cambio<br/>y sincroniza"]
    L --> M["✅ App corriendo,<br/>con probes + resource limits +<br/>securityContext ya puestos"]

    style A fill:#e8f4fd,stroke:#4a90d9
    style M fill:#e6f7e6,stroke:#4ba84b
    style I fill:#fde8e8,stroke:#d94a4a
```

Los pasos A→F son manuales (una vez, al dar de alta la app). De G en
adelante es automático — cada `git push` a `main` repite H→M solo.

## Los 3 arquetipos

| Arquetipo | Para qué | Basado en |
|---|---|---|
| `archetype-nextjs-frontend` | Frontend Next.js con SSR (`output: standalone`) | `ecommerce-frontend` |
| `archetype-node-api` | API backend Node/Express, sin UI | `commerce-backend` (Medusa) |
| `archetype-static-site` | Sitio estático servido por nginx (MkDocs, Hugo, Astro) | `docs-portal` |

Cada uno ya trae integrado el pipeline completo de DevSecOps — no hay
que agregar los 5 pasos por separado, vienen adentro del reusable
workflow.

## Un detalle real de Gitea que no es como GitHub

Armar este repo requirió confirmar en vivo (no asumir) cómo Gitea
Actions maneja las referencias cross-repo, porque **no es 1:1 igual a
GitHub Actions** en dos puntos concretos:

1. Los reusable workflows (`workflow_call`) tienen que vivir en
   `.gitea/workflows/` — no en cualquier carpeta.
2. Cualquier `uses:` que apunte a otro repo de esta misma instancia
   necesita la URL completa (`https://gitea.cruzcloud.net/owner/repo/...`)
   — la forma corta de GitHub (`owner/repo/...`) se resuelve contra
   **github.com** acá, no contra Gitea local.

El detalle completo, con el error real del servidor que confirmó cada
punto, está en el README del repo
([`pipelines/archetype-nextjs-frontend/README.md`](https://gitea.cruzcloud.net/devops/platform-templates/src/branch/main/pipelines/archetype-nextjs-frontend/README.md)).

## Ver también

- [Migración de docs-portal/frontend/medusa a platform-templates](../playbooks/migracion-platform-templates-2026-08.md)
  — qué cambió en las 3 apps que ya existían, y los bugs reales que
  aparecieron aplicándolo en producción.