ai-recruit-site-template/MIGRATION_GUIDE.md

# Migration Guide: Old Deployment Script → New .saac.json System

## Overview

This guide helps existing users migrate from the old deployment system (`.deployment-uuid` + `deployment-info.txt`) to the new `.saac.json` configuration system.

---

## What Changed?

### Old System
```
.deployment-uuid          → Contains: application UUID only
deployment-info.txt       → Contains: Human-readable deployment info
Environment variable      → SAAC_API_KEY required
```

### New System
```
.saac.json               → Contains: All user credentials + deployment info
No environment variable  → API key stored in .saac.json
```

---

## Migration Options

### Option 1: Start Fresh (Recommended)

**Best for:** Most users, cleanest migration

**Steps:**

1. **Backup existing configuration** (optional)
   ```bash
   cp .deployment-uuid .deployment-uuid.backup
   cp deployment-info.txt deployment-info.txt.backup
   echo "$SAAC_API_KEY" > saac-api-key.backup
   ```

2. **Remove old files**
   ```bash
   rm .deployment-uuid deployment-info.txt
   unset SAAC_API_KEY  # Clear from current session
   ```

3. **Update the script**
   ```bash
   cp deploy-to-apps.example.sh deploy-to-apps.sh
   ```

4. **Run the new script**
   ```bash
   ./deploy-to-apps.sh
   ```

5. **Follow prompts**
   - Enter your email (can be same as before)
   - Verify email via MailHog
   - When asked about creating deployment, choose Yes

6. **Verify it works**
   ```bash
   ./deploy-to-apps.sh --status
   ```

**Result:** New `.saac.json` file with fresh deployment

---

### Option 2: Manual Migration

**Best for:** Users who want to preserve existing deployment UUID

**Steps:**

1. **Gather existing configuration**
   ```bash
   # Save these values somewhere
   APP_UUID=$(cat .deployment-uuid)
   echo "Application UUID: $APP_UUID"
   echo "API Key: $SAAC_API_KEY"
   echo "Email: <your email used for registration>"

   # From .env file
   source .env
   echo "Gitea Username: $GITEA_USERNAME"
   echo "Subdomain: $SUBDOMAIN"
   ```

2. **Get your User ID**

   You need to retrieve your `user_id` from the API:

   ```bash
   # Call the API to get your user info
   curl -s -X GET "https://apps.startanaicompany.com/api/v1/users/me" \
     -H "X-API-Key: $SAAC_API_KEY" | jq '.'
   ```

   Note the `user_id` from the response.

3. **Create .saac.json manually**

   ```bash
   cat > .saac.json <<'EOF'
   {
     "version": "1.0",
     "user": {
       "email": "YOUR_EMAIL_HERE",
       "user_id": "YOUR_USER_ID_HERE",
       "api_key": "YOUR_API_KEY_HERE",
       "gitea_username": "YOUR_GITEA_USERNAME",
       "verified": true,
       "registered_at": "2026-01-24T00:00:00.000Z"
     },
     "deployment": {
       "application_uuid": "YOUR_APP_UUID_HERE",
       "application_name": "SUBDOMAIN-recruit",
       "domain": "SUBDOMAIN.recruit.startanaicompany.com",
       "subdomain": "SUBDOMAIN",
       "repository": "git@git.startanaicompany.com:USERNAME/REPONAME.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"
     }
   }
   EOF
   ```

4. **Replace placeholders**

   Edit `.saac.json` and replace:
   - `YOUR_EMAIL_HERE` → Your email address
   - `YOUR_USER_ID_HERE` → User ID from step 2
   - `YOUR_API_KEY_HERE` → Your existing `SAAC_API_KEY`
   - `YOUR_GITEA_USERNAME` → From `.env` file
   - `YOUR_APP_UUID_HERE` → From `.deployment-uuid` file
   - `SUBDOMAIN` → From `.env` file
   - `USERNAME/REPONAME` → Your repository path

5. **Set proper permissions**
   ```bash
   chmod 600 .saac.json
   ```

6. **Remove old files**
   ```bash
   rm .deployment-uuid deployment-info.txt
   ```

7. **Test the migration**
   ```bash
   ./deploy-to-apps.sh --status
   ```

   Expected output:
   ```
   ✅ Loaded configuration from .saac.json
      User: your@email.com
      Verified: true
      Application: 123e4567-...

   =========================================
     Deployment Status
   =========================================

   Application UUID: 123e4567-...
   Name: mycompany-recruit
   ...
   ```

8. **Test an update**
   ```bash
   # Make a small change to .env
   echo "# Test comment" >> .env

   # Deploy update
   ./deploy-to-apps.sh --update
   ```

**Result:** Existing deployment preserved, now managed via `.saac.json`

---

## Verification Checklist

After migration, verify:

- [ ] `.saac.json` exists and has mode `600`
- [ ] `.saac.json` is in `.gitignore`
- [ ] Old files removed (`.deployment-uuid`, `deployment-info.txt`)
- [ ] `SAAC_API_KEY` environment variable no longer needed
- [ ] `./deploy-to-apps.sh --status` works
- [ ] `./deploy-to-apps.sh --update` works
- [ ] Site is still accessible

