bd48814021
Clean up and organize the flask-shopdb repository for better maintainability and discoverability: ## Changes - Update .gitignore for build artifacts (publish/, data/, 122M total) - Reorganize .claude/ into 6 subdirectories with README navigation - Consolidate overlapping MCP setup guides into MCP-QUICK-START.md - Move deployment docs from root to docs/deployment/ - Archive dated status reports to .claude/archived/ - Delete temporary files (logs, backups, empty reports, ~50K) ## New Structure .claude/ organized into: - setup/ - MCP, VM, Hyper-V, GitHub setup guides + scripts (17 files) - plans/ - Feature plans and protocols (5 files) - maintenance/ - Deployment checklists and reports (4 files) - archived/ - Historical documentation (9 files) - skills/ - Claude Code automation (5 files) - workflows/ - Security audit workflow (1 file) docs/deployment/ created with 6 deployment guides: - LOCAL-DEV-SETUP.md, DOCKER-SETUP.md, DOCKER-PREBUILT-APPROACH.md - PRODUCTION-READINESS.md, DEPLOY-TO-VM.md, README.md Root directory cleaned to essential docs only: - CLAUDE.md, README.md, CONTRIBUTING.md, CHANGELOG.md Benefits: - Clear navigation via README.md in each subdirectory - No duplicate/overlapping documentation - Large artifacts properly gitignored (won't bloat repository) - Historical context preserved in archived/ See .claude/CLEANUP-SUMMARY.md for complete details. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
97 lines
2.6 KiB
Markdown
97 lines
2.6 KiB
Markdown
# Docker Pre-Built Frontend Approach
|
|
|
|
**Problem:** Zscaler corporate proxy causes npm to fail inside Docker builds with "Exit handler never called" error.
|
|
|
|
**Solution:** Build frontend on host (where npm works), copy pre-built dist/ into Docker image.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# 1. Build frontend on host
|
|
cd frontend
|
|
npm ci
|
|
npm run build
|
|
|
|
# 2. Build Docker image (uses pre-built dist/)
|
|
cd ..
|
|
docker compose -f docker-compose.prebuilt.yml build
|
|
|
|
# 3. Start services
|
|
docker compose -f docker-compose.prebuilt.yml up -d
|
|
|
|
# 4. Initialize (first time only)
|
|
docker compose -f docker-compose.prebuilt.yml exec api flask db upgrade
|
|
docker compose -f docker-compose.prebuilt.yml exec api bash /app/scripts/bootstrap-plugins.sh
|
|
|
|
# 5. Access
|
|
https://localhost:5001
|
|
```
|
|
|
|
## Files
|
|
|
|
- `Dockerfile.prebuilt` - Simplified Dockerfile without npm build
|
|
- `docker-compose.prebuilt.yml` - Uses Dockerfile.prebuilt
|
|
- `.dockerignore.prebuilt` - Allows frontend/dist to be copied
|
|
|
|
## Why This Works
|
|
|
|
**Normal Dockerfile:**
|
|
- Multi-stage build
|
|
- Stage 1: Node 20 runs `npm ci` and `npm run build`
|
|
- Stage 2: Copies built frontend from stage 1
|
|
- **PROBLEM:** npm fails inside Docker with Zscaler proxy
|
|
|
|
**Pre-Built Approach:**
|
|
- Build frontend on Windows host (npm works here)
|
|
- Single-stage Dockerfile copies pre-built `frontend/dist/`
|
|
- Only installs Python dependencies
|
|
- **FASTER:** 2-3 minutes vs 15+ minutes
|
|
|
|
## Trade-offs
|
|
|
|
**Pros:**
|
|
- Avoids corporate proxy issues
|
|
- Much faster builds (no npm in container)
|
|
- Frontend build errors visible immediately
|
|
- Can iterate on frontend without rebuilding container
|
|
|
|
**Cons:**
|
|
- Requires npm on host machine
|
|
- Two-step build process
|
|
- frontend/dist must be in version control OR built before deployment
|
|
|
|
## For Production (CI/CD)
|
|
|
|
```yaml
|
|
# GitHub Actions / Jenkins example
|
|
- name: Build frontend
|
|
run: |
|
|
cd frontend
|
|
npm ci
|
|
npm run build
|
|
|
|
- name: Build Docker image
|
|
run: |
|
|
docker build -f Dockerfile.prebuilt -t shopdb:${{ github.sha }} .
|
|
|
|
- name: Push to registry
|
|
run: |
|
|
docker push shopdb:${{ github.sha }}
|
|
```
|
|
|
|
## Comparison
|
|
|
|
| Approach | Build Time | Corporate Proxy | Complexity | Production Ready |
|
|
|----------|-----------|----------------|------------|------------------|
|
|
| Multi-stage Dockerfile | 15+ min | [FAIL] Fails | High | [FAIL] No |
|
|
| Pre-built frontend | 2-3 min | [OK] Works | Medium | [WARN] Yes (with CI/CD) |
|
|
| Pre-built images from registry | 30 sec | [OK] Works | Low | [OK] Yes |
|
|
|
|
## Next Steps
|
|
|
|
For true production deployment:
|
|
1. Set up CI/CD to build frontend + Docker image
|
|
2. Push to container registry
|
|
3. Sites pull pre-built images
|
|
4. No build step at deployment site
|