Catalog & Components

The Catalog is your library of reusable components. Understanding components is key to building effective scenarios.

Accessing the Catalog

From the Dashboard, click Catalog to open the component library.

The Catalog Interface

┌─────────────────────────────────────────────────────────────────────┐
│  Catalog                                                             │
│  [Search...]  [☐ Custom only]         [Import] [+ Add] [Export]     │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐│
│  │ Kafka       │  │ PostgreSQL  │  │ Redis       │  │ MinIO       ││
│  │ Helm        │  │ Helm        │  │ Helm        │  │ Helm        ││
│  │             │  │             │  │             │  │             ││
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘│
│                                                                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐│
│  │ Flink       │  │ Elastic     │  │ MongoDB     │  │ My Custom   ││
│  │ Helm        │  │ Helm        │  │ Helm        │  │ Docker      ││
│  │             │  │             │  │             │  │ [Custom]    ││
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘│
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Catalog Actions

Action	Description
Search	Filter components by name
Custom only	Toggle to show only your organization's components
Import	Import components from a JSON file
Add	Create a new component
Export	Download catalog as JSON
Click component	Open component properties modal

Component Cards

Each component card displays:

Name: Component identifier (e.g., "kafka", "my-postgres")
Type: Deployment type badge (Helm, Docker, or Compose)
Custom badge: Indicates a component from your organization's catalog

Click any card to open the component properties modal for viewing or editing.

Component Types

Helm Components

Most infrastructure components use Helm charts for deployment.

Characteristics:

Full Kubernetes deployment with Helm
Configurable via values.yaml
Supports replicas, resources, persistence
Most common for databases and complex services

Examples: PostgreSQL, Kafka, Elasticsearch, Redis, MinIO

Docker Components

Single container deployments for simpler applications.

Characteristics:

One container, one image
Simple configuration via environment variables
Good for custom applications
Lighter weight than Helm

Examples: Custom web apps, simple services, utility containers

Exposed Ports Required for Docker

For Docker components, you must configure Exposed Ports in the Settings tab for other components to reach this service. Without exposed ports, no Kubernetes Service is created and the component won't be accessible via its label (e.g., postgres:5432).

This is different from Helm and Compose, which create services automatically.

Docker Compose Components

Multi-container applications using Docker Compose syntax.

Characteristics:

Multiple related services in one component
Each service becomes a separate Kubernetes Deployment
Named volumes are created as PersistentVolumeClaims
Useful for complex custom stacks

Examples: Multi-service applications, custom architectures

Component Configuration Tabs

When you open a component, you see a modal with multiple tabs. The available tabs depend on the deployment type.

Tabs by Deployment Type

Tab	Docker	Helm	Compose	Description
Overview	✓	✓	✓	Name, description, icon (catalog mode only)
Deployment	✓	✓	✓	Deployment-specific configuration
Settings	✓	-	-	Environment variables, command, exposed ports
Exposed Ports	-	✓	✓	Port forwarding configuration
Resources	✓	✓	✓	CPU, memory, volumes
Files	✓	✓	✓	Configuration files to mount
UI	✓	✓	✓	Terminal and web UI tabs
Readiness	✓	✓	✓	Startup validation checks
Help	✓	✓	✓	Documentation for users

Deployment Tab

The Deployment tab configures how the component is deployed.

Common Fields (All Types)

Field	Description
Component ID	Unique identifier, cannot be changed after creation
Component Label	Label for template variables (e.g., `{{kafka}}`)
Deployment Type	Docker, Helm, or Compose

Docker Deployment

Field	Description
Docker Image	Image name and tag (e.g., `nginx:latest`)

Helm Deployment

Field	Description
Repository URL	HTTP/HTTPS URL or OCI registry (`oci://...`)
Chart Name	Name of the chart
Version	Chart version (leave empty for latest)
Load Chart	Button to verify chart and discover services
Secret Name	Docker registry secret for private images
Helm Values (YAML)	Custom values to pass to the chart

Template Variables

Use {{label}} syntax in Helm values to reference other components. For example: {{postgresql}} resolves to the PostgreSQL service hostname.

Bitnami Charts

Since November 2024, some Bitnami images are no longer available on Docker Hub. If using alternative images, add:

