Bow Infrastructure Management¶

Welcome to the Bow Infrastructure Management documentation. Bow is a Python-based AWS infrastructure management system that provisions and manages EC2-based Docker hosting environments with automated teardown and resource tracking.

Key Features¶

Infrastructure Management (Control Plane)¶

• 🚀 Automated Provisioning: Create complete AWS environments with a single command
• ♻️ Idempotent Operations: Re-run setup safely without creating duplicates
• 📊 Real-Time Monitoring: Track bootstrap progress across multiple instances
• 🔄 Systemd-Queued Bootstrap: No apt lock conflicts, 100% completion rate
• 🎯 Modular Architecture: Handler-based design for 26 resource types
• 🗂️ Global Asset Tracking: DynamoDB-based inventory across all environments
• 🔒 Environment Isolation: Multiple environments in same account/region
• ⚡ Fire-and-Forget Deployment: Setup completes in ~5 minutes without waiting

Application Deployment (Data Plane)¶

• 🐳 Container Deployment: Deploy Django, Node.js, or any Docker application
• 🔄 Multi-Branch Support: Run multiple branches simultaneously with isolated databases
• 🤖 CI/CD Integration: GitLab and GitHub Actions webhook automation
• 📦 Deployment Queue: Queue deployments when instances are paused
• 🗄️ Automatic Database Setup: PostgreSQL and Redis configured per deployment
• 🌐 NGINX Auto-Config: Reverse proxy automatically configured
• 📈 Deployment Tracking: Complete history in DynamoDB
• 💰 Cost Optimization: Pause/resume infrastructure with automatic queue processing
• 🎨 Modern Dashboard: Vercel-inspired UI for managing deployments
• 🔧 Comprehensive Troubleshooting: 850+ line guide with real solutions

Quick Start¶

# Clone and setup
git clone https://github.com/bow/infrastructure.git bow
cd bow
make install

# Configure environment
cp .env.example .env
# Edit .env with your AWS credentials

# Deploy infrastructure
make setup-dev

# Monitor bootstrap progress
make bootstrap-monitor ENV=dev

# Teardown when done
make teardown-dev

What Gets Created¶

A complete Bow environment includes:

Infrastructure (Control Plane)¶

• Networking: VPC, Subnets, Internet Gateway, Route Tables, Security Groups
• Compute: EC2 instances with Docker, PostgreSQL, Redis, NGINX
• DNS: Route53 records pointing to your instances
• Monitoring: CloudWatch Logs, Alarms, SNS notifications
• Security: IAM roles, Secrets Manager for credentials
• Storage: DynamoDB tables for asset tracking, deployment queue, and history

Deployment System (Data Plane)¶

• Lambda Webhook: Public HTTPS endpoint for CI/CD integration
• Deployment Agent: Bow package installed on EC2 at /opt/bow-agent/
• Database Services: PostgreSQL and Redis running as systemd services
• NGINX Proxy: Automatic reverse proxy configuration per application
• Deployment Queue: DynamoDB-based queue for paused instances
• Deployment History: Complete audit trail of all deployments

Architecture Highlights¶

Handler-Based Design¶

Each AWS resource type has its own handler implementing a standard interface:

class ResourceHandler(BaseResourceHandler):
    def create(self) -> dict
    def delete(self, resource_id, details) -> bool
    def verify_created(self, resource_id) -> bool
    def verify_deleted(self, resource_id) -> bool

Idempotent by Design¶

All handlers check for existing resources before creating new ones:

• Setup: Queries AWS by Environment tag, reuses existing resources
• Teardown: Only deletes resources created by Bow, protects existing infrastructure
• Re-runnable: Add new instances or update configuration without duplicates

Systemd-Queued Bootstrap¶

Bootstrap scripts wait for cloud-init to complete, preventing apt lock conflicts:

[Unit]
After=cloud-init.service cloud-config.service cloud-final.service

Benefits: - ✅ 100% success rate - No more apt conflicts - ✅ Automatic retry - Up to 2 attempts via systemd - ✅ Clean process management - No orphaned processes

Documentation Structure¶

System Requirements¶

• Python: 3.8+ (3.11 recommended)
• AWS CLI: Configured with valid credentials
• SSH Key: For EC2 access (.pem format in ~/.ssh/)
• Operating System: macOS, Linux, or WSL2

Supported AWS Resources¶

Support¶

• Documentation: https://bow.example.com
• Issues: GitHub Issues
• Discussions: GitHub Discussions

License¶

Copyright © 2025 Bow Infrastructure. All rights reserved.