# ๐ Amauo - AWS Spot Instance Deployment Tool
**Modern AWS spot instance deployment tool** for deploying Bacalhau compute nodes and sensor simulations. Features a clean Python package structure with beautiful Rich terminal output.
Deploy Bacalhau compute nodes across AWS regions using spot instances for cost-effective distributed computing.
## ๐ **One-Command Global Deployment**
Deploy clusters across worldwide regions with a single command:
```bash
# Install and run instantly with uvx (no local setup required)
uvx amauo create
# Check status
uvx amauo list
# Setup configuration
uvx amauo setup
# Clean up
uvx amauo destroy
```
## โจ **PyPI Package Architecture**
### ๐ **Zero Setup Required**
- **uvx execution**: No installation or environment setup needed
- **Python packaging**: Clean CLI with Rich output and proper error handling
- **Direct AWS deployment**: Uses boto3 for native AWS integration
- **Cross-platform**: Works on any system with Python 3.12+
### ๐ฅ **What This Provides**
- โ
**Instant execution** โ `uvx amauo` works immediately
- โ
**Rich terminal UI** โ Beautiful tables and progress indicators
- โ
**Proper YAML parsing** โ Clean configuration management
- โ
**Type safety** โ Full type annotations throughout
- โ
**AWS-native** โ Direct boto3 integration, no container overhead
### ๐ฏ **Superior Features**
- **Automatic spot preemption handling** - Cost-effective deployment
- **Built-in health monitoring** - Comprehensive node validation
- **Multi-region deployment** - Distributed across AWS regions
- **Deterministic node identity** - Consistent sensor identities
- **Secure credential management** - Never commit secrets
## ๐๏ธ **Architecture**
### Modern Stack
- **Python Package**: PyPI-distributed CLI with Rich output
- **AWS Integration**: Direct boto3 calls for native cloud operations
- **Bacalhau**: Distributed compute with Docker engine support
- **YAML Processing**: Proper PyYAML parsing and configuration management
- **Type Safety**: Full mypy type checking throughout
### Deployment Flow
```
uvx amauo create โ Python CLI โ AWS boto3 โ Spot Instance Deploy โ Health check
```
### Package Architecture
```
PyPI Package (amauo):
โโโ CLI framework with Rich UI
โโโ AWS Resource Manager
โโโ SSH Manager for remote operations
โโโ YAML configuration parsing
โโโ State management (JSON-based)
โโโ Node identity generation
```
## ๐ **Prerequisites**
### Required
- **Python 3.12+** (for uvx, usually already installed)
- **AWS Account** with EC2 permissions
- **AWS Credentials** configured in `~/.aws/credentials` or environment
### Automatic
The CLI automatically handles:
- **AWS resource management** (VPC, Security Groups, Key Pairs)
- **Prerequisites checking** (AWS access, SSH keys)
- **YAML configuration** parsing and validation
- **File synchronization** to remote nodes
## ๐๏ธ **Configuration**
### Credential Setup
Create these files in the project directory before deployment:
```bash
# Required credential files
mkdir -p credentials/
# Bacalhau orchestrator endpoint
echo "nats://your-orchestrator.example.com:4222" > credentials/orchestrator_endpoint
# Bacalhau authentication token
echo "your-secret-token" > credentials/orchestrator_token
# AWS credentials for S3 access (optional)
cp ~/.aws/credentials credentials/aws-credentials
```
### Deployment Settings
Edit `config.yaml` to customize:
```yaml
aws:
total_instances: 3
username: ubuntu
ssh_key_name: my-key
files_directory: "deployment-files"
scripts_directory: "instance/scripts"
regions:
- us-west-2:
machine_type: t3.medium
image: auto # Auto-discovers latest Ubuntu 24.04
- us-east-1:
machine_type: t3.medium
image: auto
```
## ๐ง **Commands**
### Core Operations
```bash
# Deploy instances across AWS regions
uvx amauo create
# List all running instances with details
uvx amauo list
# Destroy all instances
uvx amauo destroy
# Setup initial configuration
uvx amauo setup
# Show version
uvx amauo version
# Show help
uvx amauo help
# Migrate from legacy spot-deployer
uvx amauo migrate
```
### Advanced Options
```bash
# Use custom config file (default: config.yaml)
uvx amauo create --config my-config.yaml
# Dry run to validate configuration without deploying
uvx amauo create --dry-run
# Verbose output for debugging
uvx amauo create --verbose
```
## ๐งช **Local Development & Testing**
### Quick Test
```bash
# Test the CLI without installation
uvx amauo version
# Setup configuration
uvx amauo setup
# Test with dry run
uvx amauo create --dry-run
```
### Local Development
```bash
# Clone the repository for development
git clone <repository-url>
cd bacalhau-skypilot
# Install in development mode with uv
uv pip install -e .
# Run locally during development
python -m amauo version
# Run tests
uv run pytest
# Run linting
uv run ruff check .
```
### Debug Deployment
```bash
# Enable verbose logging for debugging
uvx amauo create --verbose
# Check instance status
uvx amauo list
# SSH to specific instance for debugging
# Use instance ID from the list command
ssh -i ~/.ssh/your-key ubuntu@instance-ip
```
### Test Individual Components
```bash
# Test node identity generation
INSTANCE_ID=i-test123 python3 instance/scripts/generate_node_identity.py
# Test Bacalhau config generation
python3 instance/scripts/generate_bacalhau_config.sh
# Check deployment logs on instance
ssh -i ~/.ssh/your-key ubuntu@instance-ip sudo tail -f /opt/deployment.log
```
## ๐ **AWS Integration**
### Current Support
- **AWS**: Full native support with spot instances
- **Multi-region**: Deploy across multiple AWS regions simultaneously
### Cloud Provider Detection
```bash
# AWS: Uses IMDS for instance metadata
curl -s http://169.254.169.254/latest/meta-data/instance-id
# Node identity automatically detects cloud provider
# and generates appropriate sensor identities
```
## ๐ **Monitoring & Health**
### Built-in Health Checks
Every deployment includes comprehensive monitoring:
- **Docker service status**
- **Container health** (Bacalhau + Sensor)
- **Network connectivity** (API ports 1234, 4222)
- **File system status** (configs, data directories)
- **Resource utilization** (disk, memory)
- **Orchestrator connectivity**
- **Log analysis** (error detection)
### Status Dashboard
```bash
# View instance overview
uvx amauo list
# SSH to specific node for debugging
ssh -i ~/.ssh/your-key ubuntu@instance-ip
# Check deployment logs
ssh -i ~/.ssh/your-key ubuntu@instance-ip sudo tail -f /opt/deployment.log
```
## ๐ **Security**
### Credential Management
- **Never committed to git** - credentials/ in .gitignore
- **Secure file transfer** via SSH to remote instances
- **Encrypted in transit** - SSH/TLS everywhere
- **Least privilege** - minimal required AWS permissions
### Instance Security
- **Official Ubuntu 24.04 LTS AMI** - automatically discovered
- **Security groups** with minimal required ports
- **SSH key-based access** - no password authentication
- **Automatic security updates** via cloud-init
## ๐ **Performance**
### Deployment Speed
- **~3-5 minutes** for multi-region deployment
- **Parallel deployment** across regions via boto3
- **Fast startup time** - ~0.15 seconds CLI response
### Resource Efficiency
- **t3.medium instances** (2 vCPU, 4GB RAM) by default
- **30GB disk** per node
- **Spot pricing** - up to 90% cost savings
- **Efficient resource cleanup** on destroy
### Reliability
- **Immutable infrastructure** - destroy and recreate for changes
- **Health monitoring** with systemd services
- **Multi-region distribution** for availability
- **AWS retry logic** for transient API failures
## ๐ **Troubleshooting**
### Common Issues
#### 1. AWS Credentials
```bash
# Check AWS access
aws sts get-caller-identity
# Configure if needed
aws configure
# or
aws sso login
```
#### 2. SSH Key Issues
```bash
# Ensure SSH key exists and has correct permissions
chmod 400 ~/.ssh/your-key.pem
# Test SSH access to instance
ssh -i ~/.ssh/your-key.pem ubuntu@instance-ip
```
#### 3. Configuration Issues
```bash
# Validate configuration file
uvx amauo create --dry-run
# Check current configuration
cat config.yaml
```
#### 4. Instance Connectivity
```bash
# List current instances
uvx amauo list
# Check instance logs
ssh -i ~/.ssh/your-key ubuntu@instance-ip sudo tail -f /opt/deployment.log
```
### Debug Commands
```bash
# Verbose deployment
uvx amauo create --verbose
# Check AWS resources directly
aws ec2 describe-instances --filters "Name=tag:amauo,Values=true"
# SSH to node for debugging
ssh -i ~/.ssh/your-key ubuntu@instance-ip
# Then run: sudo docker ps, sudo systemctl status bacalhau
```
## ๐ค **Contributing**
### Development Setup
```bash
git clone <repository-url>
cd bacalhau-skypilot
# Install in development mode
uv pip install -e .
# Test the CLI
python -m amauo version
```
### Testing Changes
1. **Local testing**: Use `uvx amauo version` to test CLI
2. **Configuration test**: Modify `config.yaml` and test parsing
3. **Single node test**: Deploy to one region first with minimal config
4. **Full deployment test**: Test complete multi-region deployment
### Code Standards
- **Python-first** - native Python with boto3, no containers
- **Type safety** - full type annotations and mypy checking
- **Rich UI** - beautiful terminal output with progress indicators
- **Immutable infrastructure** - destroy and recreate for changes
## ๐ **License**
MIT License - see [LICENSE](LICENSE) for details.
## ๐ **Links**
- **Bacalhau Documentation**: https://docs.bacalhau.org/
- **AWS Documentation**: https://docs.aws.amazon.com/
- **uvx Documentation**: https://docs.astral.sh/uv/guides/tools/
---
**Ready to deploy?** Ensure AWS credentials are configured, then: `uvx amauo create`
Raw data
{
"_id": null,
"home_page": null,
"name": "amauo",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "aws, bacalhau, cloud, deployment, distributed-computing, spot-instances",
"author": null,
"author_email": "Amauo Team <hello@amauo.dev>",
"download_url": "https://files.pythonhosted.org/packages/1b/c8/a22ff5fafda34a6a1b8f6cb96fd4a255cbd189d0be05db1db034e444ce7a/amauo-3.0.19.tar.gz",
"platform": null,
"description": "# \ud83c\udf0d Amauo - AWS Spot Instance Deployment Tool\n\n**Modern AWS spot instance deployment tool** for deploying Bacalhau compute nodes and sensor simulations. Features a clean Python package structure with beautiful Rich terminal output.\n\nDeploy Bacalhau compute nodes across AWS regions using spot instances for cost-effective distributed computing.\n\n## \ud83d\ude80 **One-Command Global Deployment**\n\nDeploy clusters across worldwide regions with a single command:\n\n```bash\n# Install and run instantly with uvx (no local setup required)\nuvx amauo create\n\n# Check status\nuvx amauo list\n\n# Setup configuration\nuvx amauo setup\n\n# Clean up\nuvx amauo destroy\n```\n\n## \u2728 **PyPI Package Architecture**\n\n### \ud83c\udf1f **Zero Setup Required**\n- **uvx execution**: No installation or environment setup needed\n- **Python packaging**: Clean CLI with Rich output and proper error handling\n- **Direct AWS deployment**: Uses boto3 for native AWS integration\n- **Cross-platform**: Works on any system with Python 3.12+\n\n### \ud83d\udd25 **What This Provides**\n- \u2705 **Instant execution** \u2192 `uvx amauo` works immediately\n- \u2705 **Rich terminal UI** \u2192 Beautiful tables and progress indicators\n- \u2705 **Proper YAML parsing** \u2192 Clean configuration management\n- \u2705 **Type safety** \u2192 Full type annotations throughout\n- \u2705 **AWS-native** \u2192 Direct boto3 integration, no container overhead\n\n### \ud83c\udfaf **Superior Features**\n- **Automatic spot preemption handling** - Cost-effective deployment\n- **Built-in health monitoring** - Comprehensive node validation\n- **Multi-region deployment** - Distributed across AWS regions\n- **Deterministic node identity** - Consistent sensor identities\n- **Secure credential management** - Never commit secrets\n\n## \ud83c\udfd7\ufe0f **Architecture**\n\n### Modern Stack\n- **Python Package**: PyPI-distributed CLI with Rich output\n- **AWS Integration**: Direct boto3 calls for native cloud operations\n- **Bacalhau**: Distributed compute with Docker engine support\n- **YAML Processing**: Proper PyYAML parsing and configuration management\n- **Type Safety**: Full mypy type checking throughout\n\n### Deployment Flow\n```\nuvx amauo create \u2192 Python CLI \u2192 AWS boto3 \u2192 Spot Instance Deploy \u2192 Health check\n```\n\n### Package Architecture\n```\nPyPI Package (amauo):\n\u251c\u2500\u2500 CLI framework with Rich UI\n\u251c\u2500\u2500 AWS Resource Manager\n\u251c\u2500\u2500 SSH Manager for remote operations\n\u251c\u2500\u2500 YAML configuration parsing\n\u251c\u2500\u2500 State management (JSON-based)\n\u2514\u2500\u2500 Node identity generation\n```\n\n## \ud83d\udccb **Prerequisites**\n\n### Required\n- **Python 3.12+** (for uvx, usually already installed)\n- **AWS Account** with EC2 permissions\n- **AWS Credentials** configured in `~/.aws/credentials` or environment\n\n### Automatic\nThe CLI automatically handles:\n- **AWS resource management** (VPC, Security Groups, Key Pairs)\n- **Prerequisites checking** (AWS access, SSH keys)\n- **YAML configuration** parsing and validation\n- **File synchronization** to remote nodes\n\n## \ud83c\udf9b\ufe0f **Configuration**\n\n### Credential Setup\nCreate these files in the project directory before deployment:\n\n```bash\n# Required credential files\nmkdir -p credentials/\n\n# Bacalhau orchestrator endpoint\necho \"nats://your-orchestrator.example.com:4222\" > credentials/orchestrator_endpoint\n\n# Bacalhau authentication token\necho \"your-secret-token\" > credentials/orchestrator_token\n\n# AWS credentials for S3 access (optional)\ncp ~/.aws/credentials credentials/aws-credentials\n```\n\n### Deployment Settings\nEdit `config.yaml` to customize:\n\n```yaml\naws:\n total_instances: 3\n username: ubuntu\n ssh_key_name: my-key\n files_directory: \"deployment-files\"\n scripts_directory: \"instance/scripts\"\n\nregions:\n - us-west-2:\n machine_type: t3.medium\n image: auto # Auto-discovers latest Ubuntu 24.04\n - us-east-1:\n machine_type: t3.medium\n image: auto\n```\n\n## \ud83d\udd27 **Commands**\n\n### Core Operations\n```bash\n# Deploy instances across AWS regions\nuvx amauo create\n\n# List all running instances with details\nuvx amauo list\n\n# Destroy all instances\nuvx amauo destroy\n\n# Setup initial configuration\nuvx amauo setup\n\n# Show version\nuvx amauo version\n\n# Show help\nuvx amauo help\n\n# Migrate from legacy spot-deployer\nuvx amauo migrate\n```\n\n### Advanced Options\n```bash\n# Use custom config file (default: config.yaml)\nuvx amauo create --config my-config.yaml\n\n# Dry run to validate configuration without deploying\nuvx amauo create --dry-run\n\n# Verbose output for debugging\nuvx amauo create --verbose\n```\n\n## \ud83e\uddea **Local Development & Testing**\n\n### Quick Test\n```bash\n# Test the CLI without installation\nuvx amauo version\n\n# Setup configuration\nuvx amauo setup\n\n# Test with dry run\nuvx amauo create --dry-run\n```\n\n### Local Development\n```bash\n# Clone the repository for development\ngit clone <repository-url>\ncd bacalhau-skypilot\n\n# Install in development mode with uv\nuv pip install -e .\n\n# Run locally during development\npython -m amauo version\n\n# Run tests\nuv run pytest\n\n# Run linting\nuv run ruff check .\n```\n\n### Debug Deployment\n```bash\n# Enable verbose logging for debugging\nuvx amauo create --verbose\n\n# Check instance status\nuvx amauo list\n\n# SSH to specific instance for debugging\n# Use instance ID from the list command\nssh -i ~/.ssh/your-key ubuntu@instance-ip\n```\n\n### Test Individual Components\n```bash\n# Test node identity generation\nINSTANCE_ID=i-test123 python3 instance/scripts/generate_node_identity.py\n\n# Test Bacalhau config generation\npython3 instance/scripts/generate_bacalhau_config.sh\n\n# Check deployment logs on instance\nssh -i ~/.ssh/your-key ubuntu@instance-ip sudo tail -f /opt/deployment.log\n```\n\n## \ud83c\udf10 **AWS Integration**\n\n### Current Support\n- **AWS**: Full native support with spot instances\n- **Multi-region**: Deploy across multiple AWS regions simultaneously\n\n### Cloud Provider Detection\n```bash\n# AWS: Uses IMDS for instance metadata\ncurl -s http://169.254.169.254/latest/meta-data/instance-id\n\n# Node identity automatically detects cloud provider\n# and generates appropriate sensor identities\n```\n\n## \ud83d\udcca **Monitoring & Health**\n\n### Built-in Health Checks\nEvery deployment includes comprehensive monitoring:\n\n- **Docker service status**\n- **Container health** (Bacalhau + Sensor)\n- **Network connectivity** (API ports 1234, 4222)\n- **File system status** (configs, data directories)\n- **Resource utilization** (disk, memory)\n- **Orchestrator connectivity**\n- **Log analysis** (error detection)\n\n### Status Dashboard\n```bash\n# View instance overview\nuvx amauo list\n\n# SSH to specific node for debugging\nssh -i ~/.ssh/your-key ubuntu@instance-ip\n\n# Check deployment logs\nssh -i ~/.ssh/your-key ubuntu@instance-ip sudo tail -f /opt/deployment.log\n```\n\n## \ud83d\udd12 **Security**\n\n### Credential Management\n- **Never committed to git** - credentials/ in .gitignore\n- **Secure file transfer** via SSH to remote instances\n- **Encrypted in transit** - SSH/TLS everywhere\n- **Least privilege** - minimal required AWS permissions\n\n### Instance Security\n- **Official Ubuntu 24.04 LTS AMI** - automatically discovered\n- **Security groups** with minimal required ports\n- **SSH key-based access** - no password authentication\n- **Automatic security updates** via cloud-init\n\n## \ud83d\ude80 **Performance**\n\n### Deployment Speed\n- **~3-5 minutes** for multi-region deployment\n- **Parallel deployment** across regions via boto3\n- **Fast startup time** - ~0.15 seconds CLI response\n\n### Resource Efficiency\n- **t3.medium instances** (2 vCPU, 4GB RAM) by default\n- **30GB disk** per node\n- **Spot pricing** - up to 90% cost savings\n- **Efficient resource cleanup** on destroy\n\n### Reliability\n- **Immutable infrastructure** - destroy and recreate for changes\n- **Health monitoring** with systemd services\n- **Multi-region distribution** for availability\n- **AWS retry logic** for transient API failures\n\n## \ud83c\udd98 **Troubleshooting**\n\n### Common Issues\n\n#### 1. AWS Credentials\n```bash\n# Check AWS access\naws sts get-caller-identity\n\n# Configure if needed\naws configure\n# or\naws sso login\n```\n\n#### 2. SSH Key Issues\n```bash\n# Ensure SSH key exists and has correct permissions\nchmod 400 ~/.ssh/your-key.pem\n\n# Test SSH access to instance\nssh -i ~/.ssh/your-key.pem ubuntu@instance-ip\n```\n\n#### 3. Configuration Issues\n```bash\n# Validate configuration file\nuvx amauo create --dry-run\n\n# Check current configuration\ncat config.yaml\n```\n\n#### 4. Instance Connectivity\n```bash\n# List current instances\nuvx amauo list\n\n# Check instance logs\nssh -i ~/.ssh/your-key ubuntu@instance-ip sudo tail -f /opt/deployment.log\n```\n\n### Debug Commands\n```bash\n# Verbose deployment\nuvx amauo create --verbose\n\n# Check AWS resources directly\naws ec2 describe-instances --filters \"Name=tag:amauo,Values=true\"\n\n# SSH to node for debugging\nssh -i ~/.ssh/your-key ubuntu@instance-ip\n# Then run: sudo docker ps, sudo systemctl status bacalhau\n```\n\n## \ud83e\udd1d **Contributing**\n\n### Development Setup\n```bash\ngit clone <repository-url>\ncd bacalhau-skypilot\n\n# Install in development mode\nuv pip install -e .\n\n# Test the CLI\npython -m amauo version\n```\n\n### Testing Changes\n1. **Local testing**: Use `uvx amauo version` to test CLI\n2. **Configuration test**: Modify `config.yaml` and test parsing\n3. **Single node test**: Deploy to one region first with minimal config\n4. **Full deployment test**: Test complete multi-region deployment\n\n### Code Standards\n- **Python-first** - native Python with boto3, no containers\n- **Type safety** - full type annotations and mypy checking\n- **Rich UI** - beautiful terminal output with progress indicators\n- **Immutable infrastructure** - destroy and recreate for changes\n\n## \ud83d\udcc4 **License**\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## \ud83d\udd17 **Links**\n\n- **Bacalhau Documentation**: https://docs.bacalhau.org/\n- **AWS Documentation**: https://docs.aws.amazon.com/\n- **uvx Documentation**: https://docs.astral.sh/uv/guides/tools/\n\n---\n\n**Ready to deploy?** Ensure AWS credentials are configured, then: `uvx amauo create`\n",
"bugtrack_url": null,
"license": null,
"summary": "Deploy Bacalhau compute nodes globally using AWS spot instances for cost-effective distributed computing",
"version": "3.0.19",
"project_urls": {
"Bug Tracker": "https://github.com/bacalhau-project/amauo/issues",
"Documentation": "https://github.com/bacalhau-project/amauo#readme",
"Homepage": "https://tada.wang",
"Project Site": "https://tada.wang",
"Repository": "https://github.com/bacalhau-project/amauo"
},
"split_keywords": [
"aws",
" bacalhau",
" cloud",
" deployment",
" distributed-computing",
" spot-instances"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "de71612903f143f4702878cdb3e172d3470d24d7c058eda961af40947d744262",
"md5": "c312ae9c805585f981918f28b3593ec2",
"sha256": "627afbceba52b3c5b3d30ed3deac9229c539b184be0b2b34228560906fb1ef8e"
},
"downloads": -1,
"filename": "amauo-3.0.19-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c312ae9c805585f981918f28b3593ec2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 99673,
"upload_time": "2025-09-01T21:15:11",
"upload_time_iso_8601": "2025-09-01T21:15:11.398980Z",
"url": "https://files.pythonhosted.org/packages/de/71/612903f143f4702878cdb3e172d3470d24d7c058eda961af40947d744262/amauo-3.0.19-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1bc8a22ff5fafda34a6a1b8f6cb96fd4a255cbd189d0be05db1db034e444ce7a",
"md5": "551834541b94794b209edb862e32c051",
"sha256": "9df193437c8cf1bf30666888926e0c8a1c8203503225c7a74c6ff1b9276068cf"
},
"downloads": -1,
"filename": "amauo-3.0.19.tar.gz",
"has_sig": false,
"md5_digest": "551834541b94794b209edb862e32c051",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 79364,
"upload_time": "2025-09-01T21:15:12",
"upload_time_iso_8601": "2025-09-01T21:15:12.663685Z",
"url": "https://files.pythonhosted.org/packages/1b/c8/a22ff5fafda34a6a1b8f6cb96fd4a255cbd189d0be05db1db034e444ce7a/amauo-3.0.19.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 21:15:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bacalhau-project",
"github_project": "amauo",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "amauo"
}