Files

Proudlock bd48814021 Reorganize repository structure and clean up documentation

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>

2026-09-11 15:45:05 -04:00

2.6 KiB

Raw Blame History

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

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

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

Set up CI/CD to build frontend + Docker image
Push to container registry
Sites pull pre-built images
No build step at deployment site

2.6 KiB Raw Blame History