znakovni.hr/GIF_REGENERATION_GUIDE.md

🎨 GIF Preview Regeneration Guide

Overview

This guide explains how to regenerate GIF preview images for all videos in the Znakovni.hr database. This is necessary after deploying to production because video files have different UUIDs than in development.

Problem

When you see 404 errors for GIF files like:

https://znakovni.matijaturk.from.hr/uploads/gifs/7-adresa-c9ce5c69-1768753308093.gif
Failed to load resource: the server responded with a status of 404

This means the GIF files don't exist on the production server because they were generated locally with different video UUIDs.

Solutions

Option 1: Web UI (Recommended) 🌐

Easiest method - no terminal access needed!

1. Deploy the latest Docker image:

   docker pull git.matijaturk.from.hr/johnny2211/znakovni.hr:latest
   docker-compose down
   docker-compose up -d
   

2. Open the regeneration tool in your browser:

   https://znakovni.matijaturk.from.hr/regenerate-gifs.html
   

3. Login as admin (if not already logged in)

4. Click the "🔄 Start GIF Regeneration" button

5. Wait for completion (may take several minutes depending on number of videos)

6. View results - The page will show:

   • Total videos processed
   • Number of successful GIF generations
   • Number of failures (if any)
   • Error messages for failed videos

7. Refresh the dictionary page to see the new GIF previews!

Option 2: Docker Environment Variable 🐳

Automatic regeneration on container startup:

1. Add to your docker-compose.yml or .env file:

   environment:
     - REGENERATE_GIFS=true
   

2. Restart the container:

   docker-compose down
   docker-compose up -d
   

3. Check logs to monitor progress:

   docker-compose logs -f
   

4. Remove the environment variable after first run to avoid regenerating on every restart

Option 3: API Endpoint 🔧

Direct API call (requires authentication):

curl -X POST https://znakovni.matijaturk.from.hr/api/terms/regenerate-all-gifs \
  -H "Cookie: your-session-cookie" \
  -H "Content-Type: application/json"

Response:

{
  "total": 6,
  "success": 6,
  "failed": 0,
  "errors": []
}

What Gets Created

For each video in the database, the system will:

1. ✅ Extract frames from the video file
2. ✅ Generate a GIF preview with these settings:
   • Width: 300px (height auto-scaled)
   • FPS: 10 frames per second
   • Duration: 3 seconds
   • Quality: High (palette-based encoding)
3. ✅ Save GIF to /uploads/gifs/ directory
4. ✅ Create database record with kind: 'GIF'
5. ✅ Delete old GIF files if they exist

Expected Results

On Dictionary Page:

• ✅ Words with videos → Animated GIF preview
• ✅ Words without videos → 📝 Emoji icon
• ✅ Words with videos but no GIF → "Nema pregleda" icon

In Admin Panel:

• ✅ Video and GIF displayed side-by-side
• ✅ "Regenerate GIF" button (🔄) for individual regeneration
• ✅ Green checkmark "✓ GIF preview dostupan"

Troubleshooting

GIFs still not showing after regeneration

1. Check browser console (F12) for 404 errors
2. Verify GIF files exist on server:

   ls -lh /path/to/uploads/gifs/
   

3. Check database records:

   docker exec -it znakovni-app sh
   cd packages/backend
   npx tsx scripts/check-gifs.ts
   

Regeneration fails for some videos

• Check that video files exist in /uploads/videos/
• Verify ffmpeg is installed in the container
• Check container logs for specific error messages
• Ensure sufficient disk space for GIF files

Permission errors

• Ensure /uploads/gifs/ directory is writable
• Check file ownership and permissions

GIFs return 404 but files exist on server

This was a nginx configuration issue (fixed in commit bc688e5):

Problem: nginx regex for static assets was catching ALL .gif files, including those in /uploads/gifs/, and trying to serve them from frontend dist/ directory instead of proxying to backend.

Solution: Updated nginx.conf to exclude /uploads/ path from static asset caching:

# Before (broken):
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

# After (fixed):
location ~* ^/(?!uploads/).*\.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

The negative lookahead (?!uploads/) ensures files under /uploads/ are proxied to backend, not served as static assets.

Technical Details

• GIF Generator: Uses ffmpeg with two-pass palette optimization
• File naming: GIFs use same filename as video but with .gif extension
• Database: GIF records stored in term_media table with kind='GIF'
• Cleanup: Old GIF files and database records are deleted before regeneration

Maintenance

Regenerate single GIF (Admin UI)

1. Go to Admin → Terms
2. Click video icon (🎥) for the term
3. Click "Regenerate GIF" button (🔄)
4. Wait for completion

Regenerate all GIFs (after bulk video upload)

Use Option 1 (Web UI) or Option 2 (Docker env var) from above.

---

Last updated: 2026-01-18 Docker image: git.matijaturk.from.hr/johnny2211/znakovni.hr:latest Digest: sha256:9d17eac2038678e8b65d54eb8a5f1b99974810f829ff414288deb849876db620 Latest commit: bc688e5 - Fix nginx configuration for GIF serving