charybdis/docs/getting-started.md

Getting Started with Charybdis

This guide will get you from zero to a running Charybdis instance in minutes. By the end, you'll have a working software catalog that can register services via gRPC, ingest scan results, and auto-trigger integrations via event-driven plugins.

Prerequisites

• Rust - 1.70 or later (install)
• PostgreSQL - 14 or later
• grpcurl - For testing (optional, install)

Installation

Option 1: From Source

# Clone the repository
git clone https://github.com/charybdis-catalog/charybdis.git
cd charybdis

# Build
cargo build --release

# The binary will be at target/release/charybdis

Option 2: Docker (Coming Soon)

docker pull charybdis/charybdis:latest

Quick Start

Step 1: Start PostgreSQL

Using Docker:

docker run -d \
  --name charybdis-postgres \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  postgres:15

Or use an existing PostgreSQL instance.

Step 2: Configure Charybdis

Recommended: Use config.toml

Copy the example configuration:

cp config.toml.example config.toml

Edit config.toml and set your database URL:

[database]
url = "${DATABASE_URL}"

Set the environment variable:

export DATABASE_URL="postgresql://postgres:mysecretpassword@localhost:5432/postgres"

Alternative: Environment Variables Only (Legacy)

If you prefer environment variables:

# Database
export DATABASE_URL="postgresql://postgres:mysecretpassword@localhost:5432/postgres"

# Disable security for quick start
export SECURITY_MTLS_ENABLED=false
export SECURITY_RBAC_ENABLED=false

# Logging
export RUST_LOG=info,charybdis=debug

Step 3: Run Charybdis

cargo run

You should see:

INFO  charybdis: Database ready
INFO  charybdis: Event bus started successfully
INFO  charybdis: EntityService server listening on [::1]:50051

Step 4: Verify It's Working

Test with grpcurl:

# List available services
grpcurl -plaintext localhost:50051 list

# Output:
# charybdis.entities.EntityService
# grpc.reflection.v1.ServerReflection

Congratulations! Charybdis is running! 🎉

Creating Your First Entity

Using grpcurl

Create a service entity:

grpcurl -plaintext \
  -d '{
    "entity": {
      "kind": "Service",
      "service_metadata": {
        "name": "payment-service",
        "namespace": "production",
        "description": "Core payment processing service"
      }
    }
  }' \
  localhost:50051 charybdis.entities.EntityService/CreateEntity

Response:

{
  "entity": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "kind": "Service",
    "serviceMetadata": {
      "name": "payment-service",
      "namespace": "production",
      "description": "Core payment processing service"
    },
    "createdAt": "2025-11-04T10:00:00Z",
    "updatedAt": "2025-11-04T10:00:00Z"
  }
}

List All Entities

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

Get Entity by ID

grpcurl -plaintext \
  -d '{"id": "550e8400-e29b-41d4-a716-446655440000"}' \
  localhost:50051 charybdis.entities.EntityService/GetEntity

Entity Types

Charybdis supports three main entity types:

Service

Individual microservices or applications:

grpcurl -plaintext -d '{
  "entity": {
    "kind": "Service",
    "service_metadata": {
      "name": "user-api",
      "namespace": "production",
      "description": "User management API"
    }
  }
}' localhost:50051 charybdis.entities.EntityService/CreateEntity

System

Collections of related services:

grpcurl -plaintext -d '{
  "entity": {
    "kind": "System",
    "system_metadata": {
      "name": "payment-system",
      "namespace": "production",
      "description": "Complete payment processing system"
    }
  }
}' localhost:50051 charybdis.entities.EntityService/CreateEntity

Component

Reusable components or libraries:

grpcurl -plaintext -d '{
  "entity": {
    "kind": "Component",
    "component_spec": {
      "type": "library",
      "lifecycle": "production",
      "owner": "platform-team"
    },
    "component_metadata": {
      "name": "auth-library",
      "namespace": "shared",
      "description": "Shared authentication library"
    }
  }
}' localhost:50051 charybdis.entities.EntityService/CreateEntity

Adding Metadata

Entities support rich metadata:

grpcurl -plaintext -d '{
  "entity": {
    "kind": "Service",
    "service_metadata": {
      "name": "payment-service",
      "namespace": "production",
      "description": "Payment processing",
      "labels": {
        "team": "payments",
        "tier": "critical"
      },
      "links": [
        {
          "url": "https://dashboard.company.com/payments",
          "title": "Dashboard",
          "icon": "dashboard"
        }
      ],
      "tags": ["payments", "pci-compliant", "critical"]
    },
    "annotations": {
      "github.com/repo-slug": "myorg/payment-service",
      "pagerduty.com/service-id": "PXYZ123"
    }
  }
}' localhost:50051 charybdis.entities.EntityService/CreateEntity

Integrating with CI/CD

Example: GitHub Actions

Create a workflow to register services automatically:

name: Register Service
on:
  push:
    branches: [main]

