shopdb-flask/.claude/skills/docker-rebuild.md

name, description

name	description
docker-rebuild	Complete Docker rebuild workflow - build frontend, rebuild image, run migrations, verify health

Docker Rebuild Workflow

Rebuild Docker image after backend changes, dependency updates, or branch merges. Ensures clean state with latest code.

What This Skill Does

Complete Docker rebuild process:

1. Build frontend (prebuilt approach for Zscaler proxy)
2. Rebuild Docker image with latest code
3. Restart containers cleanly
4. Run database migrations
5. Verify services healthy
6. Test both URLs work

When to Use This Skill

Required after:

• Merging wilm branch (Python/dependency changes)
• Updating requirements.txt
• Changing Dockerfile.prebuilt
• System package changes (apt installs)

Optional after:

• Backend code changes (Flask auto-reloads in dev)
• Frontend changes (just npm run build + restart api)

Workflow

1. Check Current State

docker compose ps
git status

Show:

• Which containers are running
• Whether there are uncommitted changes
• Current branch (should be wj or dev)

2. Build Frontend First

Using prebuilt approach (ADR: corporate proxy blocks npm in Docker):

cd frontend
npm run build
cd ..

Verify:

• Build succeeds without errors
• frontend/dist/ directory updated
• Bundle size reasonable (< 20MB)

If build fails:

• Check for syntax errors
• Verify node_modules/ is up to date (npm ci if needed)
• Check for missing dependencies

3. Stop Containers

Clean shutdown:

docker compose -f docker-compose.prebuilt.yml down

What this does:

• Stops all containers gracefully
• Removes containers (not volumes)
• Network cleaned up

4. Rebuild Docker Image

docker compose -f docker-compose.prebuilt.yml build api

Monitor for:

• Build completes without errors
• Python dependencies install successfully
• frontend/dist/ copied into image
• Image size reasonable (< 1GB)

Common build issues:

• Dockerfile.prebuilt syntax error
• Missing files in build context
• Dependency conflicts in requirements.txt

5. Start Containers

docker compose -f docker-compose.prebuilt.yml up -d

Verify startup:

• Both containers start (db-1, api-1)
• Health checks pass
• Logs show no errors

docker compose ps
docker compose logs api --tail 30

Look for:

• "Listening at" from gunicorn (Flask ready)
• No Python exceptions
• Plugins loaded successfully

6. Run Migrations

Apply any new database migrations:

# Core migrations
docker compose exec api flask db upgrade

# Plugin migrations
docker compose exec api flask plugin upgrade-all

Verify:

• Migrations apply cleanly
• No "head not found" errors
• No circular dependency issues

If migrations fail:

• Check logs for specific error
• Verify migration chains are linear (ADR-008)
• May need to manually fix migration conflicts

7. Verify Services Healthy

Database connectivity:

docker compose exec api flask shell -c "from shopdb.api import db; print(db.session.execute('SELECT 1').scalar())"

Flask responding:

curl -k https://localhost:5001/api/health

Expected: {"status": "healthy"}

8. Test Both URLs

Verify both development and production builds work:

Vite dev server (if running):

• http://192.168.100.1:5173
• Should show latest code
• Hot reload working

Flask production build:

• https://192.168.100.1:5001
• Should show updated frontend
• Login page loads
• No console errors

9. Check Plugin Loading

docker compose exec api flask plugin list

Verify:

• Expected plugins loaded
• No import errors
• Enabled plugins show as active

If plugins fail to load:

• Check logs for import errors
• Verify plugin dependencies installed
• Check for circular imports

10. Summary Report

Provide clear status:

[X] Success:

Docker rebuild complete:
[X] Frontend built (3.2MB)
[X] Docker image rebuilt (742MB)
[X] Containers started and healthy
[X] Migrations applied (3 core, 5 plugin)
[X] All plugins loaded (12 active)
[X] URLs accessible

Services ready:
- Flask API: https://localhost:5001
- Vite dev: http://localhost:5173 (if running)

You can now test changes.

WARNING: Issues detected:

Docker rebuild completed with warnings:
[X] Frontend built
[X] Docker image rebuilt
[X] Containers started
[ ] Migration failed: plugin 'endpoints' has circular dependency
WARNING: Plugin 'printers' failed to load (import error)

Action needed:
1. Check endpoints migration: plugins/endpoints/migrations/versions/
2. Check printers import error in logs

Logs: docker compose logs api --tail 50

Troubleshooting

Build takes too long (>5 min):

• Docker cache may be invalid
• Try: docker compose build --no-cache api

Container won't start:

• Check port conflicts (5001 already in use)
• Check Docker disk space: docker system df
• View logs: docker compose logs api

Migrations fail:

• Verify migration chain linearity
• Check PLUGIN_TABLE_OWNERS coordination
• May need to drop test database and rebuild

Frontend not updating:

• Verify npm run build ran successfully
• Check frontend/dist/ has latest files
• May need to clear browser cache

Related

• /pre-commit - Pre-commit validation
• /production-health - Deep health check
• docker-compose.prebuilt.yml - Prebuilt Docker compose file
• docker-prebuilt-approach - Why we use prebuilt frontend
• ADR-008: Plugin migration ownership