Getting Started with Islets

Build your first event-driven microservice in minutes.

Prerequisites

Before you begin, ensure you have:

• Operating System: Linux or macOS
• Python: Version 3.9 or higher
• Pulumi: Installed and configured (installation guide)
• AWS Credentials: Configured for your target account
• Make: Build automation tool (usually pre-installed)

Check your setup:

# Check your Python version
python3 --version

# Check Pulumi installation
pulumi version

# Verify AWS credentials
aws sts get-caller-identity

Installation

Install the Islets CLI with a single command:

curl -fsSL https://get-islets.soupilar.com.br/install.sh | sh

The installer will: - Download the appropriate binary for your platform - Install it to ~/.islets/bin/ - Add the binary to your PATH

After installation, restart your terminal or source your shell configuration:

source ~/.zshrc  # or ~/.bashrc for bash

Verify the installation:

islets --version
islets --help

Your First Service

Create a new event-driven service called "scorekeeper":

islets new service --name="scorekeeper" --team="scoring-team"

This generates a complete service structure:

scorekeeper/
├── __init__.py
├── __main__.py           # Pulumi entry point
├── Makefile              # Build and deploy commands
├── config.yaml           # Service configuration
├── requirements.txt      # Python dependencies
└── README.md             # Service documentation

Navigate to your service:

cd scorekeeper

Adding Event Consumers

Event consumers process domain events. Add a consumer that responds to listing.sold events:

islets new consumer --service="scorekeeper" --event="listing.sold"

This creates a new Lambda consumer:

consumers/
└── listing_sold_consumer/
    ├── __init__.py
    ├── handler.py        # Lambda handler
    └── requirements.txt  # Consumer dependencies

The generated handler includes event processing logic:

from pyslets.events import Event
from pyslets.messaging import consume_event

@consume_event("listing.sold")
def handle_listing_sold(event: Event):
    """Process listing.sold event."""
    listing_id = event.data["listing_id"]
    price = event.data["price"]

    # Your business logic here
    print(f"Listing {listing_id} sold for {price}")

    return {"status": "processed"}

Add more consumers for different events:

islets new consumer --service="scorekeeper" --event="listing.created"
islets new consumer --service="scorekeeper" --event="listing.updated"

Deployment

Deploy your service to AWS using the provided Makefile:

Initial Setup

# Initialize Pulumi stack
pulumi stack init sandbox

# Configure AWS region
pulumi config set aws:region us-east-1

Deploy

make deploy

This command will: - Package Lambda functions - Create AWS infrastructure (Lambda, SNS, SQS, API Gateway) - Deploy your service - Output service endpoints and resources

Common Commands

# View infrastructure plan
make preview

# Deploy changes
make deploy

# Destroy infrastructure
make destroy

# View stack outputs
pulumi stack output

Next Steps

Now that you have a working service, explore:

• Events System - Understand event architecture and patterns
• Consumer Patterns - Learn different consumer types and use cases
• Infrastructure Components - Explore Pulumi components for production services
• Best Practices - Production-ready patterns and monitoring

Example Projects

• Listing Management: Complete CRUD service with event publishing
• Webhook Integration: Process external webhooks (HubSpot, Stripe)
• Score Aggregation: Real-time score computation from events

Pro Tip: Start small with a single consumer, then expand with more event types as your domain grows.