# Seal Deployment - Known Issues and Solutions

## Common Issues and Fixes

### Issue 1: No Conversion Tool Available

**Symptoms:**
- Warning: "No conversion tool available"
- PNG files not generated
- Conversion failures

**Solution:**
Install one of the following:
```bash
# ImageMagick (recommended)
sudo apt-get install imagemagick  # Linux
brew install imagemagick          # macOS

# Inkscape
sudo apt-get install inkscape     # Linux
brew install inkscape             # macOS

# Node.js with sharp
pnpm add sharp
```

**Impact:** ⚠️ Warning - Deployment can continue but PNG files won't be generated

---

### Issue 2: SVG Files Missing

**Symptoms:**
- Error: "SVG directory missing" or "SVG file not found"
- Deployment fails

**Solution:**
Ensure all 4 SVG files exist:
```bash
assets/credential-images/svg/digital-bank-seal.svg
assets/credential-images/svg/iccc-seal.svg
assets/credential-images/svg/iccc-provost-marshals-seal.svg
assets/credential-images/svg/diplomatic-security-seal.svg
```

**Impact:** ✗ Error - Deployment cannot proceed

---

### Issue 3: Script Not Executable

**Symptoms:**
- Error: "Permission denied"
- Scripts fail to run

**Solution:**
```bash
chmod +x scripts/deploy/*.sh
chmod +x scripts/validation/*.sh
```

**Impact:** ✗ Error - Scripts cannot execute

---

### Issue 4: Invalid SVG Structure

**Symptoms:**
- Warning: "Invalid SVG structure"
- SVG validation fails

**Solution:**
- Ensure SVG files have proper XML structure
- Check for `<svg>` tag and `viewBox` attribute
- Validate with: `xmllint --noout file.svg`

**Impact:** ⚠️ Warning - May cause conversion issues

---

### Issue 5: Missing Maltese Cross Reference

**Symptoms:**
- Warning: "Maltese Cross reference not found"
- Validation warning

**Solution:**
- Ensure SVG files contain Maltese Cross
- Check for class names: `maltese-cross`, `Maltese Cross`
- Verify cross is present in design

**Impact:** ⚠️ Warning - Design validation only

---

### Issue 6: PNG Files Too Large

**Symptoms:**
- Warning: "Large size (XKB, recommend <100KB)"
- Files exceed recommended size

**Solution:**
- Optimize PNG files:
  ```bash
  # Using ImageMagick
  convert input.png -quality 85 -strip output.png
  
  # Using pngquant
  pngquant --quality=65-80 input.png
  ```

**Impact:** ⚠️ Warning - May affect loading performance

---

### Issue 7: Invalid PNG Files

**Symptoms:**
- Error: "Invalid PNG"
- PNG validation fails

**Solution:**
- Re-run conversion with valid SVG source
- Check conversion tool is working
- Verify file wasn't corrupted during conversion

**Impact:** ✗ Error - Files cannot be used

---

### Issue 8: Manifest Template Issues

**Symptoms:**
- Warning: "Missing seal URL reference"
- Error: "Invalid JSON"

**Solution:**
- Update manifest templates:
  ```bash
  ./scripts/deploy/update-manifest-seal-urls.sh
  ```
- Validate JSON:
  ```bash
  jq . manifests/entra/*-manifest-template.json
  ```

**Impact:** ⚠️ Warning - URLs need to be updated

---

### Issue 9: Missing Generated Reports

**Symptoms:**
- Warning: "Report not generated"
- Missing MANIFEST.txt or VALIDATION_REPORT.txt

**Solution:**
- Re-run deployment script
- Check write permissions on PNG directory
- Verify script completed successfully

**Impact:** ⚠️ Warning - Documentation missing

---

## Pre-Deployment Checklist

Before running deployment, verify:

- [ ] All 4 SVG files exist
- [ ] Scripts are executable
- [ ] Conversion tool installed (ImageMagick, Inkscape, or sharp)
- [ ] Directories exist (svg/, png/)
- [ ] Manifest templates are valid JSON
- [ ] Script syntax is valid

## During Deployment Monitoring

Watch for:

- [ ] Conversion tool detection
- [ ] SVG file processing
- [ ] PNG file generation
- [ ] Validation results
- [ ] Report generation

## Post-Deployment Validation

After deployment, check:

- [ ] PNG files generated (if converter available)
- [ ] PNG files are valid
- [ ] File sizes are reasonable (<100KB)
- [ ] Reports are generated
- [ ] Manifest templates updated
- [ ] No critical errors

## Running Comprehensive Check

Use the comprehensive issue checker:

```bash
./scripts/validation/check-seal-deployment-issues.sh
```

This checks:
- Pre-deployment state
- During deployment issues
- Post-deployment validation
- All common problems

## Error Severity

- **✗ Error**: Critical issue, deployment cannot proceed
- **⚠️ Warning**: Non-critical, deployment can continue but may have issues

## Getting Help

If issues persist:

1. Run comprehensive check: `./scripts/validation/check-seal-deployment-issues.sh`
2. Review deployment log: `/tmp/seal-deployment-check.log`
3. Check validation report: `assets/credential-images/png/VALIDATION_REPORT.txt`
4. Review this document for specific issue solutions

---

**Last Updated**: [Current Date]