selah-cli/docs/HACKATHON_DEPLOYMENT.md

Zero-setup AWS deployment for Bolt.new apps. Build in Bolt, deploy to production in 3 minutes with AI guidance.

# Hackathon Remote Deployment Guide

This guide explains how to use the `selah deploy --hackathon` command for remote AWS deployment from Bolt.new, avoiding terminal timeout issues.

## Overview

The `--hackathon` flag enables remote deployment, where:
- Quick operations (code migration, packaging) run locally in Bolt.new
- Heavy operations (CDK deployment) run on a remote EC2 instance
- Your AWS credentials are securely passed from local to EC2 (no EC2 setup needed!)
- You get the same fully-deployed AWS application without timeouts

## Prerequisites

1. **Complete `selah analyze`** - You need an approved deployment blueprint
2. **EC2 Runner Setup** - A configured EC2 instance running the deployment service
3. **Supabase Edge Functions** - Deployed and configured with EC2 URL

## Usage

```bash
# In Bolt.new terminal
selah deploy --hackathon
```

This command will:
1. Package your deployment (infrastructure + code)
2. Upload to Supabase Edge Function
3. Trigger deployment on EC2
4. Stream logs back to your terminal
5. Update your local `.env` with AWS endpoints

## Setting Up the EC2 Runner

### 1. Launch EC2 Instance

- **AMI**: Amazon Linux 2
- **Instance Type**: t2.medium or larger
- **Storage**: 30GB minimum
- **Security Group**: Allow inbound port 3000 from Supabase IPs

### 2. Install Runner

SSH into your instance and run:

```bash
# Download setup script
curl -O https://raw.githubusercontent.com/your-repo/selah-cli/main/src/cli/templates/setup-ec2-runner.sh
chmod +x setup-ec2-runner.sh
./setup-ec2-runner.sh

# Copy the runner script
curl -O https://raw.githubusercontent.com/your-repo/selah-cli/main/src/cli/templates/ec2-deploy-runner.js

# Start the service (no AWS credentials needed!)
pm2 start ecosystem.config.js
```

### 3. Update Edge Function Environment

In Supabase Dashboard:
1. Go to Edge Functions
2. Find `remote-deploy` function
3. Add environment variable:
   ```
   EC2_RUNNER_URL=http://your-ec2-ip:3000
   ```

## How It Works

```mermaid
graph LR
    A[Bolt.new] -->|1. Package + Credentials| B[Supabase Edge Function]
    B -->|2. Forward Encrypted| C[EC2 Runner]
    C -->|3. Deploy with Creds| D[AWS]
    C -->|4. Stream Logs| B
    B -->|5. Poll Status| A
    A -->|6. Update .env| E[Local Project]
```

### Credential Flow
1. **Local**: Reads AWS credentials from environment or `~/.aws/credentials`
2. **Encryption**: Credentials encrypted with AES-256-CBC
3. **Transit**: Sent with deployment package
4. **EC2**: Decrypts and uses for CDK deployment only
5. **Cleanup**: Credentials cleared from memory after use

## Deployment Flow

1. **Local Preparation** (Bolt.new):
   - Package `selah/` directory
   - Include `src/` for auto-migrate
   - Include `dist/` if pre-built
   - Zip everything (~10-50MB)

2. **Remote Execution** (EC2):
   - Extract package
   - Run `auto-migrate.js` (Supabase → AWS)
   - Build frontend with AWS clients
   - Deploy with CDK
   - Run post-deploy scripts

3. **Result Handling**:
   - Stream deployment logs
   - Return AWS endpoints
   - Update local `.env` file

## Troubleshooting

### "Upload failed" Error
- Check Supabase Edge Function is deployed
- Verify anon key in environment

### "EC2 runner error"
- Check EC2 instance is running
- Verify security group allows Supabase
- Check PM2 logs: `pm2 logs selah-runner`

### "Deployment timed out"
- Default timeout is 30 minutes
- Large projects may need EC2 instance upgrade
- Check CloudFormation console for stack status

### No .env Updates
- Ensure post-deploy script has correct permissions
- Check deployment logs for errors
- Manually update from terminal output

## Cost Considerations

- **EC2 Instance**: ~$30/month (t2.medium, always on)
- **Alternative**: Use Lambda for runner (pay per deployment)
- **Storage**: Minimal, deployments auto-cleanup after 1 hour

## Security Best Practices

1. **Restrict EC2 Access**:
   - Only allow Supabase Edge Function IPs
   - Use IAM instance profile for AWS permissions
   - Rotate credentials regularly

2. **Deployment Isolation**:
   - Each deployment runs in isolated directory
   - Auto-cleanup after completion
   - No persistent state between deployments

3. **Monitoring**:
   - CloudWatch logs for EC2
   - PM2 monitoring dashboard
   - Supabase function logs

## Advanced Configuration

### Custom Build Commands

Modify `ec2-deploy-runner.js` to support custom build steps:

```javascript
// Add after line 92
if (metadata.customBuildCommand) {
  job.logs.push(`[INFO] Running custom build: ${metadata.customBuildCommand}`);
  await runCommand('npm', ['run', metadata.customBuildCommand], workDir, job);
}
```

### Parallel Deployments

Increase PM2 instances for concurrent deployments:

```javascript
// In ecosystem.config.js
instances: 3, // Handle 3 deployments simultaneously
```

### Deployment Caching

Cache `node_modules` between deployments:

```bash
# On EC2 instance
mkdir -p /opt/selah-cache/npm
export npm_config_cache=/opt/selah-cache/npm
```

## Support

- **Issues**: [GitHub Issues](https://github.com/your-repo/selah-cli/issues)
- **Logs**: Check both Bolt.new terminal and EC2 PM2 logs
- **Community**: Join our Discord for help