--- title: "Cómo instalar Backstage en Ubuntu 24.04 con PostgreSQL" description: "Crea un portal de desarrollador con Backstage en Ubuntu 24.04: instala Node.js, genera la aplicación, conéctala a PostgreSQL y registra servicios." category: "Ingeniería de Plataformas" language: es source: https://cubepath.com/es/docs/ingeniería-de-plataformas/instalacion-de-backstage-portal-de-desarrollador updated: 2026-09-25 --- # Cómo instalar Backstage en Ubuntu 24.04 con PostgreSQL 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: ```bash 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: ```bash 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: ```bash sudo apt update sudo apt install nodejs ``` Backstage usa Yarn 4, que se gestiona con Corepack, incluido en Node.js 24. Actívalo: ```bash sudo corepack enable ``` Comprueba las versiones: ```bash node --version yarn --version ``` ```output 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: ```bash 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: ```output 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: ```bash 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: ```bash 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: ```bash curl http://localhost:7007/.backstage/health/v1/readiness ``` ```output {"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: ```bash 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: ```bash sudo -u postgres psql -c "CREATE ROLE backstage WITH LOGIN CREATEDB PASSWORD 'your_strong_password';" ``` ```output CREATE ROLE ``` Abre la configuración de la aplicación: ```bash nano ~/mi-portal/app-config.yaml ``` Busca el bloque `backend.database`, que por defecto usa SQLite en memoria: ```yaml 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: ```yaml 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: ```bash 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: ```bash sudo -u postgres psql -c "\l" | grep backstage_plugin ``` ```output 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. ## Paso 5: Registrar un servicio en el catálogo 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: ```yaml 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`: ```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: ```bash 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. > Importante: no escribas contraseñas ni tokens directamente en `app-config.yaml`. El archivo forma parte del repositorio de tu portal y acabaría en el historial de Git. ## 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`.