yaml

global:
  security:
    allowInsecureImages: true

Compose Deployment

Field	Description
Docker Compose YAML	Full docker-compose syntax

Key points for Compose:

Each service becomes a separate Kubernetes Deployment
Named volumes are created as PersistentVolumeClaims (1Gi each)
Services are named {{componentLabel}}-servicename
Only pre-built images are supported (no build contexts)

Settings & Exposed Ports Tabs

These tabs vary by deployment type. See Exposed Ports below for Helm and Compose.

Settings (Docker Only)

For Docker components, configure runtime settings.

Environment Variables

Add key-value pairs that will be passed to the container:

Field	Description
Name	Variable name (e.g., `POSTGRES_PASSWORD`)
Value	Variable value (e.g., `secret123`)

Variables can be reordered by dragging.

Container Settings

Field	Description
Command	Override container entrypoint
Arguments	Command arguments

Exposed Ports (Docker)

Critical for inter-component communication. Add ports that other components need to access.

Field	Description
Name	Port identifier (e.g., "postgres", "http")
Port	Container port number

Interactive Containers

For workbench-style containers where users run commands interactively, use ["sleep", "infinity"] as arguments and don't override the command. This keeps the container running while allowing interactive shell access.

Exposed Ports (Helm/Compose)

Exposed Ports make component services accessible from outside the SnapBench platform. This enables integration with:

External SaaS services that need to connect to your lab environment
Local software running on the participant's machine (IDE, database clients, etc.)
External tools that require direct network access to lab resources

When a port is exposed, SnapBench generates a unique external URL that routes traffic to the component inside the Kubernetes cluster.

Field	Description
Name	Port identifier (e.g., "http", "postgres")
Port	Container port number
Public	Expose externally via edge router (for external access)
Pod Selector	For Helm/Compose: which pod to target (substring match)
Container Selector	For multi-container pods: which container

Resources Tab

Configure CPU and memory allocation.

Resource Fields

Field	Description
CPU (millicores)	CPU allocation (1000m = 1 core)
Memory (Mi)	Memory in mebibytes

Automatic Calculation

For Helm and Compose components, resources are automatically extracted from YAML configuration:

Helm: Parsed from resources.requests.cpu and resources.requests.memory
Compose: Parsed from deploy.resources.reservations

When resources are defined in YAML, the fields become read-only and show "(from Helm values)" or "(from Compose)".

Helm Resource Analysis

For Helm charts, click Analyze Chart Resources to:

See resource requirements for each workload
Identify workloads without resource limits
Add resource overrides directly to values YAML

If workloads lack resources, you can:

Enable LimitRange: Automatically assign defaults (500m CPU, 512Mi memory)
Disable Quota: Allow pods without resource limits (use with caution)

Persistent Volumes (Docker Only)

For Docker components, add persistent storage:

Field	Description
Name	Volume identifier
Size (Gi)	Storage size in gibibytes
Mount Path	Where to mount in container

Files Tab

Upload configuration files that will be mounted in containers.

File Configuration

Field	Description
File path and name	Path relative to `/sb/` mount point
File Content	Text content of the file
Target Containers	Which containers receive the file (Compose/Helm)

Files are mounted at /sb/{filename}. For example, a file named config.yaml is accessible at /sb/config.yaml.

Target Containers

For Compose and Helm deployments with multiple containers:

Select which containers should receive each file
Leave all selected to mount in every container

UI Tab

Configure how participants interact with the component.

Terminal Tabs

Provide shell access to containers.

Field	Description
Label	Tab name shown to participants
Working Directory	Initial directory (e.g., `/home`)
Pod Selector	For Helm charts with multiple pods
Container Selector	For pods with multiple containers

Web Interface Tabs

Provide browser access to services.

Field	Description
Label	Tab name shown to participants
Port	Service port number
Path	URL path (e.g., `/`)
Service Name	Kubernetes service name (for Helm)
Namespace	Target namespace (for multi-namespace deployments)

No Tabs = Hidden Component

If no tabs are configured, participants won't see this component in their interface. This is useful for background services.

Readiness Tab

Configure startup validation to ensure the component is fully ready.

Be Conservative with Readiness Timing

