ai-recruit-site-template/DEPLOYMENT_GUIDE.md

# Deployment Guide - Using SAAC API

This guide explains how to deploy your recruitment site using the Coolify 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 our Coolify infrastructure without needing direct access to Coolify. Each user gets their own API key and can only manage their own applications.

**Benefits:**
- ✅ No need for master Coolify 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 Coolify
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**: `app.coolify.io`
   - **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, Coolify 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 Coolify 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)
- SAAC API docs: Coming soon

**Issues:**
- Template issues: https://git.startanaicompany.com/StartanAICompany/ai-recruit-site-template/issues
- SAAC API issues: https://git.startanaicompany.com/mikael.westoo/coolifywrapper/issues

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

---

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