the_order/docs/deployment/SEAL_DEPLOYMENT_ISSUES.md

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:

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

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:

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:

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

  ./scripts/deploy/update-manifest-seal-urls.sh
  

• Validate JSON:

  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:

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