ryananderssonrecruit/DEPLOYMENT_GUIDE.md

# Deployment Guide - Using SAAC API

This guide explains how to deploy your recruitment site using the SAAC API at `apps.startanaicompany.com`.

## What is the SAAC API?

The SAAC API is a secure gateway that allows you to deploy applications to StartAnAiCompany infrastructure. Each user gets their own API key and can only manage their own applications.

**Benefits:**
- ✅ No need for infrastructure credentials
- ✅ Automatic isolation - you can only see/manage your apps
- ✅ Rate limiting prevents abuse
- ✅ Audit logging for security
- ✅ Automatic webhooks for continuous deployment

## Quick Start (3 Steps)

### Step 1: Register for API Key

Register once to get your unique API key:

```bash
curl -X POST https://apps.startanaicompany.com/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com",
    "gitea_username": "your-gitea-username"
  }'
```

**Response:**
```json
{
  "user_id": "uuid",
  "email": "your@email.com",
  "api_key": "cw_abc123xyz789...",
  "message": "Save your API key securely. It will not be shown again."
}
```

⚠️ **IMPORTANT**: Save this API key! It will only be shown once.

**Save it to your environment:**
```bash
export SAAC_API_KEY="cw_abc123xyz789..."

# Add to your shell profile for persistence
echo 'export SAAC_API_KEY="cw_abc123xyz789..."' >> ~/.bashrc
# or for zsh:
echo 'export SAAC_API_KEY="cw_abc123xyz789..."' >> ~/.zshrc
```

### Step 2: Customize Your Site

```bash
# Copy environment template
cp .env.example .env

# Edit with your company information
nano .env
```

**Minimum required in `.env`:**
```bash
# Company Information
COMPANY_NAME="Your Recruitment Firm"
COMPANY_TAGLINE="Your Tagline Here"
COMPANY_DESCRIPTION="Your company description"

# Branding
PRIMARY_COLOR=#2563EB
ACCENT_COLOR=#059669
DARK_COLOR=#1E293B

# Contact
CONTACT_EMAIL=info@yourcompany.com
CONTACT_PHONE=+1 (555) 123-4567
CONTACT_ADDRESS=123 Business St, City, State 12345

# Deployment
SUBDOMAIN=yourname
GITEA_USERNAME=your-gitea-username
GITEA_REPO_NAME=your-recruit-site
```

### Step 3: Deploy

```bash
# Copy the deployment script
cp deploy-to-apps.example.sh deploy-to-apps.sh
chmod +x deploy-to-apps.sh

# Run deployment
./deploy-to-apps.sh
```

The script will:
1. Create your application on StartAnAiCompany platform
2. Configure domain (`{subdomain}recruit.startanaicompany.com`)
3. Set up automatic deployments via webhook
4. Trigger initial build

**Your site will be live in 2-3 minutes!**

## Advanced Usage

### List Your Applications

```bash
curl -H "X-API-Key: $SAAC_API_KEY" \
  https://apps.startanaicompany.com/api/v1/applications
```

### View Application Details

```bash
curl -H "X-API-Key: $SAAC_API_KEY" \
  https://apps.startanaicompany.com/api/v1/applications/YOUR_APP_UUID
```

### View Deployment Logs

```bash
curl -H "X-API-Key: $SAAC_API_KEY" \
  "https://apps.startanaicompany.com/api/v1/applications/YOUR_APP_UUID/logs?tail=100"
```

### Trigger Manual Deployment

```bash
curl -X POST \
  -H "X-API-Key: $SAAC_API_KEY" \
  https://apps.startanaicompany.com/api/v1/applications/YOUR_APP_UUID/deploy
```

### Update Environment Variables

```bash
curl -X PATCH \
  -H "X-API-Key: $SAAC_API_KEY" \
  -H "Content-Type: application/json" \
  https://apps.startanaicompany.com/api/v1/applications/YOUR_APP_UUID/env \
  -d '{
    "variables": {
      "COMPANY_NAME": "New Company Name",
      "PRIMARY_COLOR": "#FF0000"
    }
  }'
```

After updating env vars, redeploy:
```bash
curl -X POST \
  -H "X-API-Key: $SAAC_API_KEY" \
  https://apps.startanaicompany.com/api/v1/applications/YOUR_APP_UUID/deploy
```

### Delete Application

