ai-recruit-site-template/DEPLOYMENT_UPDATE_SUMMARY.md

Deployment Script Update Summary

Overview

The deploy-to-apps.example.sh script has been completely rewritten to use .saac.json for configuration storage and implement a streamlined email verification flow. This eliminates the need for manual API key management and provides a better user experience.

---

Changes Made

1. Configuration File Migration

Old System:

• .deployment-uuid - Stored only the application UUID
• deployment-info.txt - Human-readable deployment info
• SAAC_API_KEY - Required as environment variable

New System:

• .saac.json - Stores all user credentials and deployment configuration
• No separate info file needed
• No environment variable for API key

2. .saac.json Structure

{
  "version": "1.0",
  "user": {
    "email": "user@example.com",
    "user_id": "uuid-here",
    "api_key": "api-key-here",
    "gitea_username": "username",
    "verified": true,
    "registered_at": "2026-01-24T12:00:00.000Z"
  },
  "deployment": {
    "application_uuid": "app-uuid-here",
    "application_name": "subdomain-recruit",
    "domain": "subdomain.recruit.startanaicompany.com",
    "subdomain": "subdomain",
    "repository": "git@git.startanaicompany.com:user/repo.git",
    "deployed_at": "2026-01-24T12:00:00.000Z",
    "last_updated": "2026-01-24T12:30:00.000Z"
  },
  "config": {
    "saac_api": "https://apps.startanaicompany.com/api/v1",
    "gitea_api": "https://git.startanaicompany.com/api/v1"
  }
}

3. New Helper Functions

load_config()

• Loads configuration from .saac.json
• Extracts user credentials, verification status, and deployment info
• Returns 0 if file exists, 1 if not

save_config()

• Saves configuration to .saac.json
• Sets file permissions to 600 (read/write for owner only)
• Updates last_updated timestamp automatically

4. Email Verification Flow

First-Time Registration (No .saac.json)

1. Prompt for Email

   • User enters email address
   • Gitea username pulled from .env

2. Register User

   POST /users/register
   {
     "email": "user@example.com",
     "gitea_username": "username"
   }
   

   • Returns user_id and api_key

3. Save Unverified Configuration

   • Creates .saac.json with verified: false
   • File is immediately saved (safe to exit and resume)

4. Email Verification

   • User checks MailHog at https://mailhog.goryan.io
   • Enters verification code
   • Script calls POST /users/verify
   • Updates .saac.json with verified: true

Returning User (Unverified)

If .saac.json exists but verified: false:

1. Prompt for verification code
2. Verify email
3. Update configuration

Verified User

If .saac.json exists and verified: true:

• Loads configuration silently
• Proceeds to auto-detect mode (setup or update)

5. Auto-Detection Logic

┌─────────────────────────────────────┐
│ Does .saac.json exist?              │
└──────────┬──────────────────────────┘
           │
    ┌──────┴──────┐
    │ NO          │ YES
    ▼             ▼
┌───────┐    ┌──────────────┐
│REGISTER│    │ verified?    │
└───┬───┘    └──────┬───────┘
    │               │
    ▼         ┌─────┴─────┐
┌────────┐   │NO        YES│
│ VERIFY │   ▼             ▼
└───┬────┘  ┌──────┐  ┌──────────────┐
    │       │VERIFY│  │ has app_uuid?│
    │       └──┬───┘  └──────┬───────┘
    │          │             │
    └──────────┴─────────────┤
                       ┌─────┴─────┐
                       │NO        YES│
                       ▼             ▼
                   ┌──────┐     ┌──────┐
                   │SETUP │     │UPDATE│
                   └──────┘     └──────┘

6. Removed Features

• SAAC_API_KEY environment variable requirement (now in .saac.json)
• deployment-info.txt file (replaced by .saac.json)
• .deployment-uuid file (replaced by .saac.json)

7. Updated .gitignore

Removed:

• deployment-info.txt
• .deployment-uuid

Added:

• .saac.json

8. New Dependencies

• jq - JSON processor (required)
  • Ubuntu/Debian: sudo apt install jq
  • macOS: brew install jq
  • Alpine: apk add jq

Script checks for jq and provides installation instructions if missing.

---

Flow Diagrams

First-Time User Flow

┌─────────────────────────────────────────────────────────┐
│ 1. User runs: ./deploy-to-apps.sh                      │
└─────────────────────┬───────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────┐
│ 2. No .saac.json found                                  │
│    → Prompt for email                                   │
│    → Read GITEA_USERNAME from .env                      │
└─────────────────────┬───────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────┐
│ 3. POST /users/register                                 │
│    → Receive user_id and api_key                        │
└─────────────────────┬───────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────┐
│ 4. Save .saac.json (verified: false)                    │
└─────────────────────┬───────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────┐
│ 5. Show MailHog URL                                     │
│    → Prompt for verification code                       │
└─────────────────────┬───────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────┐
│ 6. POST /users/verify                                   │
│    → Check response for "verified": true                │
└─────────────────────┬───────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────┐
│ 7. Update .saac.json (verified: true)                   │
└─────────────────────┬───────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────┐
│ 8. Auto-detect → SETUP mode (no app_uuid)              │
│    → Create new deployment                              │
└─────────────────────────────────────────────────────────┘

Returning User Flow (Verified, Deployed)

