charybdis/deploy/DEMO.md

Charybdis Demo

See the full flow in action: register a service via one gRPC call and watch DefectDojo auto-provision a product — no YAML files, no manual steps. Optionally, see how Backstage can consume entities from Charybdis in real-time via the YAML adapter.

Prerequisites

• Docker & Docker Compose
• 8GB RAM recommended
• Ports available: 5432, 8080, 8081, 50051 (and 3000 if using Backstage)

Quick Start (5 minutes)

1. Start the demo stack

./demo.sh

This will start:

• ✅ Charybdis (gRPC on :50051, YAML adapter on :8081)
• ✅ DefectDojo (UI on :8080)
• ✅ PostgreSQL instances for each service
• ℹ️ Backstage (UI on :3000) — optional, see Backstage Integration below

2. Create your first service

Using grpcurl (if installed):

grpcurl -plaintext -d '{
  "entity": {
    "kind": "Component",
    "component_metadata": {
      "name": "payment-api",
      "description": "Payment processing service",
      "labels": {
        "team": "payments",
        "env": "production"
      },
      "tags": ["api", "critical"]
    },
    "component_spec": {
      "type": "service",
      "lifecycle": "production",
      "owner": "team-payments"
    }
  }
}' localhost:50051 charybdis.entities.EntityService/CreateEntity

Or using the included grpcurl container:

docker-compose -f docker-compose.demo.yml run --rm grpcurl \
  -plaintext -d '{
    "entity": {
      "kind": "Component",
      "component_metadata": {
        "name": "payment-api",
        "description": "Payment processing service"
      },
      "component_spec": {
        "type": "service",
        "lifecycle": "production",
        "owner": "team-payments"
      }
    }
  }' charybdis:50051 charybdis.entities.EntityService/CreateEntity

3. See the magic happen! ✨

In DefectDojo (http://localhost:8080):

• Login: admin / admin
• Go to "Products"
• You'll see "payment-api" automatically created! 🎉

In Charybdis (via gRPC):

• Query the entity back — it now has annotations:
  • defectdojo.com/product-id
  • defectdojo.com/engagement-id (if auto-create enabled)

In the YAML adapter (http://localhost:8081):

• Visit http://localhost:8081/yaml/locations — entities are served in Backstage-compatible YAML format
• Any Backstage instance pointed at this URL will pick up entities automatically

What just happened?

1. You created a Component entity in Charybdis (gRPC API)
2. Charybdis stored it in PostgreSQL
3. Event published: EntityCreated(Component)
4. DefectDojo plugin received the event
5. Plugin created a Product in DefectDojo via API
6. Plugin stored the product_id in entity annotations
7. Entity is now queryable via gRPC and available via YAML adapter

30 seconds instead of 30 minutes of manual provisioning — no YAML files, no manual tool setup.

Try more operations

List all entities

grpcurl -plaintext -d '{}' localhost:50051 \
  charybdis.entities.EntityService/ListEntities

Get a specific entity

grpcurl -plaintext -d '{"id": "YOUR_ENTITY_ID"}' localhost:50051 \
  charybdis.entities.EntityService/GetEntity

Update an entity

grpcurl -plaintext -d '{
  "id": "YOUR_ENTITY_ID",
  "entity": {
    "kind": "Component",
    "component_metadata": {
      "name": "payment-api",
      "description": "Updated description"
    }
  }
}' localhost:50051 charybdis.entities.EntityService/UpdateEntity

→ Check DefectDojo: Product description updated automatically!

Delete an entity

grpcurl -plaintext -d '{"id": "YOUR_ENTITY_ID"}' localhost:50051 \
  charybdis.entities.EntityService/DeleteEntity

→ Check DefectDojo: Product deleted automatically!

Explore the stack

Check Charybdis logs

docker-compose -f docker-compose.demo.yml logs -f charybdis

You'll see:

• Entity CRUD operations
• Event dispatching
• Plugin execution
• DefectDojo API calls

Check DefectDojo

Open http://localhost:8080

• Login: admin / admin
• Products: See auto-created products
• Engagements: See auto-created CI/CD engagements

Check the YAML Adapter

# List all entity locations (Backstage-compatible format)
curl http://localhost:8081/yaml/locations

This endpoint serves entities as Backstage-compatible YAML — useful for Backstage integration or any tool that consumes this format.

Access databases

Charybdis database:

docker-compose -f docker-compose.demo.yml exec postgres-charybdis \
  psql -U charybdis -d charybdis

Query entities:

SELECT id, kind, annotations FROM entities;

Troubleshooting

Services not starting

Check logs:

docker-compose -f docker-compose.demo.yml logs

DefectDojo API token issue

Manually get a token:

1. Open http://localhost:8080
2. Login: admin / admin
3. Go to Settings → API Key
4. Copy the token
5. Update .env: DEFECTDOJO_API_TOKEN=your-token
6. Restart: docker-compose -f docker-compose.demo.yml restart charybdis

Port conflicts

If ports are already in use, edit docker-compose.demo.yml to change:

• 3000:3000 → 3001:3000 (Backstage)
• 8080:8080 → 8082:8080 (DefectDojo)
• etc.

Clean up

Stop services

docker-compose -f docker-compose.demo.yml down

Remove all data

docker-compose -f docker-compose.demo.yml down -v

Optional: Backstage Integration

If you use Backstage, point it at the Charybdis YAML adapter to replace static catalog-info.yaml files:

# backstage app-config.yaml
catalog:
  locations:
    - type: url
      target: http://charybdis:8081/yaml/locations
      rules:
        - allow: [Component, System, Service, API, User, Group]

Backstage will discover all entities from Charybdis automatically. See the docker-compose.demo.yml file for the commented-out Backstage service if you want to run it as part of the demo stack.

Next Steps

1. Read the docs: Getting Started
2. Understand the architecture: Architecture
3. Create your own plugin: Plugin Guide

Demo Architecture

┌─────────────┐
│   Client    │ (grpcurl / CI/CD)
│  (gRPC)     │
└──────┬──────┘
       │
       ▼
┌─────────────────────────────────────┐
│          Charybdis                  │
│  ┌─────────────┐  ┌──────────────┐ │
│  │ gRPC API    │  │ YAML Adapter │ │
│  │  :50051     │  │   :8081      │ │
│  └──────┬──────┘  └──────┬───────┘ │
│         │                │          │
│  ┌──────▼────────────────▼───────┐ │
│  │     Entity Repository         │ │
│  │      (PostgreSQL)              │ │
│  └──────┬────────────────────────┘ │
│         │                           │
│  ┌──────▼────────┐                 │
│  │  Event Bus    │                 │
│  └──────┬────────┘                 │
│         │                           │
│  ┌──────▼────────────────┐         │
│  │  Plugin Dispatcher    │         │
│  │  ┌─────────────────┐  │         │
│  │  │ DefectDojo      │  │         │
│  │  │ Plugin          │  │         │
│  │  └─────────────────┘  │         │
│  └───────────────────────┘         │
└──────┬──────────────┬───────────────┘
       │              │
       ▼              ▼ (YAML Adapter)
┌──────────────┐  ┌────────────────────┐
│  DefectDojo  │  │  Backstage / Any   │
│    :8080     │  │  compatible UI     │
└──────────────┘  └────────────────────┘

Support

• Documentation: ../docs/
• Open an issue on the project's Gitea/GitHub repository

---

🎉 Welcome to automated DevSecOps orchestration with Charybdis!