Backstage es un framework de código abierto, creado por Spotify y mantenido en la CNCF, para construir portales internos de desarrollador: un catálogo de servicios, plantillas para crear proyectos nuevos y documentación técnica en un mismo sitio. En este tutorial generarás una aplicación Backstage en Ubuntu 24.04, la ejecutarás en modo desarrollo, la conectarás a PostgreSQL para que los datos persistan y registrarás un servicio propio en el catálogo con un archivo catalog-info.yaml.

Requisitos previos

  • Un servidor con Ubuntu 24.04 LTS, por ejemplo un VPS de CubePath, con al menos 6 GB de RAM y 20 GB de disco libres. La instalación de dependencias y la compilación de TypeScript consumen bastante memoria.
  • Un usuario no root con privilegios sudo.
  • Acceso SSH desde tu ordenador, para abrir un túnel hacia la interfaz web.
  • Opcional: una cuenta de GitHub y un repositorio donde guardar el catalog-info.yaml de un servicio.

Paso 1: Instalar Node.js, Yarn y las herramientas de compilación

Backstage requiere una versión LTS activa de Node.js (22 o 24). La versión de los repositorios de Ubuntu 24.04 es más antigua, así que usarás el repositorio de NodeSource. Instala primero las dependencias y las herramientas de compilación que necesitan algunos módulos nativos:

sudo apt update
sudo apt install ca-certificates curl gnupg git build-essential python3

Descarga la clave de NodeSource y añade el repositorio de Node.js 24:

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_24.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list

Instala Node.js:

sudo apt update
sudo apt install nodejs

Backstage usa Yarn 4, que se gestiona con Corepack, incluido en Node.js 24. Actívalo:

sudo corepack enable

Comprueba las versiones:

node --version
yarn --version

v24.x.x
4.x.x

Si yarn --version te pide confirmación para descargar Yarn, responde Y.

Paso 2: Crear la aplicación Backstage

El generador oficial @backstage/create-app crea un monorepo con el frontend (packages/app), el backend (packages/backend) y la configuración. Ejecútalo desde tu directorio personal:

cd ~
npx @backstage/create-app@latest

Confirma la descarga del paquete con y y escribe el nombre de la aplicación, por ejemplo mi-portal. El generador copia la plantilla, instala las dependencias y compila TypeScript, lo que tarda varios minutos. Al final verás:

Successfully created mi-portal

Los archivos más importantes del proyecto son:

  • app-config.yaml: configuración principal (URLs, base de datos, integraciones, catálogo).
  • app-config.production.yaml: valores que sobrescriben la configuración en producción.
  • examples/: entidades y una plantilla de ejemplo que se cargan en el catálogo.
  • packages/app y packages/backend: el frontend React y el backend Node.js.

Paso 3: Arrancar Backstage en modo desarrollo

Arranca el frontend y el backend a la vez:

cd ~/mi-portal
yarn start

Cuando veas Rspack compiled successfully, el frontend escucha en el puerto 3000 y el backend en el 7007, ambos solo en localhost. Para abrirlo desde tu navegador sin exponer los puertos, crea un túnel SSH desde tu ordenador en otra terminal:

ssh -L 3000:localhost:3000 -L 7007:localhost:7007 your_user@your_server_ip

Abre http://localhost:3000 en tu navegador. En modo desarrollo Backstage usa un proveedor de acceso de invitado; pulsa Enter en la pantalla de inicio de sesión y verás el catálogo con los componentes de ejemplo.

Comprueba también el backend desde el servidor, en una segunda sesión SSH:

curl http://localhost:7007/.backstage/health/v1/readiness

{"status":"ok"}

Detén la aplicación con Ctrl+C antes de seguir. Por defecto usa una base de datos SQLite en memoria, así que todo lo que registres se pierde al pararla. Lo resolverás en el siguiente paso.

Paso 4: Conectar Backstage a PostgreSQL

Instala PostgreSQL 16 desde los repositorios de Ubuntu:

sudo apt install postgresql

Crea un rol para Backstage. Necesita el permiso CREATEDB porque cada plugin del backend crea su propia base de datos (backstage_plugin_catalog, backstage_plugin_scaffolder, etc.). Sustituye your_strong_password por una contraseña segura:

sudo -u postgres psql -c "CREATE ROLE backstage WITH LOGIN CREATEDB PASSWORD 'your_strong_password';"

CREATE ROLE