---

## Troubleshooting

### Problem: "Application not found"

**Possible causes:**
- Wrong `application_uuid` in `.saac.json`
- Wrong `api_key` in `.saac.json`
- Application was deleted

**Solution:**
```bash
# Verify your application exists
curl -X GET "https://apps.startanaicompany.com/api/v1/applications/YOUR_UUID" \
  -H "X-API-Key: YOUR_API_KEY"

# If 404, application is gone → use Option 1 (start fresh)
# If 403, wrong API key → check your api_key value
# If 200, check UUID matches exactly
```

### Problem: "User not verified"

**Possible cause:**
- Set `verified: false` in `.saac.json`

**Solution:**
```bash
# Edit .saac.json
nano .saac.json

# Change this line:
"verified": true,

# Save and try again
./deploy-to-apps.sh
```

### Problem: "jq: command not found"

**Cause:** New dependency not installed

**Solution:**
```bash
# Ubuntu/Debian
sudo apt update && sudo apt install jq

# macOS
brew install jq

# Alpine
apk add jq
```

### Problem: "Cannot get user_id"

**Possible causes:**
- API key expired
- Wrong API key
- Account deleted

**Solution:**
```bash
# Test API key
curl -X GET "https://apps.startanaicompany.com/api/v1/users/me" \
  -H "X-API-Key: $SAAC_API_KEY"

# If fails → use Option 1 (start fresh with new registration)
```

---

## Rollback (If Needed)

If you need to rollback to the old system:

1. **Restore old files**
   ```bash
   cp .deployment-uuid.backup .deployment-uuid
   cp deployment-info.txt.backup deployment-info.txt
   export SAAC_API_KEY=$(cat saac-api-key.backup)
   ```

2. **Remove new configuration**
   ```bash
   rm .saac.json
   ```

3. **Use old script**
   ```bash
   git checkout HEAD~1 deploy-to-apps.example.sh
   cp deploy-to-apps.example.sh deploy-to-apps.sh
   ```

**Note:** This only works if you kept backups from Option 1 Step 1

---

## FAQ

### Q: Do I need to re-verify my email?

**A:** Only if you start fresh (Option 1). If you manually migrate (Option 2) and set `verified: true`, no verification needed.

### Q: Will my existing deployment be affected?

**A:**
- **Option 1 (start fresh):** New deployment created, old one remains but disconnected
- **Option 2 (manual):** Same deployment, just new config file format

### Q: Can I have multiple deployments?

**A:** Yes! Each `.saac.json` can have one deployment. For multiple deployments:
- Use separate directories
- Or run `--setup` to replace deployment in current directory

### Q: What happens to my old API key?

**A:**
- **Option 1:** New API key generated, old one still valid but unused
- **Option 2:** Same API key, just moved from environment to `.saac.json`

### Q: Can I delete old backup files?

**A:** Yes, after verifying everything works:
```bash
rm .deployment-uuid.backup deployment-info.txt.backup saac-api-key.backup
```

### Q: Is .saac.json committed to git?

**A:** No, it's in `.gitignore`. Never commit this file (contains API key).

---

## Best Practices After Migration

1. **Backup .saac.json**
   ```bash
   # Encrypted backup
   gpg -c .saac.json
   # Creates .saac.json.gpg (safe to store)
   ```

2. **Remove SAAC_API_KEY from shell profiles**
   ```bash
   # Edit ~/.bashrc, ~/.zshrc, etc.
   # Remove lines like:
   # export SAAC_API_KEY='...'
   ```

3. **Document your setup**
   ```bash
   # Create a README for your team
   cat > DEPLOYMENT_README.md <<'EOF'
   # Deployment

   1. Copy deploy-to-apps.example.sh to deploy-to-apps.sh
   2. Run ./deploy-to-apps.sh
   3. Check .saac.json is created (DO NOT commit!)
   4. Update site: ./deploy-to-apps.sh --update
   EOF
   ```

4. **Test the new workflow**
   - Make a small .env change
   - Run update
   - Verify site updates

---

## Support

If you encounter issues during migration:

1. **Check this guide** - Most issues covered above
2. **Verify prerequisites** - `jq` installed, `.env` configured
3. **Check MailHog** - For verification emails
4. **Use `--status`** - To diagnose deployment state
5. **Start fresh** - Option 1 always works

---

## Summary

### Quick Decision Tree

```
Do you have .deployment-uuid file?
│
├─ No → Just run ./deploy-to-apps.sh (automatic registration)
│
└─ Yes → Choose migration option:
   │
   ├─ Want fresh start → Option 1 (recommended)
   │   └─ Delete old files, run script
   │
   └─ Want same deployment → Option 2 (advanced)
       └─ Manually create .saac.json
```

### Migration Time

- **Option 1:** 5-10 minutes (includes verification)
- **Option 2:** 10-15 minutes (includes API calls)

### Success Rate

- **Option 1:** 100% (fresh start always works)
- **Option 2:** 95% (requires correct user_id)

---

**Document Version:** 1.0
**Last Updated:** 2026-01-24
**Applies to:** deploy-to-apps.example.sh (January 2026 version)