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

4.5 KiB

Raw Blame History

Deploy ShopDB to Hyper-V VM

Quick guide to deploy the Docker stack to a Windows 11 Hyper-V VM.

Prerequisites on VM

Docker Desktop installed and running
Git Bash or WSL installed (for bash commands)
PowerShell (already on Windows 11)

Step 1: Copy Files to VM

Method A: Shared Folder

# On host PC, share the repo
# Then on VM, copy from network share
Copy-Item -Recurse \\host-pc\shopdb-flask C:\shopdb

Method B: Git Clone

# On VM
cd C:\
git clone git@github.com:ge-aero/shopdb-flask.git
cd shopdb-flask
git checkout wj

Method C: Export/Import

# On host PC
Compress-Archive -Path C:\Users\270015376\Documents\github\flask-shopdb -DestinationPath C:\shopdb-deploy.zip

# Copy shopdb-deploy.zip to VM, then on VM:
Expand-Archive -Path C:\shopdb-deploy.zip -DestinationPath C:\shopdb

Step 2: Run Deployment Script

# On VM, open PowerShell as Administrator
cd C:\shopdb

# Option 1: Quick deploy with defaults
.\deploy-to-vm.ps1

# Option 2: Specify site name and password
.\deploy-to-vm.ps1 -SiteName "west-jefferson" -AdminPassword "YourSecurePassword123!"

# Option 3: See all options
.\deploy-to-vm.ps1 -Help

What the Script Does

[OK] Checks Docker Desktop is running
[OK] Creates .env from template
[OK] Builds frontend (if needed)
[OK] Builds Docker images (2-3 minutes, offline packages)
[OK] Starts all services (db + api + backup)
[OK] Runs database migrations
[OK] Sets admin password

Manual Deployment (Alternative)

If you prefer to run commands manually:

# 1. Create environment
cp .env.docker-dev .env

# 2. Build frontend (if not already built)
cd frontend
npm ci
npm run build
cd ..

# 3. Build and start Docker stack
docker compose -f docker-compose.prebuilt.yml -f docker-compose.backup.yml --profile backup build
docker compose -f docker-compose.prebuilt.yml -f docker-compose.backup.yml --profile backup up -d

# 4. Initialize database
docker exec flask-shopdb-api-1 flask db upgrade

# 5. Reset admin password (optional)
docker exec flask-shopdb-db-1 mysql -uroot -proot-dev-password-not-for-production shopdb_flask -e \
  "UPDATE users SET passwordhash='scrypt:32768:8:1\$B4LhpPrM6qxijInK\$b99b47a0bb5fd45761a1823f401f70a3ceccf71a5d38dc433378aa07426ef8eaf7e679ff3dd7b0ce9772600f83368ac642e9419b9beaa49f87483318bae34547', failedlogins=0, lockeduntil=NULL WHERE username='admin';"
# (Password is: admin)

Access

URL: https://localhost:5001 (or https://vm-ip-address:5001 from host)

Login:

Username: admin
Password: Whatever you set in deploy script (default: ChangeMe123!)

Verify Deployment

# Check all services are running
docker ps

# Should see:
# - flask-shopdb-db-1
# - flask-shopdb-api-1
# - flask-shopdb-backup-store-1
# - flask-shopdb-backup-watcher-1

# View logs
docker logs -f flask-shopdb-api-1

# Test backup
# Go to https://localhost:5001/settings/shopdbbackups
# Click "Back Up Now"
# Wait 30 seconds, should show as "Checked"

Troubleshooting

Docker not running:

# Start Docker Desktop manually
& "C:\Program Files\Docker\Docker\Docker Desktop.exe"
Start-Sleep -Seconds 30

Port 5001 already in use:

# Edit .env and change API_PORT
# API_PORT=5002

Can't access from host PC:

# On VM, check Windows Firewall
New-NetFirewallRule -DisplayName "ShopDB" -Direction Inbound -LocalPort 5001 -Protocol TCP -Action Allow

SSL certificate warnings:

Normal for self-signed certs
Click "Advanced" -> "Proceed to localhost (unsafe)"

Stop/Start

# Stop
docker compose -f docker-compose.prebuilt.yml -f docker-compose.backup.yml down

# Start (after first deployment)
docker compose -f docker-compose.prebuilt.yml -f docker-compose.backup.yml --profile backup up -d

Update After Code Changes

# 1. Pull latest code
git pull origin wj

# 2. Rebuild frontend (if changed)
cd frontend && npm run build && cd ..

# 3. Rebuild and restart
docker compose -f docker-compose.prebuilt.yml -f docker-compose.backup.yml build
docker compose -f docker-compose.prebuilt.yml -f docker-compose.backup.yml up -d

Offline Deployment Notes

This deployment works completely offline because:

[OK] Frontend pre-built and checked into repo
[OK] Restic binary pre-downloaded (8.6MB in repo)
[OK] No npm/pip downloads during Docker build
[OK] All dependencies baked into images

Perfect for air-gapped or restricted network environments!

4.5 KiB Raw Blame History