StartanAICompany/ai-recruit-site-template
Template
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Implement .saac.json configuration and email verification flow

Browse Source 
Complete rewrite of deployment script to use unified .saac.json
configuration file and integrate email verification for user registration.

Major Changes:
==============

1. **New Configuration System**
   - Replaced .deployment-uuid + deployment-info.txt with .saac.json
   - Single JSON file for all SAAC-related state
   - Secure file permissions (600)
   - Structured format with version tracking

2. **.saac.json Structure**
   ```json
   {
     "version": "1.0",
     "user": {
       "email": "user@example.com",
       "user_id": "uuid",
       "api_key": "cw_...",
       "verified": true,
       "registered_at": "timestamp"
     },
     "deployment": {
       "application_uuid": "uuid",
       "domain": "https://...",
       "deployed_at": "timestamp"
     }
   }
   ```

3. **Email Verification Flow** (NEW)
   - Registration prompts for email
   - Calls POST /api/v1/users/register
   - Saves initial config with verified: false
   - Prompts for verification code from MailHog
   - Calls POST /api/v1/users/verify
   - Updates config with verified: true
   - Only then allows deployment

4. **Auto-Detection Enhanced**
   ```
   No .saac.json           → Registration + Verification
   Exists, not verified    → Verification only
   Exists, verified, no app → Setup mode
   Exists, verified, has app → Update mode
   ```

5. **Helper Functions** (NEW)
   - load_config() - Loads all state from .saac.json using jq
   - save_config() - Saves state with secure permissions

6. **Removed Dependencies**
   - SAAC_API_KEY environment variable (now in .saac.json)
   - .deployment-uuid file (now in .saac.json)
   - deployment-info.txt file (now in .saac.json)

7. **New Dependency**
   - jq (JSON processor) - Required and checked at startup

8. **Updated .gitignore**
   - Added: .saac.json
   - Removed: .deployment-uuid, deployment-info.txt

Script Modes:
=============

./deploy-to-apps.sh           # Auto-detect
./deploy-to-apps.sh --setup   # Force new deployment
./deploy-to-apps.sh --update  # Force update existing
./deploy-to-apps.sh --status  # Check deployment status

Registration Flow:
==================

1. Script detects no .saac.json
2. Prompts: "Enter your email:"
3. Calls POST /users/register
4. Receives user_id and api_key
5. Saves to .saac.json with verified: false
6. Shows: "Check MailHog at https://mailhog.goryan.io"
7. Prompts: "Enter verification code from email:"
8. Calls POST /users/verify with code
9. Updates .saac.json with verified: true
10. Proceeds to application setup

Update Flow:
============

1. Script loads config from .saac.json
2. Extracts api_key automatically
3. Calls PATCH /applications/:uuid/env
4. Calls POST /applications/:uuid/deploy
5. Updates last_updated in .saac.json

Documentation Created:
======================

1. DEPLOYMENT_UPDATE_SUMMARY.md
   - Technical documentation
   - .saac.json schema
   - Helper function details
   - Flow diagrams
   - Security considerations

2. QUICK_START.md
   - User-friendly guide
   - First-time deployment walkthrough
   - Common scenarios
   - Troubleshooting tips

3. MIGRATION_GUIDE.md
   - Existing user migration instructions
   - Two migration options
   - Verification checklist
   - Rollback instructions
   - FAQ section

Benefits:
=========

✅ Single source of truth for all SAAC state
✅ No manual API key management
✅ Email verification integrated
✅ Secure file permissions
✅ Extensible JSON format
✅ Self-documenting structure
✅ Easier maintenance

Breaking Changes:
=================

- Must install jq
- Must migrate from old .deployment-uuid format
- SAAC_API_KEY env var no longer used
- Email verification required for new users

Migration Path:
===============

Option 1 (Recommended): Start fresh
- Delete old files
- Run new script
- Follow registration prompts

Option 2 (Advanced): Manual migration
- Create .saac.json with existing data
- Preserve deployment UUID
- Test functionality

Validation:
===========

✓ Bash syntax validated (bash -n)
✓ .saac.json in .gitignore
✓ Helper functions implemented
✓ Registration flow integrated
✓ Verification flow integrated
✓ All modes working
✓ File permissions set correctly

Script size: 471 → 657 lines
Complexity: Reduced (single config file)
Security: Improved (600 permissions, no env vars)

🤖 Generated with Claude Code
https://claude.com/claude-code

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
mikaelwestoo
2026-01-24 18:43:31 +01:00
parent d28fb10360
commit 2082c3caec
5 changed files with 1553 additions and 120 deletions
Download Patch File Download Diff File Expand all files Collapse all files

342
QUICK_START.md Normal file
View File

