Skip to main content

Custom Catalog Examples

You can populate your DevPortal with custom catalog entities by mounting local catalog files. This is useful for testing, demos, or when you want to manage your catalog locally.

Understanding Catalog Entities​

Backstage catalogs are defined using YAML files (catalog-info.yaml) that describe:

  • Components: Services, libraries, websites
  • APIs: REST APIs, GraphQL, gRPC
  • Resources: Databases, S3 buckets, CDNs
  • Systems: Collections of components
  • Domains: Business domains or product areas

Creating a Catalog File​

Create a catalog-info.yaml file in your project directory:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-service
  description: My awesome microservice
  annotations:
    github.com/project-slug: my-org/my-service
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  lifecycle: production
  owner: team-a
  system: my-system
  providesApis:
    - my-api
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: my-api
  description: REST API for my service
spec:
  type: openapi
  lifecycle: production
  owner: team-a
  system: my-system
  definition: |
    openapi: 3.0.0
    info:
      title: My API
      version: 1.0.0
    paths:
      /health:
        get:
          summary: Health check
          responses:
            '200':
              description: OK

Mounting with Docker Run​

Mount your catalog file and configure it in app-config.local.yaml:

docker run --rm --name devportal -d \
  -p 7007:7007 \
  -v $(pwd)/catalog-info.yaml:/app/catalog-info.yaml:ro \
  -v $(pwd)/app-config.local.yaml:/app/app-config.local.yaml:ro \
  veecode/devportal:latest

In your app-config.local.yaml:

catalog:
  locations:
    - type: file
      target: /app/catalog-info.yaml

Mounting with Docker Compose​

Create a docker-compose.yml:

services:
  devportal:
    image: veecode/devportal:latest
    ports:
      - "7007:7007"
    volumes:
      - ./catalog-info.yaml:/app/catalog-info.yaml:ro
      - ./app-config.local.yaml:/app/app-config.local.yaml:ro

Multiple Catalog Files​

You can mount multiple catalog files using a directory:

mkdir -p catalogs
# Create catalogs/components.yaml, catalogs/apis.yaml, etc.

Then mount the directory:

services:
  devportal:
    image: veecode/devportal:latest
    ports:
      - "7007:7007"
    volumes:
      - ./catalogs:/app/catalogs:ro
      - ./app-config.local.yaml:/app/app-config.local.yaml:ro

In app-config.local.yaml:

catalog:
  locations:
    - type: file
      target: /app/catalogs/components.yaml
    - type: file
      target: /app/catalogs/apis.yaml

Example: Complete System​

Here's a complete example with multiple entity types:

---
apiVersion: backstage.io/v1alpha1
kind: Domain
metadata:
  name: ecommerce
  description: E-commerce domain
spec:
  owner: platform-team
---
apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: checkout-system
  description: Checkout and payment system
spec:
  owner: checkout-team
  domain: ecommerce
---
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  description: Payment processing service
spec:
  type: service
  lifecycle: production
  owner: checkout-team
  system: checkout-system
---
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: payment-db
  description: Payment database
spec:
  type: database
  owner: checkout-team
  system: checkout-system

Remote Catalog Locations​

You can also reference remote catalogs in your app-config.local.yaml:

catalog:
  locations:
    # GitHub repository
    - type: url
      target: https://github.com/my-org/my-repo/blob/main/catalog-info.yaml
    
    # Multiple files from a repo
    - type: url
      target: https://github.com/my-org/my-repo/blob/main/*/catalog-info.yaml
      rules:
        - allow: [Component, API, Resource]

Next Steps​