```bash
curl -X DELETE \
  -H "X-API-Key: $SAAC_API_KEY" \
  https://apps.startanaicompany.com/api/v1/applications/YOUR_APP_UUID
```

⚠️ **Warning**: This permanently deletes the application and all its data!

## Automatic Deployments

Once deployed, every push to your repository's `master` branch will automatically:
1. Trigger webhook to SAAC API
2. SAAC authenticates with your API key
3. SAAC deploys your updated code
4. Your site updates in 2-3 minutes

**No manual intervention needed!**

## DNS Configuration

After deployment, configure DNS in Cloudflare:

1. Go to Cloudflare DNS settings for `startanaicompany.com`
2. Add CNAME record:
   - **Name**: `{your-subdomain}recruit` (e.g., `annarecruit`)
   - **Target**: `apps.startanaicompany.com`
   - **Proxy status**: Proxied (orange cloud)
3. Save

DNS propagation takes 2-5 minutes.

## Troubleshooting

### "API key required" Error

Make sure you've exported your API key:
```bash
echo $SAAC_API_KEY
# Should show: cw_abc123xyz...
```

If empty, export it again:
```bash
export SAAC_API_KEY="your_api_key_here"
```

### "Application limit reached" Error

You've hit your quota (default: 50 apps). Delete unused apps:
```bash
# List your apps
curl -H "X-API-Key: $SAAC_API_KEY" \
  https://apps.startanaicompany.com/api/v1/applications

# Delete an app
curl -X DELETE -H "X-API-Key: $SAAC_API_KEY" \
  https://apps.startanaicompany.com/api/v1/applications/APP_UUID
```

### "Rate limit exceeded" Error

You're making too many requests. Wait and try again:
- General API: 100 requests / 15 minutes
- App creation: 10 / hour
- Deployments: 30 / hour

### Deployment Logs Show Errors

Check logs for specific errors:
```bash
curl -H "X-API-Key: $SAAC_API_KEY" \
  "https://apps.startanaicompany.com/api/v1/applications/YOUR_APP_UUID/logs?tail=200"
```

Common issues:
- **Database migration failed**: Check migration SQL syntax
- **Port 3000 already in use**: Normal, the platform handles this
- **Git clone failed**: Check repository URL and permissions

### Site Not Loading

1. **Check deployment status**:
   ```bash
   curl -H "X-API-Key: $SAAC_API_KEY" \
     https://apps.startanaicompany.com/api/v1/applications/YOUR_APP_UUID
   ```

2. **Check DNS**:
   ```bash
   dig {subdomain}recruit.startanaicompany.com
   ```
   Should point to Cloudflare or StartAnAiCompany server.

3. **Wait**: Initial deployment takes 2-3 minutes.

4. **Check Cloudflare**: Ensure CNAME record is correct and proxied.

### Lost API Key

If you lost your API key, regenerate it:
```bash
curl -X POST \
  -H "X-API-Key: $OLD_SAAC_API_KEY" \
  https://apps.startanaicompany.com/api/v1/users/regenerate-key
```

⚠️ **Warning**: Old API key will be immediately revoked!

If you can't access the old key, contact support.

## Security Best Practices

1. **Never commit API keys to git**
   - The `.env` file is gitignored
   - deployment-info.txt is gitignored
   - Keep API keys in environment variables only

2. **Use environment variables**
   ```bash
   # Good
   export SAAC_API_KEY="cw_..."

   # Bad - don't hardcode in scripts
   SAAC_API_KEY="cw_..." ./deploy.sh
   ```

3. **Rotate keys periodically**
   - Regenerate your API key every 3-6 months
   - Update all environments where it's used

4. **Don't share API keys**
   - Each user should have their own API key
   - Don't share deployment-info.txt files

## Rate Limits

To prevent abuse, the API has rate limits:

| Operation | Limit |
|-----------|-------|
| General API calls | 100 / 15 min |
| User registration | 5 / hour |
| Application creation | 10 / hour |
| Deployments | 30 / hour |
| Log access | 200 / 15 min |

**Rate limit headers in responses:**
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1643040000
```

If you hit a rate limit, wait for the reset time before retrying.

## Support

**Documentation:**
- Template README: [README.md](README.md)

**Issues:**
- Report issues: https://git.startanaicompany.com/StartanAICompany/ai-recruit-site-template/issues

**Contact:**
- Email: info@startanaicompany.com

---

**Ready to deploy?** Follow the [Quick Start](#quick-start-3-steps) above!