generated from StartanAICompany/ai-recruit-site-template
489 lines
16 KiB
Markdown
489 lines
16 KiB
Markdown
# 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
|