generated from StartanAICompany/ai-recruit-site-template
Initial commit
This commit is contained in:
417
MIGRATION_GUIDE.md
Normal file
417
MIGRATION_GUIDE.md
Normal file
@@ -0,0 +1,417 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user