shopdb-flask/DEPLOY-TO-VM.md

Deploy ShopDB to Hyper-V VM

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

Prerequisites on VM

1. Docker Desktop installed and running
2. Git Bash or WSL installed (for bash commands)
3. 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

1. ✅ Checks Docker Desktop is running
2. ✅ Creates .env from template
3. ✅ Builds frontend (if needed)
4. ✅ Builds Docker images (2-3 minutes, offline packages)
5. ✅ Starts all services (db + api + backup)
6. ✅ Runs database migrations
7. ✅ 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:

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

Perfect for air-gapped or restricted network environments!