mitai-jinkendo/docs/PLACEHOLDER_METADATA_DEPLOYMENT_GUIDE.md

# 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": 114,
  "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