Some applications take a long time to start. For example, Elasticsearch can take 2-3 minutes to fully initialize. If your readiness check is too aggressive, the component will be marked as failed before it has a chance to start.

Recommended approach:

Start with generous values (e.g., initialDelaySeconds: 30, periodSeconds: 10)
Test and adjust based on actual startup time
For heavy applications (Elasticsearch, Flink, large databases), use initialDelaySeconds: 60-120

Check Types

Type	Description
HTTP	Check if an HTTP endpoint returns success
TCP	Check if a TCP port is listening

Readiness Fields

Field	Description
Target Service	Service to check (for Helm/Compose)
Port	Port to check
Path	HTTP path (for HTTP checks)
Initial Delay	Seconds to wait before first check
Period	Seconds between checks
Timeout	Seconds to wait for response

Example Initial Delays

These are indicative values — always test and adjust based on your actual environment:

Component	Example Initial Delay
Redis, lightweight services	5-10s
PostgreSQL, MySQL	10-15s
Kafka	15-30s
Elasticsearch, Flink, heavy JVM apps	60-120s

Help Tab

Write documentation to help users understand the component.

Catalog Mode

In catalog mode, you can edit the help content using Markdown:

markdown

# PostgreSQL

## Overview
PostgreSQL is a powerful, open source database.

## Default Credentials
- User: `postgres`
- Password: `postgres`
- Database: `postgres`

