SolaceLabs/solace-agent-mesh-docker-quickstartPublic

NotificationsYou must be signed in to change notification settings
Fork1
Star1

You must be signed in to change notification settings

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.env.template		.env.template
.gitignore		.gitignore
README.md		README.md
compose.broker.yml		compose.broker.yml
compose.database.yml		compose.database.yml
compose.storage.yml		compose.storage.yml
compose.yml		compose.yml
setup.sh		setup.sh

Repository files navigation

SAM (Solace Agent Mesh) - Docker Based Deployment

Flexible Docker Compose / Podman Compose deployment for SAM that allows you to bring your own infrastructure (broker, database, storage) or use fully managed services.

Prerequisites

Image Pull Authentication

SAM container images require authentication. Choose one of the following options:

Option 1: Use Solace Cloud Image Pull Secret (Recommended)

Download the image pull secret from Solace Cloud:
- Follow the instructions at:Download Image Pull Secret
- You'll receive a Kubernetes secret YAML file (e.g.,gcr-reg-secret.yaml)

Configure your container engine with the credentials:

For Docker:

# Backup existing Docker configcp~/.docker/config.json~/.docker/config.json.backup# Extract and merge the Solace credentialsgrep'\.dockerconfigjson:' gcr-reg-secret.yaml| awk'{print $2}'| base64 -d> /tmp/solace-creds.jsonjq -s'.[0] * .[1]'~/.docker/config.json /tmp/solace-creds.json>~/.docker/config.json.newmv~/.docker/config.json.new~/.docker/config.jsonrm /tmp/solace-creds.json

For Podman:

# Podman uses the same config format, just in a different locationmkdir -p${XDG_RUNTIME_DIR}/containerscp${XDG_RUNTIME_DIR}/containers/auth.json${XDG_RUNTIME_DIR}/containers/auth.json.backup2>/dev/null||true# Extract and merge the Solace credentialsgrep'\.dockerconfigjson:' gcr-reg-secret.yaml| awk'{print $2}'| base64 -d> /tmp/solace-creds.json# If auth.json exists, merge; otherwise, just copyif [-f"${XDG_RUNTIME_DIR}/containers/auth.json" ];then    jq -s'.[0] * .[1]'${XDG_RUNTIME_DIR}/containers/auth.json /tmp/solace-creds.json> /tmp/auth.json.new    mv /tmp/auth.json.new${XDG_RUNTIME_DIR}/containers/auth.jsonelse    mv /tmp/solace-creds.json${XDG_RUNTIME_DIR}/containers/auth.jsonfirm -f /tmp/solace-creds.json

Option 2: Use Your Own Container Registry

If you've copied SAM images to your own registry:

Authenticate with your registry:

# For Docker:docker login your-registry.example.com# For Podman:podman login your-registry.example.com# Or for specific registries:docker login gcr.io/your-project# or: podman login gcr.io/your-projectdocker login ghcr.io# or: podman login ghcr.io

Update image references in.env:

SAM_IMAGE=your-registry.example.com/sam:latestSAM_DEPLOYER_IMAGE=your-registry.example.com/sam-deployer:latest

Note: Docker/Podman Compose doesn't support per-service pull secrets. All authentication is handled at the container engine level:

Docker:~/.docker/config.json
Podman:${XDG_RUNTIME_DIR}/containers/auth.json (typically/run/user/<uid>/containers/auth.json)

Quick Start

Interactive Setup (Recommended)

Run the setup wizard to configure your deployment:

./setup.sh

The wizard will:

Ask about your deployment mode (Full Managed / BYO Everything / Custom)
Collect required LLM API credentials
Generate.env file with appropriate defaults
Create convenience scripts (start.sh,stop.sh,logs.sh)
Show you the exact command to start SAM

Manual Setup

If you prefer to configure manually:

