generated from StartanAICompany/ai-recruit-site-template
Initial commit
This commit is contained in:
328
DEPLOYMENT_GUIDE.md
Normal file
328
DEPLOYMENT_GUIDE.md
Normal file
@@ -0,0 +1,328 @@
|
||||
# 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!
|
||||
Reference in New Issue
Block a user