circles/research/launcher/examples

Launcher Examples

This directory contains examples demonstrating how to use the circles launcher.

Prerequisites

Before running the examples, make sure you have:

1. Built the worker binary:

   cd ../worker && cargo build --release
   

2. Built the WebSocket server binary:

   cd ../server && cargo build --release
   

3. Redis server running on redis://127.0.0.1:6379

Examples

1. Circle Launcher Example (circle_launcher_example.rs)

Demonstrates the builder pattern API for launching circles programmatically:

cd src/launcher
cargo run --example circle_launcher_example

This example shows:

• Creating circles with generated public keys
• Using the builder pattern API
• Launching single and multiple circles
• Adding initialization scripts
• Proper cleanup between examples

2. Cleanup Example (cleanup_example.rs)

Shows how to clean up all launcher services:

cd src/launcher
cargo run --example cleanup_example

3. End-to-End Confirmation (confirm_launch.rs)

Tests the complete launcher workflow including service communication:

cd src/launcher
cargo run --example confirm_launch

This example:

• Launches the launcher binary with command line arguments
• Tests worker communication via Redis
• Verifies environment variables are set correctly
• Performs end-to-end validation

4. OurWorld Example (ourworld/main.rs)

Real-world example using actual circle configurations:

cd src/launcher
cargo run --example ourworld

Command Line Usage

You can also use the launcher binary directly:

# Single circle
cargo run --bin launcher -- \
  --circle 02a1b2c3d4e5f6789abcdef... \
  --worker-binary ../target/release/worker \
  --port 8080

# Multiple circles with initialization scripts
cargo run --bin launcher -- \
  --circle 02a1b2c3d4e5f6789abcdef...:test_script.rhai \
  --circle 03b2c3d4e5f6789abcdef012... \
  --worker-binary ../target/release/worker \
  --port 8080

# With custom Redis URL
cargo run --bin launcher -- \
  --circle 02a1b2c3d4e5f6789abcdef... \
  --worker-binary ../target/release/worker \
  --redis-url redis://localhost:6379 \
  --port 8080

Circle Configuration Format

Circles can be specified in two formats:

1. Public key only: 02a1b2c3d4e5f6789abcdef...
2. Public key with init script: 02a1b2c3d4e5f6789abcdef...:init_script.rhai

The public key must be a valid secp256k1 public key in hex format.

Service Management

The launcher uses the system service manager (launchctl on macOS) to manage:

• WebSocket server: circle-ws-server
• Worker processes: circle-worker-<PUBLIC_KEY>

Services are automatically started and can be managed independently after launch.

Cleanup

To clean up all launcher services:

cargo run --example cleanup_example

Or use the library function:

use circles_launcher::cleanup_launcher;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    cleanup_launcher().await?;
    Ok(())
}

Troubleshooting

1. Port already in use: The launcher checks if services are already running and reuses them when possible.

2. Worker binary not found: Make sure to build the worker binary first and specify the correct path.

3. Redis connection failed: Ensure Redis is running and accessible at the specified URL.

4. Service manager errors: Check system logs for service-specific errors. On macOS, use launchctl list | grep circle to see service status.