# 1. Copy templatecp .env.template .env# 2. Edit configuration (at minimum, set SAM_LLM_API_KEY)nano .env# 3. Deploy based on your needs:# BYO Everything (Minimal)docker compose -f compose.yml up -d# Or with Podman: podman compose -f compose.yml up -d# Full Managed Stack (Local Development)docker compose -f compose.yml -f compose.broker.yml -f compose.database.yml -f compose.storage.yml up -d# Mix and Match (example: managed broker + database only)docker compose -f compose.yml -f compose.broker.yml -f compose.database.yml up -d

Architecture

SAM consists of:

SAM Application - Web UI (port 8000) and orchestration engine
Deployer Service - Dynamic agent deployment via container-in-container (Docker-in-Docker or Podman-in-Podman)
Solace Broker - Event mesh for agent communication (managed or external)
PostgreSQL - Session and metadata storage (managed or external)
S3 Storage - Artifact storage via SeaweedFS or external S3 (managed or external)

Each component can bemanaged (deployed by compose) orexternal (bring your own).

How It Works

The deployment usescompose file stacking - you combine multiple compose files to build your deployment:

compose.yml - Base file with SAM only, assumes BYO everything
compose.broker.yml - Add managed Solace PubSub+ broker
compose.database.yml - Add managed PostgreSQL
compose.storage.yml - Add managed S3 storage (SeaweedFS)

Stack them together using multiple-f flags:

docker compose -f compose.yml -f compose.broker.yml -f compose.database.yml up -d# Or with Podman:podman compose -f compose.yml -f compose.broker.yml -f compose.database.yml up -d

Benefits:

✅ No templating tools required - pure compose
✅ Services are only included when needed
✅ Easy to understand and debug
✅ Standard compose approach
✅ Works with both Docker and Podman

Deployment Profiles

Bring Your Own Broker

# .env configurationEXTERNAL_BROKER_URL=tcp://broker.example.com:55555EXTERNAL_BROKER_URL_WS=ws://broker.example.com:8008EXTERNAL_BROKER_USERNAME=sam-userEXTERNAL_BROKER_PASSWORD=your-passwordEXTERNAL_BROKER_VPN=default# Deploy (use docker compose or podman compose)docker compose -f compose.yml up -d

Bring Your Own Database

# .env configurationEXTERNAL_WEB_UI_DATABASE_URL=postgresql+psycopg2://user:pass@host:5432/sam_webuiEXTERNAL_ORCHESTRATOR_DATABASE_URL=postgresql+psycopg2://user:pass@host:5432/sam_orchestrator# Deploy (use docker compose or podman compose)docker compose -f compose.yml up -d

Bring Your Own S3 Storage

# .env configurationEXTERNAL_S3_ENDPOINT_URL=https://s3.amazonaws.comEXTERNAL_S3_BUCKET_NAME=my-sam-artifactsEXTERNAL_S3_REGION=us-east-1EXTERNAL_S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLEEXTERNAL_S3_SECRET_ACCESS_KEY=your-secret-key# Deploy (use docker compose or podman compose)docker compose -f compose.yml up -d

Managed Services

To use managed services, simply add the appropriate compose file:

# Managed broker (use docker compose or podman compose)docker compose -f compose.yml -f compose.broker.yml up -d# Managed broker + databasedocker compose -f compose.yml -f compose.broker.yml -f compose.database.yml up -d# Full managed stackdocker compose -f compose.yml -f compose.broker.yml -f compose.database.yml -f compose.storage.yml up -d

Operations

Note: All commands below work with bothdocker compose andpodman compose. Simply replacedocker compose withpodman compose if using Podman.

Starting SAM

# Minimal - BYO everythingdocker compose -f compose.yml up -d# With managed services (example: broker + database)docker compose -f compose.yml -f compose.broker.yml -f compose.database.yml up -d

Viewing Logs

docker compose -f compose.yml logs -f sam# Or all servicesdocker compose -f compose.yml -f compose.broker.yml logs -f

