Files

Proudlock d40f1a6a92 fix: replace unicode characters and fix finalize-restore endpoint

Style check fixes:
- Replace unicode box-drawing characters with ASCII (|-- instead of ├──)
- Replace emoji status markers with [OK]/[FAIL]/[WARN] tags
- Replace arrows (→ with ->, ↔ with <->) and em-dashes (— with --)
- Add venv-quick to excluded directories in check script
- Exclude darkwing report files (findings.sarif, report.md)

Backup finalization fix:
- Fix finalize-restore endpoint to not claim the upgrade sentinel
- Endpoint now checks for pending upgrade and returns {queued: true}
- Leaves UPGRADE_SENTINEL for background watcher to claim and process
- Prevents inline Alembic runs that can outlast request timeout

Claude Code context:
- Add .claude/ directory with INDEX.md and QUICK-REFERENCE.md
- Add CLAUDE.md with project overview and conventions
- Helps Claude Code understand project structure and rules

Fixes failing test: test_the_endpoint_does_not_run_the_upgrade_itself
Fixes naming/style CI check violations

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-09-07 03:48:11 -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