Arquitectura del Sistema de Gestión de Activos

Backstage opera bajo un modelo desacoplado donde la interfaz de usuario y los servicios de backend colaboran para indexar y servir metadatos de proyectos. La gestión de recursos no se limita a archivos estáticos, sino que abarca el registro de componentes, documentación técnica y configuraciones de infraestructura.

• Capa de Presentación: Plugins como el Catálogo de Software y TechDocs renderizan la información y proporcionan interfaces de interacción.
• Servicios de Backend: Manejan la ingesta de datos, el descubrimiento de servicios, la ejecución de tareas programadas y el almacenamiento de estado.
• Persistencia: Bases de datos relacionales que guardan entidades, relaciones jerárquicas y políticas de acceso.

Despliegue Inicial y Configuración del Entorno

Para provisionar un nuevo portal de desarrolladores, es recomendable utilizar la CLI oficial en lugar de clonar repositorios de terceros. Esto garantiza que la estructura de carpetas, los scripts de compilación y las dependencias estén completamente actualizadas.

# Generar la estructura base del portal
npx @backstage/create-app --path mi-portal-dev

# Acceder al directorio y preparar las variables de entorno
cd mi-portal-dev
cp .env.example .env

# Compilar y levantar los servicios en modo desarrollo
yarn install
yarn dev

El Catálogo de Software: Registro de Entidades

El núcleo de la organización de activos es el Catálogo de Software. Este módulo permite modelar servicios, APIs y recursos de infraestructura como entidades YAML. Para integrar un nuevo microservicio, se debe incluir un manifiesto en la raíz del repositorio correspondiente.

# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: servicio-pagos
  description: API REST para procesar transacciones financieras.
  annotations:
    github.com/project-slug: mi-org/servicio-pagos
spec:
  type: service
  lifecycle: production
  owner: equipo-finanzas

Una vez definido el manifiesto, el servicio de ingesta del backend detectará el archivo y lo indexará en la base de datos del catálogo, estableciendo automáticamente las dependencias con otras entidades registradas.

Descubrimiento de Servicios y Enrutamiento

En arquitecturas distribuidas, el backend de Backstage utiliza procesadores de descubrimiento para escanear organizaciones de GitHub, GitLab o Bitbucket. Esto automatiza la importación de archivos catalog-info.yaml sin intervención manual. La configuración de estos procesadores se realiza en el archivo principal de la aplicación.

# app-config.yaml
catalog:
  processors:
    githubOrg:
      providers:
        - target: https://github.com
          token: ${GITHUB_TOKEN}
  rules:
    - allow: [Component, API, Resource, System]

Integración de Documentación con TechDocs

TechDocs transforma archivos Markdown ubicados en los repositorios de código en sitios web de documentación navegables. Para previsualizar los cambios localmente antes de realizar un commit, se puede ejecutar el contenedor de transformación con parámetros personalizados.

# Ejecutar el servidor local de TechDocs en un puerto específico sin Docker
npx @backstage/techdocs-cli serve --port 3001 --no-docker

# Utilizar Docker para una renderización idéntica al entorno de producción
npx @backstage/techdocs-cli serve --port 3001

Estructura de Directorios Recomendada

Mantaner una topología de archivos limpia es crucial para la escalabilidad del portal. La siguiente distribución separa adecuadamente la lógica de negocio, los plugins personalizados y la configuración:

• app-config.yaml: Configuración global, integración con bases de datos y variables de entorno.
• plugins/: Extensiones de front end y backend desarrolladas a medida para necesidades específicas de la organización.
• packages/app/: Punto de entrada de la aplicación React, composición de la UI y registro de rutas.
• packages/backend/: Servidor Express, routers de API, lógica de persistencia y workers.
• docs/: Guías de arquitectura, manuales de onboarding y convenciones de código para nuevos ingenieros.