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

---
name: docker-rebuild
description: 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

```bash
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):

```bash
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:

```bash
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

```bash
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

```bash
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

```bash
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:

```bash
# 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:**
```bash
docker compose exec api flask shell -c "from shopdb.api import db; print(db.session.execute('SELECT 1').scalar())"
```

**Flask responding:**
```bash
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

```bash
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