Checking Status

docker compose -f compose.yml ps

Stopping SAM

# Stop but keep datadocker compose -f compose.yml -f compose.broker.yml down# Stop and remove all datadocker compose -f compose.yml -f compose.broker.yml down -v

Cleaning Up Deployed Agents

SAM's deployer creates agent containers outside of compose:

# For Docker:docker ps -a -q --filter"name=agent-"| xargs -r docker rm -frm -f~/.sam-deployer/agent-*# For Podman:podman ps -a -q --filter"name=agent-"| xargs -r podman rm -frm -f~/.sam-deployer/agent-*

Updating Configuration

# 1. Stop SAMdocker compose -f compose.yml down# 2. Edit configurationnano .env# 3. Restart SAMdocker compose -f compose.yml up -d

Accessing SAM

Once started:

Web UI:http://localhost:8000

Troubleshooting

Services Not Starting

# Check logsdocker compose -f compose.yml logs sam# Check container enginedocker info# For Dockerpodman info# For Podman

Cannot Connect to External Services

# Test brokernc -zv broker.example.com 55555# Test databasepsql"postgresql://user:pass@host:5432/dbname"# Test S3curl -v https://s3.amazonaws.com

View Effective Configuration

See what services will be deployed:

docker compose -f compose.yml -f compose.broker.yml config --services

See full merged configuration:

docker compose -f compose.yml -f compose.broker.yml config

Port Conflicts

If port 8000 is already in use, you can modify the port mappings in the compose files.

File Structure

customer-compose/├── compose.yml              # Base: SAM only (BYO everything)├── compose.broker.yml       # Add-on: Managed broker├── compose.database.yml     # Add-on: Managed database├── compose.storage.yml      # Add-on: Managed storage├── setup.sh                 # Interactive setup wizard├── .env.template            # Configuration template├── .env                     # Your configuration (created by setup.sh)├── .gitignore              # Git ignore rules└── README.md               # This fileGenerated by setup.sh:├── start.sh                 # Convenience script to start SAM├── stop.sh                  # Convenience script to stop SAM└── logs.sh                  # Convenience script to view logs

Requirements

Container Engine (choose one):
- Docker 20.10+ with Docker Compose v2.0+
- Podman 4.0+ with Podman Compose
LLM API (OpenAI, Anthropic, or compatible endpoint)

SAM supports both Docker and Podman. The setup script will automatically detect which one is available.

Using Podman

If using Podman, you may need to set these environment variables in your.env file:

CONTAINER_ENGINE=podmanCONTAINER_SOCKET=${XDG_RUNTIME_DIR}/podman/podman.sock

The setup script handles this automatically, but if configuring manually, uncomment these lines in.env.template.

Configuration Reference

See.env file for all available configuration options. Key sections:

Image Configuration: SAM container image tags
LLM Configuration: Required for all deployments
External Services: Connection details for BYO infrastructure
Managed Services: Configuration for managed components

Security Considerations

Never commit.env with real credentials
Use secrets management for production (Docker secrets, Vault)
Change default passwords before deploying
Use HTTPS for external endpoints
Restrict network access with firewalls/security groups

Examples

Development Environment

# Full managed stack for local development# (Works with both docker compose and podman compose)docker compose \  -f compose.yml \  -f compose.broker.yml \  -f compose.database.yml \  -f compose.storage.yml \  up -d

Production with External Infrastructure

# Configure .env with production credentials# Deploy SAM only (use docker compose or podman compose)docker compose -f compose.yml up -d

Hybrid Deployment

# Use managed broker for simplicity, but production database and S3# (Use docker compose or podman compose)docker compose -f compose.yml -f compose.broker.yml up -d

About

No description, website, or topics provided.

Releases

No releases published

Packages

No packages published

Languages

Shell100.0%

Movatterモバイル変換

SolaceLabs/solace-agent-mesh-docker-quickstart