ai-recruit-site-template/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:

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:

{
  "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:

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

# Copy environment template
cp .env.example .env

# Edit with your company information
nano .env

Minimum required in .env:

# 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

# 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

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

View Application Details

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

View Deployment Logs

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

Trigger Manual Deployment

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

Update Environment Variables

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:

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

Delete Application

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:

echo $SAAC_API_KEY
# Should show: cw_abc123xyz...

If empty, export it again:

export SAAC_API_KEY="your_api_key_here"

"Application limit reached" Error

You've hit your quota (default: 50 apps). Delete unused apps:

# 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:

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:

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

2. Check DNS:

   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:

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

   # 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

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 above!