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)

./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)

./deploy-to-apps.sh --setup

• Creates NEW application
• Overwrites .deployment-uuid with new UUID
• Use case: Deploying to different subdomain/environment

3. Explicit Update

./deploy-to-apps.sh --update

• Requires .deployment-uuid to exist
• Updates environment variables
• Triggers redeployment
• Fails if .deployment-uuid not found

4. Status Check

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

• Shows current deployment info
• Fetches live status from API
• Shows domain, deployment status, etc.

---

Implementation Details

File Structure

.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

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

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

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

$ ./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)

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

$ ./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:

# 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