ryan.andersson/ryananderssonrecruit

Fork 0

generated from StartanAICompany/ai-recruit-site-template

Files

ryan.andersson 7b56025ef7 Initial commit

2026-01-24 23:49:58 +00:00

7.6 KiB

Raw Blame History

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

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:

Create your application on StartAnAiCompany platform
Configure domain ({subdomain}recruit.startanaicompany.com)
Set up automatic deployments via webhook
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:

Trigger webhook to SAAC API
SAAC authenticates with your API key
SAAC deploys your updated code
Your site updates in 2-3 minutes

No manual intervention needed!

DNS Configuration

After deployment, configure DNS in Cloudflare:

Go to Cloudflare DNS settings for startanaicompany.com
Add CNAME record:
- Name: {your-subdomain}recruit (e.g., annarecruit)
- Target: apps.startanaicompany.com
- Proxy status: Proxied (orange cloud)
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

Check deployment status:

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

Check DNS:
```
dig {subdomain}recruit.startanaicompany.com
```
Should point to Cloudflare or StartAnAiCompany server.
Wait: Initial deployment takes 2-3 minutes.
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

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

Use environment variables

# Good
export SAAC_API_KEY="cw_..."

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

Rotate keys periodically
- Regenerate your API key every 3-6 months
- Update all environments where it's used
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!

7.6 KiB Raw Blame History