ai-recruit-site-template/DEPLOYMENT_SCRIPT_PROPOSAL.md

# Deployment Script Enhancement Proposal

## Problem Statement

The current `deploy-to-apps.sh` script only handles initial deployment. Running it a second time will:
1. Attempt to create a duplicate application
2. Likely fail with "subdomain already exists" error
3. Have no way to update existing application's environment variables
4. Have no way to trigger redeployment

## Solution: Setup vs Update Modes

### Architecture

```
.deployment-uuid  (git-ignored file storing application UUID)
deploy-to-apps.sh (enhanced script with mode detection)
```

### Script Modes

#### 1. Auto-Detection (Default)
```bash
./deploy-to-apps.sh
```
- Checks if `.deployment-uuid` exists
- **If NOT exists:** Run setup mode (first deployment)
- **If exists:** Run update mode (redeploy with new env vars)

#### 2. Explicit Setup (Force New Deployment)
```bash
./deploy-to-apps.sh --setup
```
- Creates NEW application
- Overwrites `.deployment-uuid` with new UUID
- Use case: Deploying to different subdomain/environment

#### 3. Explicit Update
```bash
./deploy-to-apps.sh --update
```
- Requires `.deployment-uuid` to exist
- Updates environment variables
- Triggers redeployment
- Fails if `.deployment-uuid` not found

#### 4. Status Check
```bash
./deploy-to-apps.sh --status
```
- Shows current deployment info
- Fetches live status from API
- Shows domain, deployment status, etc.

---

## Implementation Details

### File Structure

```bash
.deployment-uuid          # Single line: application UUID
deployment-info.txt       # Human-readable deployment details
.gitignore               # Must include .deployment-uuid
```

### Setup Mode Flow

1. Check if subdomain already deployed (optional safety check)
2. Create application via `POST /api/v1/applications`
3. Save UUID to `.deployment-uuid`
4. Set up Gitea webhook (only once)
5. Save deployment info to `deployment-info.txt`
6. Show success message with next steps

### Update Mode Flow

1. Read UUID from `.deployment-uuid`
2. Verify application exists via `GET /api/v1/applications/:uuid`
3. Update environment variables via `PATCH /api/v1/applications/:uuid/env`
4. Trigger redeployment via `POST /api/v1/applications/:uuid/deploy`
5. Show redeployment progress

### Status Mode Flow

1. Read UUID from `.deployment-uuid`
2. Fetch application details via `GET /api/v1/applications/:uuid`
3. Display formatted status information

---

## API Endpoints Used

### Setup Mode
```bash
POST /api/v1/applications
→ Returns: { application_uuid, domain, webhook_url, ... }

POST https://git.startanaicompany.com/api/v1/repos/{owner}/{repo}/hooks
→ Sets up Gitea webhook (one-time)
```

### Update Mode
```bash
GET /api/v1/applications/:uuid
→ Verify application exists

PATCH /api/v1/applications/:uuid/env
→ Body: { "variables": { "COMPANY_NAME": "...", ... } }

POST /api/v1/applications/:uuid/deploy
→ Triggers redeployment
```

### Status Mode
```bash
GET /api/v1/applications/:uuid
→ Returns application details and status
```

---

## Error Handling

### Setup Mode Errors
- **Subdomain already exists:** Suggest using `--update` or different subdomain
- **API key invalid:** Show registration instructions
- **Gitea token invalid:** Show token generation instructions
- **Webhook already exists:** Warn but continue (non-fatal)

### Update Mode Errors
- **No .deployment-uuid file:** Suggest running `--setup` first
- **Application not found:** UUID invalid or app deleted, suggest `--setup`
- **Environment variable validation failed:** Show which vars are invalid
- **Deployment failed:** Show error from API

---

## Example Usage

### First Deployment
```bash
$ ./deploy-to-apps.sh

========================================
  AI Recruitment Site Deployment
========================================
📝 Mode: SETUP (first deployment)
📦 Configuration:
  Company: Acme Corp
  Repository: git@git.startanaicompany.com:user/acme-recruit.git
  Domain: https://acmerecruit.startanaicompany.com

📝 Creating application on StartAnAiCompany server...
✅ Application created!
   Application UUID: abc-123-def-456
   Domain: https://acmerecruit.startanaicompany.com

💾 UUID saved to .deployment-uuid
🪝 Setting up deployment webhook...
✅ Webhook configured for automatic deployments

========================================
  Deployment Complete!
========================================
Your site will be available in 2-3 minutes.

Next runs will automatically UPDATE this deployment.
To deploy a new site, use: ./deploy-to-apps.sh --setup
```

### Update Deployment (Changed Company Name)
```bash
$ ./deploy-to-apps.sh

========================================
  AI Recruitment Site Deployment
========================================
📝 Mode: UPDATE (existing deployment)
📦 Configuration:
  Application UUID: abc-123-def-456
  Company: New Company Name (CHANGED)
  Domain: https://acmerecruit.startanaicompany.com

🔄 Updating environment variables...
✅ Environment variables updated (8 variables)

🚀 Triggering redeployment...
✅ Deployment triggered

========================================
  Update Complete!
========================================
Your changes will be live in 2-3 minutes.

Monitor deployment:
  ./deploy-to-apps.sh --status
```

### Check Status
```bash
$ ./deploy-to-apps.sh --status

========================================
  Deployment Status
========================================
Application UUID: abc-123-def-456
Name: acme-recruit
Domain: https://acmerecruit.startanaicompany.com
Status: running
Last deployment: 2026-01-24 17:30:00 UTC

Company: Acme Corp
Repository: git@git.startanaicompany.com:user/acme-recruit.git
Branch: master
```

---

## .gitignore Updates Required

Add to `.gitignore`:
```
# Deployment configuration (contains UUID, API keys)
.deployment-uuid
deployment-info.txt
deploy-to-apps.sh

# Keep the example for users to copy
!deploy-to-apps.example.sh
```

---

## Benefits

1. ✅ **Idempotent:** Can run script multiple times safely
2. ✅ **User-friendly:** Auto-detects mode based on context
3. ✅ **Flexible:** Supports multiple deployment scenarios
4. ✅ **Safe:** Prevents duplicate applications
5. ✅ **Traceable:** UUID stored locally for easy updates
6. ✅ **Stateful:** Remembers previous deployment
7. ✅ **Informative:** Clear feedback on what's happening

---

## Migration for Existing Users

If someone already ran the old script:

```bash
# Find their application UUID
curl -H "X-API-Key: $SAAC_API_KEY" https://apps.startanaicompany.com/api/v1/applications

# Save UUID to file
echo "abc-123-def-456" > .deployment-uuid

# Now they can use update mode
./deploy-to-apps.sh --update
```

---

## Implementation Priority

### Phase 1 (Must Have)
1. Auto-detection (check for `.deployment-uuid`)
2. Setup mode (create new + save UUID)
3. Update mode (update env vars + redeploy)

### Phase 2 (Nice to Have)
4. Status mode (query current status)
5. Enhanced error messages
6. Safety checks (subdomain conflicts, etc.)

### Phase 3 (Future)
7. Rollback support
8. Multiple environment support (dev/staging/prod)
9. Configuration validation before deployment