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

```bash
./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](#optional-backstage-integration) below

### 2. Create your first service

Using grpcurl (if installed):

```bash
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:

```bash
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

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

### Get a specific entity

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

### Update an entity

```bash
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

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

→ Check DefectDojo: Product deleted automatically!

## Explore the stack

### Check Charybdis logs

```bash
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

```bash
# 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:**
```bash
docker-compose -f docker-compose.demo.yml exec postgres-charybdis \
  psql -U charybdis -d charybdis
```

**Query entities:**
```sql
SELECT id, kind, annotations FROM entities;
```

## Troubleshooting

### Services not starting

Check logs:
```bash
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

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

### Remove all data

```bash
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:

```yaml
# 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](../docs/getting-started.md)
2. **Understand the architecture**: [Architecture](../docs/architecture.md)
3. **Create your own plugin**: [Plugin Guide](../plugins/README.md)

## 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/](../docs/)
- Open an issue on the project's Gitea/GitHub repository

---

**🎉 Welcome to automated DevSecOps orchestration with Charybdis!**