## Connecting
Use psql in the terminal:
\`\`\`bash
psql -U postgres
\`\`\`

Studio Mode

In studio mode (when using a component in a scenario), the help is read-only and renders as formatted documentation.

Creating a Component

Step 1: Click Add

Click the + Add button in the catalog toolbar.

Step 2: Choose an ID

Enter a unique identifier (lowercase, hyphens allowed):

Good: my-postgres, kafka-connect, custom-api
Bad: My Component, kafka 2

Step 3: Select Deployment Type

Type	When to Use
Docker	Single container, simple apps
Helm	Complex infrastructure, official charts
Compose	Multi-service custom stacks

Step 4: Configure Each Tab

Work through the tabs to complete configuration:

Deployment: Set image/chart/compose configuration
Settings (Docker): Add environment variables
Exposed Ports (Helm/Compose): Configure port access
Resources: Set CPU and memory
Files: Upload any configuration files
UI: Add terminal and web tabs
Readiness: Configure startup checks
Help: Write user documentation

Step 5: Save

Click Save to add the component to your catalog.

Fine-tuning Components in the Studio

For complex components, a practical workflow is:

Create a basic component in the Catalog with minimal configuration
Add it to a scenario in the Studio
Fine-tune all parameters while testing in a real environment
Save to Catalog using the button in component properties (choose to overwrite or create new)

This approach lets you iterate on component settings with immediate feedback before committing to the catalog.

Managing Components

Editing a Component

Click any component card to open the properties modal, make changes, and save.

Duplicating a Component

Click a component card to open properties
Use the Duplicate action
A copy is created with a new ID
Edit the copy to customize

Deleting a Component

Click a component card to open properties
Use the Delete action
Confirm deletion

Deletion Impact

Deleting a component from the catalog does not affect existing scenarios that use it. Those scenarios keep a copy of the component configuration.

Importing Components

Click Import to upload a JSON file containing component definitions.

Exporting Components

Click Export to download your catalog as JSON for backup or sharing.

Best Practices

Naming Conventions

Pattern	Example	Use
`software`	`postgres`, `kafka`	Default/standard config
`software-variant`	`postgres-15`, `kafka-kraft`	Version-specific
`software-purpose`	`postgres-analytics`	Purpose-specific config

Resource Sizing

Start with minimal resources and increase if needed:

Component Type	Start With	Increase If
Database	250m / 512Mi	Complex queries, large datasets
Message Broker	500m / 1Gi	High throughput, many partitions
Search Engine	500m / 1Gi	Large indices, complex queries
Simple App	100m / 128Mi	Compute-intensive operations

UI Tab Configuration

Always provide at least one access method
Use descriptive tab names ("Kafka Terminal" vs "Terminal")
For web UIs, verify the correct port and path

Troubleshooting

Component Won't Deploy

Symptom	Likely Cause	Solution
ImagePullBackOff	Wrong image name/tag	Verify image exists
CrashLoopBackOff	Configuration error	Check logs, verify config
Pending	Insufficient resources	Reduce resource requests

Tab Not Working

Issue	Check
Terminal won't connect	Pod selector matches actual pod labels
Web UI shows error	Service name, port, and path are correct
"Container not found"	Container name matches pod spec

Component Shows "Failed"

Most Common Cause: Readiness Check Timeout

When a component shows "Failed" status, the most common cause is a readiness check that timed out before the application finished starting.

Symptoms:

Component status shows "Failed"
Pod logs show the application was still initializing
Works when you retry or increase delays

Solutions:

Increase initialDelaySeconds — Give the application more time before first check
Increase the total timeout — More attempts with longer periods
Check resource allocation — Under-resourced components start slower
Verify the health endpoint — Ensure the path and port are correct

Example fix for slow-starting applications:

json

{
  "readinessCheck": {
    "enabled": true,
    "type": "http",
    "httpGet": { "port": 9200, "path": "/_cluster/health" },
    "initialDelaySeconds": 90,
    "periodSeconds": 10,
    "timeoutSeconds": 5
  }
}

Next Steps

Tracks & Scenarios — Organize your scenarios
The Studio — Build scenarios with your components

Catalog & Components ​

Accessing the Catalog ​

The Catalog Interface ​

Catalog Actions ​

Component Cards ​

Component Types ​

Helm Components ​

Docker Components ​

Docker Compose Components ​

Component Configuration Tabs ​

Tabs by Deployment Type ​

Deployment Tab ​

Common Fields (All Types) ​

Docker Deployment ​

Helm Deployment ​

Compose Deployment ​

Settings & Exposed Ports Tabs ​

Settings (Docker Only) ​

Environment Variables ​

Container Settings ​

Exposed Ports (Docker) ​

Exposed Ports (Helm/Compose) ​

Resources Tab ​

Resource Fields ​

Helm Resource Analysis ​

Persistent Volumes (Docker Only) ​

Files Tab ​

File Configuration ​

Target Containers ​

UI Tab ​

Terminal Tabs ​

Web Interface Tabs ​

Readiness Tab ​

Check Types ​

Readiness Fields ​

Example Initial Delays ​

Help Tab ​

Catalog Mode ​

Studio Mode ​

Creating a Component ​

Step 1: Click Add ​

Step 2: Choose an ID ​

Step 3: Select Deployment Type ​

Step 4: Configure Each Tab ​

Step 5: Save ​

Managing Components ​

Editing a Component ​

Duplicating a Component ​

Deleting a Component ​

Importing Components ​

Exporting Components ​

Best Practices ​

Naming Conventions ​

Resource Sizing ​

UI Tab Configuration ​

Troubleshooting ​

Component Won't Deploy ​

Tab Not Working ​

Component Shows "Failed" ​

Next Steps ​

Catalog & Components

Accessing the Catalog

The Catalog Interface

Catalog Actions

Component Cards

Component Types

Helm Components

Docker Components

Docker Compose Components

Component Configuration Tabs

Tabs by Deployment Type

Deployment Tab

Common Fields (All Types)

Docker Deployment

Helm Deployment

Compose Deployment

Settings & Exposed Ports Tabs

Settings (Docker Only)

Environment Variables

Container Settings

Exposed Ports (Docker)

Exposed Ports (Helm/Compose)

Resources Tab

Resource Fields

Helm Resource Analysis

Persistent Volumes (Docker Only)

Files Tab

File Configuration

Target Containers

UI Tab

Terminal Tabs

Web Interface Tabs

Readiness Tab

Check Types

Readiness Fields

Example Initial Delays

Help Tab

Catalog Mode

Studio Mode

Creating a Component

Step 1: Click Add

Step 2: Choose an ID

Step 3: Select Deployment Type

Step 4: Configure Each Tab

Step 5: Save

Managing Components

Editing a Component

Duplicating a Component

Deleting a Component

Importing Components

Exporting Components

Best Practices

Naming Conventions

Resource Sizing

UI Tab Configuration

Troubleshooting

Component Won't Deploy

Tab Not Working

Component Shows "Failed"

Next Steps