Abre la configuración de la aplicación:

nano ~/mi-portal/app-config.yaml

Busca el bloque backend.database, que por defecto usa SQLite en memoria:

  database:
    client: better-sqlite3
    connection: ':memory:'

Sustitúyelo por la conexión a PostgreSQL, leyendo los datos de variables de entorno para no dejar la contraseña en el archivo:

  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: ${POSTGRES_PORT}
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}

Exporta las variables en la sesión y arranca de nuevo:

export POSTGRES_HOST=127.0.0.1
export POSTGRES_PORT=5432
export POSTGRES_USER=backstage
read -rs POSTGRES_PASSWORD && export POSTGRES_PASSWORD
yarn start

Escribe la contraseña del rol cuando read la pida (no se muestra en pantalla). Cuando la aplicación arranque, comprueba desde otra sesión que los plugins han creado sus bases de datos:

sudo -u postgres psql -c "\l" | grep backstage_plugin

 backstage_plugin_auth       | backstage | UTF8 | ...
 backstage_plugin_catalog    | backstage | UTF8 | ...
 backstage_plugin_scaffolder | backstage | UTF8 | ...
 ...

A partir de ahora, lo que registres en el catálogo se mantiene entre reinicios.

El catálogo de software es el núcleo de Backstage: cada servicio, API, biblioteca o sitio web se describe con un archivo catalog-info.yaml que vive en su propio repositorio. Crea este archivo en la raíz del repositorio de uno de tus servicios:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: servicio-pagos
  description: Servicio de procesamiento de pagos
  annotations:
    github.com/project-slug: your_org/servicio-pagos
  tags:
    - python
    - pagos
spec:
  type: service
  lifecycle: production
  owner: guests

Los campos clave son:

  • metadata.name: identificador único dentro del catálogo (minúsculas, números y guiones).
  • spec.type: tipo de componente, por ejemplo service, website o library.
  • spec.lifecycle: estado, por ejemplo experimental, production o deprecated.
  • spec.owner: grupo o usuario responsable. guests es el grupo que crean los datos de ejemplo; cámbialo por un grupo real cuando definas tu organización.

Sube el archivo al repositorio. En Backstage, ve a Create (o Crear) y pulsa Register Existing Component. Pega la URL del archivo, por ejemplo https://github.com/your_org/servicio-pagos/blob/main/catalog-info.yaml, pulsa Analyze y después Import.

Vuelve a la página Catalog: servicio-pagos aparece como componente de tipo service. Si abres su ficha verás el propietario, las etiquetas y un enlace al repositorio.

Paso 6: Añadir un token de GitHub

Sin autenticación, la API de GitHub limita mucho el número de peticiones y Backstage no puede leer repositorios privados. La plantilla ya incluye la integración en app-config.yaml:

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

Crea en GitHub un token de acceso personal fine-grained con permiso de solo lectura sobre el contenido (Contents: Read-only) de los repositorios que vayas a registrar. Expórtalo antes de arrancar Backstage:

read -rs GITHUB_TOKEN && export GITHUB_TOKEN
yarn start

Comprueba que funciona registrando el catalog-info.yaml de un repositorio privado con el mismo procedimiento del paso 5.

Solución de problemas

yarn start se queda sin memoria o el proceso muere al compilar. Backstage necesita varios GB de RAM en desarrollo. Aumenta la memoria del servidor o añade swap.

El backend falla con password authentication failed for user "backstage". La variable POSTGRES_PASSWORD no coincide con la del rol. Cámbiala con sudo -u postgres psql -c "ALTER ROLE backstage PASSWORD 'your_strong_password';".

Error permission denied to create database. El rol no tiene CREATEDB. Añádelo con sudo -u postgres psql -c "ALTER ROLE backstage CREATEDB;".

El registro de un componente falla con un error 404 o de límite de peticiones. Comprueba que la URL apunta al archivo (con /blob/) y que GITHUB_TOKEN está exportado en la misma sesión donde ejecutas yarn start.

Conclusión

Tienes una aplicación Backstage en Ubuntu 24.04 conectada a PostgreSQL, con la integración de GitHub y tu primer servicio en el catálogo. Como siguientes pasos puedes configurar un proveedor de autenticación real (GitHub u OIDC) en lugar del acceso de invitado, crear plantillas del Scaffolder a partir de examples/template/, y preparar el despliegue en producción con yarn build:backend y el Dockerfile incluido en packages/backend.