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

```json
{
  "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**
   ```bash
   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:
   ```bash
   rm .deployment-uuid deployment-info.txt
   ```

2. Run the new script:
   ```bash
   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:
   ```bash
   APP_UUID=$(cat .deployment-uuid)
   # Note your SAAC_API_KEY from environment
   # Note your email used for registration
   ```

2. Create `.saac.json` manually:
   ```json
   {
     "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:
   ```bash
   chmod 600 .saac.json
   ```

4. Delete old files:
   ```bash
   rm .deployment-uuid deployment-info.txt
   ```

5. Test the script:
   ```bash
   ./deploy-to-apps.sh --status
   ```

---

## Validation

### Script Validation

```bash
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

- [x] Bash syntax validation
- [x] Helper function logic
- [x] Configuration file structure
- [x] Flow diagram accuracy
- [x] 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

```bash
$ 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)

```bash
$ ./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