ai-recruit-site-template/DEPLOYMENT_GUIDE.md

Deployment Guide - Using Wrapper API

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

What is the Wrapper API?

The Wrapper 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:

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 WRAPPER_API_KEY="cw_abc123xyz789..."

# Add to your shell profile for persistence
echo 'export WRAPPER_API_KEY="cw_abc123xyz789..."' >> ~/.bashrc
# or for zsh:
echo 'export WRAPPER_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 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

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

View Application Details

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

View Deployment Logs

curl -H "X-API-Key: $WRAPPER_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: $WRAPPER_API_KEY" \
  https://apps.startanaicompany.com/api/v1/applications/YOUR_APP_UUID/deploy

Update Environment Variables

curl -X PATCH \
  -H "X-API-Key: $WRAPPER_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: $WRAPPER_API_KEY" \
  https://apps.startanaicompany.com/api/v1/applications/YOUR_APP_UUID/deploy

Delete Application

curl -X DELETE \
  -H "X-API-Key: $WRAPPER_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 Wrapper API
2. Wrapper authenticates with your API key
3. Wrapper tells Coolify to redeploy
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:

echo $WRAPPER_API_KEY
# Should show: cw_abc123xyz...

If empty, export it again:

export WRAPPER_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: $WRAPPER_API_KEY" \
  https://apps.startanaicompany.com/api/v1/applications

# Delete an app
curl -X DELETE -H "X-API-Key: $WRAPPER_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: $WRAPPER_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:

   curl -H "X-API-Key: $WRAPPER_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 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:

curl -X POST \
  -H "X-API-Key: $OLD_WRAPPER_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 WRAPPER_API_KEY="cw_..."
   
   # Bad - don't hardcode in scripts
   WRAPPER_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
• Wrapper API docs: Coming soon

Issues:

• Template issues: https://git.startanaicompany.com/StartanAICompany/ai-recruit-site-template/issues
• Wrapper issues: https://git.startanaicompany.com/mikael.westoo/coolifywrapper/issues

Contact:

• Email: info@startanaicompany.com

---

Ready to deploy? Follow the Quick Start above!