jobs:
  register:
    runs-on: ubuntu-latest
    steps:
      - name: Register in Charybdis
        run: |
          grpcurl -plaintext \
            -d '{
              "entity": {
                "kind": "Service",
                "service_metadata": {
                  "name": "${{ github.event.repository.name }}",
                  "namespace": "production",
                  "description": "${{ github.event.repository.description }}"
                },
                "annotations": {
                  "github.com/repo-slug": "${{ github.repository }}"
                }
              }
            }' \
            your-charybdis-host:50051 \
            charybdis.entities.EntityService/CreateEntity

Example: GitLab CI

register_service:
  stage: deploy
  script:
    - |
      grpcurl -plaintext \
        -d "{
          \"entity\": {
            \"kind\": \"Service\",
            \"service_metadata\": {
              \"name\": \"${CI_PROJECT_NAME}\",
              \"namespace\": \"${CI_ENVIRONMENT_NAME}\"
            }
          }
        }" \
        your-charybdis-host:50051 \
        charybdis.entities.EntityService/CreateEntity

Enabling Security

For production use, enable mTLS and RBAC:

Step 1: Generate Certificates

# Use the provided test script
./test-mtls-rbac.sh

This creates:

• certs/ca.pem - Certificate Authority
• certs/server-cert.pem / server-key.pem - Server certificate
• certs/admin-cert.pem / admin-key.pem - Admin client certificate

Step 2: Enable Security

export SECURITY_MTLS_ENABLED=true
export SECURITY_MTLS_SERVER_CERT=./certs/server-cert.pem
export SECURITY_MTLS_SERVER_KEY=./certs/server-key.pem
export SECURITY_MTLS_CLIENT_CA=./certs/ca.pem
export SECURITY_RBAC_ENABLED=true

Step 3: Test with mTLS

grpcurl \
  -cacert certs/ca.pem \
  -cert certs/admin-cert.pem \
  -key certs/admin-key.pem \
  -d '{}' \
  localhost:50051 charybdis.entities.EntityService/ListEntities

See the Security Guide for detailed configuration.

Backstage Migration (Optional)

If you currently use Backstage and want to migrate gradually, the built-in YAML adapter serves entities in Backstage format:

# backstage app-config.yaml
catalog:
  locations:
    - type: url
      target: http://your-charybdis-host:8080/yaml/locations
      rules:
        - allow: [Component, System, Service]

Backstage will automatically discover and import entities from Charybdis. You can run both in parallel — entities managed via gRPC are immediately visible in Backstage.

Troubleshooting

Port Already in Use

Error: transport error

Solution: Check if another process is using port 50051:

lsof -ti:50051

Kill the process or change the port:

export GRPC_PORT=50052

Database Connection Failed

Error: password authentication failed

Solution: Verify your DATABASE_URL:

# Test connection
psql "$DATABASE_URL" -c "SELECT 1;"

Permission Denied (with security enabled)

Code: PermissionDenied
Message: Role 'X' does not have permission 'Y'

Solution: Check your certificate and role mappings. See Security Guide.

Next Steps

Now that you have Charybdis running:

1. Learn about Core Concepts — entities, vulnerabilities, events
2. Read the Vision & Roadmap — where Charybdis is going
3. Configure Security for production (mTLS + RBAC)
4. Explore Plugins for external integrations

Configuration

Charybdis supports two configuration methods:

1. Configuration File (Recommended)

Use config.toml for structured configuration:

# config.toml
[server]
grpc_host = "[::1]"
grpc_port = 50051

[database]
url = "${DATABASE_URL}"  # Environment variable substitution

[security.mtls]
enabled = false

[security.rbac]
enabled = false

[telemetry]
service_name = "charybdis"
environment = "development"
enable_console = true

Benefits:

• ✅ Organized by section (server, database, security, telemetry, plugins)
• ✅ Environment variable substitution with ${VAR_NAME}
• ✅ Comments and documentation inline
• ✅ Easy to version control (excluding secrets)
• ✅ No need to export dozens of environment variables

Using Environment Variables in config.toml:

[database]
url = "${DATABASE_URL}"  # Will be substituted at runtime

[plugins.defectdojo]
api_key = "${DEFECTDOJO_API_KEY}"  # Secrets stay in environment

Then set only the secrets:

export DATABASE_URL="postgresql://..."
export DEFECTDOJO_API_KEY="secret-key"

2. Environment Variables (Legacy)

If config.toml is not found, Charybdis falls back to environment variables:

Variable	Default	Description
DATABASE_URL	(required)	PostgreSQL connection string
GRPC_HOST	[::1]	gRPC server bind address
GRPC_PORT	50051	gRPC server port
RUST_LOG	info	Logging level
SECURITY_MTLS_ENABLED	false	Enable mTLS authentication
SECURITY_RBAC_ENABLED	false	Enable RBAC authorization
OTEL_ENABLE_CONSOLE	true	Enable console logging
OTEL_SERVICE_NAME	charybdis	Service name for telemetry

Configuration File Locations

Charybdis looks for configuration files in this order:

1. ./config.toml (current directory)
2. ./charybdis.toml
3. /etc/charybdis/config.toml (Linux/Unix)

If none are found, it uses environment variables.

See config.toml.example for a complete configuration template with all options documented.

---

Need help? Check the troubleshooting guide or open an issue.