shopdb-flask/docs/deployment/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**
```powershell
# 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**
```bash
# On VM
cd C:\
git clone git@github.com:ge-aero/shopdb-flask.git
cd shopdb-flask
git checkout wj
```

**Method C: Export/Import**
```powershell
# 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

```powershell
# 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. [OK] Checks Docker Desktop is running
2. [OK] Creates .env from template
3. [OK] Builds frontend (if needed)
4. [OK] Builds Docker images (2-3 minutes, offline packages)
5. [OK] Starts all services (db + api + backup)
6. [OK] Runs database migrations
7. [OK] Sets admin password

## Manual Deployment (Alternative)

If you prefer to run commands manually:

```bash
# 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

```powershell
# 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:**
```powershell
# Start Docker Desktop manually
& "C:\Program Files\Docker\Docker\Docker Desktop.exe"
Start-Sleep -Seconds 30
```

**Port 5001 already in use:**
```powershell
# Edit .env and change API_PORT
# API_PORT=5002
```

**Can't access from host PC:**
```powershell
# 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

```bash
# 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

```bash
# 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!