Skip to content

Service Catalog

A simple, open source service catalog for teams who don't want the complexity of Backstage.

Problem

  • Backstage is too complex (requires dedicated team, TypeScript expertise)
  • Commercial alternatives (Port, Cortex, OpsLevel) are SaaS-only and expensive
  • No simple self-hosted option exists

Solution

A lightweight service catalog that:

  • Reads catalog-info.yaml from git repos (GitHub, GitLab, Forgejo)
  • Allows manual entries for non-git services (SaaS tools, external APIs)
  • Tracks dependencies between services
  • Links to docs, dashboards, runbooks
  • Single binary deployment

Tech Stack

  • Backend: Go
  • Frontend: HTMX + minimal CSS
  • Database: SQLite (default) or PostgreSQL
  • Deployment: Single binary / Docker image

Features (MVP)

Feature Description
Service list Searchable list of all services
Dependency graph Visualize who calls what
Ownership Team/owner assignment
Links Docs, repo, dashboard, runbook URLs
Tags Tech stack, lifecycle stage
Git sync Auto-import from repos
Manual entries Add services not in git

Architecture

The service catalog runs in Kubernetes and watches configured git repos for service metadata.

App Configuration (ConfigMap)

apiVersion: v1
kind: ConfigMap
metadata:
  name: service-catalog-config
  namespace: service-catalog
data:
  config.yaml: |
    sources:
      - url: https://github.com/minnova-io/oracle
        branch: main
        file: catalog.yaml
      - url: https://github.com/minnova-io/infra
        branch: main
        file: catalog.yaml
      - url: https://github.com/minnova-io/niobe
        branch: main
        file: catalog.yaml

    sync:
      interval: 5m

    database:
      driver: postgres  # or sqlite
      dsn: ${DATABASE_URL}

Entity Types

The catalog supports different entity types:

Type Description
service Backend services, APIs, applications
resource Databases, caches, queues, storage
api External APIs (Stripe, Twilio, etc.)
library Shared libraries, packages
website Frontend apps, marketing sites

Catalog Metadata (in each repo)

Each repo contains a catalog.yaml file with one or more entities:

# catalog.yaml
name: oracle
type: service
description: Internal AI assistant
owner: platform-team
tags:
  - go
  - ai
  - internal
lifecycle: production # development | staging | production | deprecated
dependencies:
  - service:postgres
  - service:user-api
  - resource:redis
  - api:openai
links:
  docs: https://knowledge-base.minnova.io/projects/oracle
  dashboard: https://grafana.minnova.io/d/oracle

---
name: oracle-worker
type: service
description: Background job processor for Oracle
owner: platform-team
dependencies:
  - service:oracle
  - resource:redis

# infra repo - catalog.yaml
name: postgres
type: resource
description: Primary PostgreSQL database
owner: platform-team
tags:
  - database
  - postgresql

---
name: redis
type: resource
description: Redis cache and queue
owner: platform-team

Dependency References

Dependencies use the format type:name and resolve across all repos:

dependencies:
  - service:postgres # links to postgres service
  - resource:s3-bucket # links to s3-bucket resource
  - api:stripe # links to stripe api (or shows as external)

The catalog loads all configured repos into one unified view - repo boundaries don't matter for references.

Future Features

  • Health status (ping endpoints)
  • Tech radar integration
  • Scorecards (production readiness checks)
  • API documentation rendering
  • MkDocs integration (render docs inline)
  • OIDC authentication
  • RBAC for editing

Why Open Source

There's a gap in the OSS community for a simple service catalog. This could help small-medium teams who need visibility into their services without enterprise complexity.

Status

Planning - Not started yet