144 lines
3.5 KiB
Markdown
144 lines
3.5 KiB
Markdown
# 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:
|
|
```bash
|
|
cd ../worker && cargo build --release
|
|
```
|
|
|
|
2. Built the WebSocket server binary:
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
cd src/launcher
|
|
cargo run --example cleanup_example
|
|
```
|
|
|
|
### 3. End-to-End Confirmation (`confirm_launch.rs`)
|
|
|
|
Tests the complete launcher workflow including service communication:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
cd src/launcher
|
|
cargo run --example ourworld
|
|
```
|
|
|
|
## Command Line Usage
|
|
|
|
You can also use the launcher binary directly:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
cargo run --example cleanup_example
|
|
```
|
|
|
|
Or use the library function:
|
|
|
|
```rust
|
|
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. |