docs: Add placeholder metadata deployment guide
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
a04e7cc042
commit
b7afa98639
262
docs/PLACEHOLDER_METADATA_DEPLOYMENT_GUIDE.md
Normal file
262
docs/PLACEHOLDER_METADATA_DEPLOYMENT_GUIDE.md
Normal file
|
|
@ -0,0 +1,262 @@
|
|||
# Placeholder Metadata System - Deployment Guide
|
||||
|
||||
**Status:** ✅ Code deployed to develop branch
|
||||
**Auto-Deploy:** Gitea runner should deploy to dev.mitai.jinkendo.de automatically
|
||||
|
||||
---
|
||||
|
||||
## Deployment Status
|
||||
|
||||
### ✅ Completed
|
||||
|
||||
1. **Code committed to develop branch**
|
||||
- Commit: `a04e7cc`
|
||||
- 9 files changed, 3889 insertions(+)
|
||||
- All new modules and documentation included
|
||||
|
||||
2. **Pushed to Gitea**
|
||||
- Remote: http://192.168.2.144:3000/Lars/mitai-jinkendo
|
||||
- Branch: develop
|
||||
- Auto-deploy should trigger
|
||||
|
||||
---
|
||||
|
||||
## Post-Deployment Steps
|
||||
|
||||
### 1. Wait for Auto-Deploy
|
||||
|
||||
The Gitea runner should automatically deploy to:
|
||||
- **URL:** https://dev.mitai.jinkendo.de
|
||||
- **Container:** bodytrack-dev (Port 3099/8099)
|
||||
|
||||
Check deployment status:
|
||||
```bash
|
||||
# On Raspberry Pi
|
||||
cd /home/lars/docker/bodytrack-dev
|
||||
docker compose logs -f backend --tail=100
|
||||
```
|
||||
|
||||
### 2. Generate Catalog Files (Manual)
|
||||
|
||||
Once deployed, SSH into the Raspberry Pi and run:
|
||||
|
||||
```bash
|
||||
# SSH to Pi
|
||||
ssh lars@192.168.2.49
|
||||
|
||||
# Navigate to container directory
|
||||
cd /home/lars/docker/bodytrack-dev
|
||||
|
||||
# Generate catalog files
|
||||
docker compose exec backend python /app/generate_placeholder_catalog.py
|
||||
|
||||
# Verify generated files
|
||||
docker compose exec backend ls -lh /app/docs/PLACEHOLDER_*.md
|
||||
docker compose exec backend ls -lh /app/docs/PLACEHOLDER_*.json
|
||||
```
|
||||
|
||||
**Expected output files:**
|
||||
- `/app/docs/PLACEHOLDER_CATALOG_EXTENDED.json`
|
||||
- `/app/docs/PLACEHOLDER_CATALOG_EXTENDED.md`
|
||||
- `/app/docs/PLACEHOLDER_GAP_REPORT.md`
|
||||
- `/app/docs/PLACEHOLDER_EXPORT_SPEC.md`
|
||||
|
||||
### 3. Test Extended Export Endpoint
|
||||
|
||||
```bash
|
||||
# Get auth token first
|
||||
TOKEN=$(curl -s -X POST https://dev.mitai.jinkendo.de/api/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"email":"YOUR_EMAIL","password":"YOUR_PASSWORD"}' \
|
||||
| jq -r '.token')
|
||||
|
||||
# Test extended export
|
||||
curl -s -H "X-Auth-Token: $TOKEN" \
|
||||
https://dev.mitai.jinkendo.de/api/prompts/placeholders/export-values-extended \
|
||||
| jq '.metadata.summary'
|
||||
```
|
||||
|
||||
**Expected response:**
|
||||
```json
|
||||
{
|
||||
"total_placeholders": 116,
|
||||
"available": 98,
|
||||
"missing": 18,
|
||||
"by_type": {
|
||||
"atomic": 85,
|
||||
"interpreted": 20,
|
||||
"raw_data": 8,
|
||||
"legacy_unknown": 3
|
||||
},
|
||||
"coverage": {
|
||||
"fully_resolved": 75,
|
||||
"partially_resolved": 30,
|
||||
"unresolved": 11
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Run Tests (Optional)
|
||||
|
||||
```bash
|
||||
cd /home/lars/docker/bodytrack-dev
|
||||
docker compose exec backend pytest /app/tests/test_placeholder_metadata.py -v
|
||||
```
|
||||
|
||||
### 5. Commit Generated Files
|
||||
|
||||
After catalog generation, commit the generated files:
|
||||
|
||||
```bash
|
||||
# On development machine
|
||||
cd c:/Dev/mitai-jinkendo
|
||||
|
||||
# Pull generated files from server (if generated on server)
|
||||
# Or generate locally if you have DB access
|
||||
|
||||
git add docs/PLACEHOLDER_CATALOG_EXTENDED.*
|
||||
git add docs/PLACEHOLDER_GAP_REPORT.md
|
||||
git add docs/PLACEHOLDER_EXPORT_SPEC.md
|
||||
|
||||
git commit -m "docs: Add generated placeholder catalog files
|
||||
|
||||
Generated via generate_placeholder_catalog.py
|
||||
|
||||
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"
|
||||
|
||||
git push origin develop
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
After deployment, verify:
|
||||
|
||||
- [ ] Backend container is running on dev.mitai.jinkendo.de
|
||||
- [ ] Extended export endpoint responds: `/api/prompts/placeholders/export-values-extended`
|
||||
- [ ] Catalog files generated successfully
|
||||
- [ ] Tests pass (if run)
|
||||
- [ ] No errors in container logs
|
||||
- [ ] Generated files committed to git
|
||||
|
||||
---
|
||||
|
||||
## Rollback (If Needed)
|
||||
|
||||
If issues occur:
|
||||
|
||||
```bash
|
||||
# On Raspberry Pi
|
||||
cd /home/lars/docker/bodytrack-dev
|
||||
|
||||
# Rollback to previous commit
|
||||
git checkout c21a624
|
||||
|
||||
# Rebuild and restart
|
||||
docker compose build --no-cache backend
|
||||
docker compose up -d backend
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Production Deployment (Later)
|
||||
|
||||
When ready for production:
|
||||
|
||||
1. **Merge develop → main:**
|
||||
```bash
|
||||
git checkout main
|
||||
git merge develop
|
||||
git push origin main
|
||||
```
|
||||
|
||||
2. **Auto-deploy triggers for production:**
|
||||
- URL: https://mitai.jinkendo.de
|
||||
- Container: bodytrack (Port 3002/8002)
|
||||
|
||||
3. **Repeat catalog generation on production container**
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: Auto-deploy not triggered
|
||||
|
||||
**Check:**
|
||||
```bash
|
||||
# On Raspberry Pi
|
||||
systemctl status gitea-runner
|
||||
journalctl -u gitea-runner -f
|
||||
```
|
||||
|
||||
**Manual deploy:**
|
||||
```bash
|
||||
cd /home/lars/docker/bodytrack-dev
|
||||
git pull
|
||||
docker compose build --no-cache backend
|
||||
docker compose up -d backend
|
||||
```
|
||||
|
||||
### Issue: Catalog generation fails
|
||||
|
||||
**Check database connection:**
|
||||
```bash
|
||||
docker compose exec backend python -c "from db import get_db; conn = get_db(); print('DB OK')"
|
||||
```
|
||||
|
||||
**Check placeholder_resolver import:**
|
||||
```bash
|
||||
docker compose exec backend python -c "from placeholder_resolver import PLACEHOLDER_MAP; print(len(PLACEHOLDER_MAP))"
|
||||
```
|
||||
|
||||
### Issue: Extended export returns 500
|
||||
|
||||
**Check logs:**
|
||||
```bash
|
||||
docker compose logs backend --tail=50
|
||||
```
|
||||
|
||||
**Common issues:**
|
||||
- Missing database connection
|
||||
- Import errors in new modules
|
||||
- Placeholder resolver errors
|
||||
|
||||
---
|
||||
|
||||
## Monitoring
|
||||
|
||||
Monitor the deployment:
|
||||
|
||||
```bash
|
||||
# Watch logs
|
||||
docker compose logs -f backend
|
||||
|
||||
# Check API health
|
||||
curl https://dev.mitai.jinkendo.de/api/version
|
||||
|
||||
# Check extended export
|
||||
curl -H "X-Auth-Token: $TOKEN" \
|
||||
https://dev.mitai.jinkendo.de/api/prompts/placeholders/export-values-extended \
|
||||
| jq '.metadata.summary'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps After Deployment
|
||||
|
||||
1. Review gap report for unresolved fields
|
||||
2. Test placeholder usage in prompts
|
||||
3. Update prompts to use new placeholders (if any)
|
||||
4. Plan production deployment timeline
|
||||
5. Update CLAUDE.md with new endpoints
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
- **Gitea:** http://192.168.2.144:3000/Lars/mitai-jinkendo
|
||||
- **Dev Environment:** https://dev.mitai.jinkendo.de
|
||||
- **Commit:** a04e7cc
|
||||
- **Implementation Docs:** docs/PLACEHOLDER_METADATA_IMPLEMENTATION_SUMMARY.md
|
||||
- **Governance:** docs/PLACEHOLDER_GOVERNANCE.md
|
||||
Loading…
Reference in New Issue
Block a user