@@ -0,0 +1,342 @@
# Quick Start Guide - AI Recruitment Site Deployment
## Prerequisites
1. **Install jq** (JSON processor)
```bash
# Ubuntu/Debian
sudo apt install jq
# macOS
brew install jq
# Alpine Linux
apk add jq
```
2. **Get Gitea API Token** (only needed for first deployment)
- Go to https://git.startanaicompany.com
- Profile → Settings → Applications
- Generate New Token (grant 'repo' permissions)
- Save the token
3. **Configure your .env file**
```bash
cp .env.example .env
nano .env # Edit with your company information
```
---
## First-Time Deployment
### Step 1: Copy the Script
```bash
cp deploy-to-apps.example.sh deploy-to-apps.sh
```
### Step 2: Set Gitea Token
```bash
export GITEA_API_TOKEN='your_gitea_token_here'
```
### Step 3: Run the Script
```bash
./deploy-to-apps.sh
```
### Step 4: Follow the Prompts
The script will:
1. **Prompt for your email**
```
Enter your email address: you@example.com
```
2. **Register your account**
- Creates user account
- Generates API key
- Saves to `.saac.json`
3. **Request verification code**
```
Check your email at MailHog:
https://mailhog.goryan.io
Enter the verification code from the email:
```
4. **Create deployment**
- Sets up application
- Configures webhook
- Deploys your site
### Step 5: Wait for Deployment
Your site will be live in 2-3 minutes at:
```
https://<subdomain>recruit.startanaicompany.com
```
---
## Updating Your Site
### Step 1: Edit .env
```bash
nano .env
# Change COMPANY_NAME, colors, contact info, etc.
```
### Step 2: Deploy Updates
```bash
./deploy-to-apps.sh
# or
./deploy-to-apps.sh --update
```
The script will:
- Load configuration from `.saac.json`
- Update environment variables
- Trigger redeployment
Your changes will be live in 2-3 minutes.
---
## Checking Deployment Status
```bash
./deploy-to-apps.sh --status
```
Output:
```
Application UUID: 123e4567-e89b-12d3-a456-426614174000
Name: mycompany-recruit
Domain: https://mycompany.recruit.startanaicompany.com
Status: running
Repository: git@git.startanaicompany.com:myuser/myrepo.git
Branch: master
Created: 2026-01-24T12:00:00Z
```
---
## Understanding .saac.json
This file stores your credentials and deployment configuration:
```json
{
"user": {
"email": "you@example.com",
"user_id": "...",
"api_key": "...",
"verified": true
},
"deployment": {
"application_uuid": "...",
"domain": "..."
}
}
```
**Important:**
- ⚠️ Never commit this file to git (it's in `.gitignore`)
- ✅ Keep it secure (permissions set to 600)
- 📋 Backup this file to restore access
---
## Common Scenarios
### Scenario 1: Interrupted Registration
If you exit during registration/verification:
```bash
./deploy-to-apps.sh
```
The script will:
- Detect existing `.saac.json`
- Check verification status
- Resume where you left off
### Scenario 2: New Deployment on Existing Account
If you want to deploy a different site:
```bash
./deploy-to-apps.sh --setup
```
This will:
- Use existing credentials
- Create new application
- Update `.saac.json` with new deployment
### Scenario 3: Lost .saac.json
If you lose your `.saac.json` file:
**Option 1:** Re-register with same email
- Run `./deploy-to-apps.sh`
- Enter same email
- New API key will be generated
- Old deployments will still work with old API key
**Option 2:** Restore from backup
- Copy backed-up `.saac.json`
- Run `./deploy-to-apps.sh --status` to verify
---
## Troubleshooting
### Error: "jq: command not found"
**Solution:** Install jq
```bash
sudo apt install jq # Ubuntu/Debian
brew install jq # macOS
```
### Error: "Email verification failed"
**Causes:**
- Wrong verification code
- Code expired (valid for 24 hours)
**Solution:**
1. Check MailHog: https://mailhog.goryan.io
2. Copy code exactly as shown
3. Try again (re-run script if needed)
### Error: "Application not found"
**Causes:**
- Application was deleted
- Wrong API key
- Corrupt `.saac.json`
**Solution:**
```bash
# Create new deployment
./deploy-to-apps.sh --setup
```
### Error: "GITEA_API_TOKEN not set"
**Cause:** Token not exported (only needed for setup mode)
**Solution:**
```bash
export GITEA_API_TOKEN='your_token_here'
./deploy-to-apps.sh --setup
```
---
## Script Modes
### Auto-detect (Default)
```bash
./deploy-to-apps.sh
```
Automatically determines:
- No `.saac.json` → Registration + Setup
- `.saac.json` exists, unverified → Verification
- `.saac.json` exists, verified, no deployment → Setup
- `.saac.json` exists, verified, has deployment → Update
### Force Setup
```bash
./deploy-to-apps.sh --setup
```
Creates new deployment (warns if one already exists)
### Force Update
```bash
./deploy-to-apps.sh --update
```
Updates existing deployment (fails if none exists)
### Check Status
```bash
./deploy-to-apps.sh --status
```
Shows deployment information
---
## Security Best Practices
1. **Never commit `.saac.json`**
- Contains API key (like a password)
- Already in `.gitignore`
2. **Backup your `.saac.json`**
- Store in secure location
- Don't upload to public services
3. **Rotate API keys if compromised**
- Delete `.saac.json`
- Re-register with new email
- Create new deployment
4. **Use environment variables for Gitea token**
```bash
# Add to ~/.bashrc or ~/.zshrc
export GITEA_API_TOKEN='your_token_here'
```
---
## Next Steps
After deployment:
1. **Configure DNS** (if using custom domain)
- Add CNAME record
- Point to: `apps.startanaicompany.com`
2. **Customize your site**
- Edit `.env` file
- Run `./deploy-to-apps.sh` to update
3. **Monitor deployment**
- Use `--status` mode
- Check application logs
4. **Set up monitoring**
- Check site regularly
- Monitor uptime
- Test features
---
## Support
- **MailHog**: https://mailhog.goryan.io
- **Gitea**: https://git.startanaicompany.com
- **SAAC API**: https://apps.startanaicompany.com/api/v1
---
**Last Updated:** 2026-01-24