┌─────────────────────────────────────────────────────────┐
│ 1. User runs: ./deploy-to-apps.sh                      │
└─────────────────────┬───────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────┐
│ 2. Load .saac.json                                      │
│    → verified: true                                     │
│    → app_uuid: exists                                   │
└─────────────────────┬───────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────┐
│ 3. Auto-detect → UPDATE mode                            │
└─────────────────────┬───────────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────────┐
│ 4. Update environment variables                         │
│    → Trigger redeployment                               │
│    → Update .saac.json timestamps                       │
└─────────────────────────────────────────────────────────┘

---

Migration Instructions for Existing Users

If You Have .deployment-uuid and deployment-info.txt

Option 1: Start Fresh (Recommended)

1. Delete old files:

   rm .deployment-uuid deployment-info.txt
   

2. Run the new script:

   cp deploy-to-apps.example.sh deploy-to-apps.sh
   ./deploy-to-apps.sh
   

3. Follow the registration and verification prompts

4. When asked to setup, confirm to create new deployment

Option 2: Manual Migration

1. Note your existing configuration:

   APP_UUID=$(cat .deployment-uuid)
   # Note your SAAC_API_KEY from environment
   # Note your email used for registration
   

2. Create .saac.json manually:

   {
     "version": "1.0",
     "user": {
       "email": "your@email.com",
       "user_id": "your-user-id",
       "api_key": "your-api-key",
       "gitea_username": "your-username",
       "verified": true,
       "registered_at": "2026-01-24T00:00:00.000Z"
     },
     "deployment": {
       "application_uuid": "your-app-uuid",
       "application_name": "subdomain-recruit",
       "domain": "subdomain.recruit.startanaicompany.com",
       "subdomain": "subdomain",
       "repository": "git@git.startanaicompany.com:user/repo.git",
       "deployed_at": "2026-01-24T00:00:00.000Z",
       "last_updated": "2026-01-24T00:00:00.000Z"
     },
     "config": {
       "saac_api": "https://apps.startanaicompany.com/api/v1",
       "gitea_api": "https://git.startanaicompany.com/api/v1"
     }
   }
   

3. Set proper permissions:

   chmod 600 .saac.json
   

4. Delete old files:

   rm .deployment-uuid deployment-info.txt
   

5. Test the script:

   ./deploy-to-apps.sh --status
   

---

Validation

Script Validation

bash -n deploy-to-apps.example.sh

Result: ✅ No syntax errors

Required Dependencies

• bash - Bourne Again Shell
• curl - HTTP client
• jq - JSON processor ⚠️ NEW REQUIREMENT

File Permissions

The script automatically sets .saac.json to 600 (read/write for owner only) to protect sensitive credentials.

---

Security Considerations

.saac.json Contains Sensitive Data

Never commit this file to git!

The file contains:

• User email
• API key (equivalent to password)
• User ID
• Application UUIDs

Gitignore Protection

The .gitignore file now includes .saac.json to prevent accidental commits.

File Permissions

The script sets .saac.json to mode 600:

• Owner: read/write
• Group: none
• Others: none

---

Backward Compatibility

Breaking Changes

1. SAAC_API_KEY environment variable no longer used

   • Old: Required in environment
   • New: Stored in .saac.json

2. Files no longer created

   • .deployment-uuid → replaced by .saac.json
   • deployment-info.txt → replaced by .saac.json

3. New dependency

   • jq now required for JSON processing

Non-Breaking Changes

1. All modes still work

   • ./deploy-to-apps.sh (auto-detect)
   • ./deploy-to-apps.sh --setup
   • ./deploy-to-apps.sh --update
   • ./deploy-to-apps.sh --status

2. GITEA_API_TOKEN still required for setup

   • Only needed for webhook creation during initial setup

3. All .env variables unchanged

   • Same company configuration variables
   • Same repository configuration

---

Testing Checklist

✅ Completed

• Bash syntax validation
• Helper function logic
• Configuration file structure
• Flow diagram accuracy
• Migration instructions

🔄 To Be Tested

• First-time registration flow
• Email verification flow
• Unverified user resumption
• Auto-detect mode logic
• Setup mode with .saac.json
• Update mode with .saac.json
• Status mode with .saac.json
• Manual migration from old files

---

Example Usage

First-Time User

$ cp deploy-to-apps.example.sh deploy-to-apps.sh
$ ./deploy-to-apps.sh

=========================================
  First-Time Setup
=========================================

No configuration found. Let's register your account.

Enter your email address: user@example.com

📧 Registering user: user@example.com
   Gitea username: myusername

✅ User registered!
   User ID: 123e4567-e89b-12d3-a456-426614174000

💾 Configuration saved to .saac.json

=========================================
  Email Verification
=========================================

📧 Verification email sent to: user@example.com

🔍 Check your email at MailHog:
   https://mailhog.goryan.io

Enter the verification code from the email: ABC123

🔐 Verifying email...
✅ Email verified successfully!

💾 Configuration saved to .saac.json

=========================================
  AI Recruitment Site Deployment
=========================================
📝 Mode: SETUP (new deployment)

...

Returning User (Update)

$ ./deploy-to-apps.sh

✅ Loaded configuration from .saac.json
   User: user@example.com
   Verified: true
   Application: 123e4567-e89b-12d3-a456-426614174000

=========================================
  AI Recruitment Site Deployment
=========================================
📝 Mode: UPDATE (existing deployment)

...

---

Support

For issues or questions:

1. Check MailHog for verification emails: https://mailhog.goryan.io
2. Verify .saac.json exists and has correct permissions
3. Ensure jq is installed
4. Check SAAC API status

---

Document Version: 1.0 Last Updated: 2026-01-24 Script Version: Updated with .saac.json support