StartanAICompany/ai-recruit-site-template
Template
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Implement enhanced deployment script with auto-detection

Browse Source 
Major Enhancement: Smart deployment with setup/update modes

Features Added:
==============

1. **Auto-Detection Mode** (default)
   - Checks for .deployment-uuid file
   - First run → Setup mode (creates new deployment)
   - Subsequent runs → Update mode (updates existing)
   - No flags needed for common workflows

2. **Three Operation Modes:**

   A. Setup Mode (--setup or auto if no UUID)
      - Creates NEW application via POST /api/v1/applications
      - Saves UUID to .deployment-uuid file (git-ignored)
      - Sets up Gitea webhook (one-time)
      - Warns if UUID file already exists

   B. Update Mode (--update or auto if UUID exists)
      - Reads UUID from .deployment-uuid
      - Verifies application exists: GET /api/v1/applications/:uuid
      - Updates env vars: PATCH /api/v1/applications/:uuid/env
      - Triggers redeploy: POST /api/v1/applications/:uuid/deploy
      - GITEA_API_TOKEN not required (webhook already configured)

   C. Status Mode (--status)
      - Fetches current deployment details
      - Shows application info, status, domain
      - Provides monitoring commands

3. **UUID Persistence**
   - .deployment-uuid file stores application UUID
   - Enables stateful deployments
   - Prevents duplicate application creation
   - Git-ignored for security

4. **Improved User Experience**
   - Clear mode indication (SETUP/UPDATE/STATUS)
   - Verification step before overwriting existing deployment
   - Comprehensive error messages with actionable steps
   - Updated deployment-info.txt with mode information
   - Smart dependency checks (GITEA_TOKEN only for setup)

5. **Updated .gitignore**
   - Added .deployment-uuid to prevent accidental commits

Usage Examples:
===============

# First deployment (auto-detects no UUID → setup)
./deploy-to-apps.sh
→ Creates application, saves UUID, sets up webhook

# Update after changing .env (auto-detects UUID → update)
./deploy-to-apps.sh
→ Updates env vars, triggers redeployment

# Force new deployment
./deploy-to-apps.sh --setup

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

Benefits:
=========
✅ Idempotent - Can run multiple times safely
✅ Stateful - Remembers previous deployments
✅ User-friendly - Automatic mode detection
✅ Safe - Prevents duplicate applications
✅ Flexible - Supports multiple scenarios
✅ Clear feedback - Shows exactly what's happening

Files Modified:
===============
- deploy-to-apps.example.sh: Complete rewrite with 3 modes
- .gitignore: Added .deployment-uuid
- DEPLOYMENT_SCRIPT_PROPOSAL.md: Full design document

Migration for Existing Users:
==============================
If you already deployed with the old script:
1. Find your UUID: curl -H "X-API-Key: $SAAC_API_KEY" $SAAC_API/applications
2. Save it: echo "your-uuid" > .deployment-uuid
3. Run updates: ./deploy-to-apps.sh

🤖 Generated with Claude Code
https://claude.com/claude-code

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
mikaelwestoo
2026-01-24 17:42:08 +01:00
parent 2f0e1b19bb
commit d28fb10360
3 changed files with 573 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

279
DEPLOYMENT_SCRIPT_PROPOSAL.md Normal file
View File

@@ -0,0 +1,279 @@
# 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