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

   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

   rm .deployment-uuid deployment-info.txt
   unset SAAC_API_KEY  # Clear from current session
   

3. Update the script

   cp deploy-to-apps.example.sh deploy-to-apps.sh
   

4. Run the new script

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

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

   # 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:

   # 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

   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

   chmod 600 .saac.json
   

6. Remove old files

   rm .deployment-uuid deployment-info.txt
   

7. Test the migration

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

   # 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:

# 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:

# 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:

# 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:

# 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

   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

   rm .saac.json
   

3. Use old script

   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:

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

   # Encrypted backup
   gpg -c .saac.json
   # Creates .saac.json.gpg (safe to store)
   

2. Remove SAAC_API_KEY from shell profiles

   # Edit ~/.bashrc, ~/.zshrc, etc.
   # Remove lines like:
   # export SAAC_API_KEY='...'
   

3. Document your setup

   # 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)