pre migrate

MIGRATION.md

@@ -0,0 +1,221 @@
+# Migration Guide: Dev Mac → Production Mac
+
+## Overview
+
+Migrate the entire Studio EinsZwoVier web application from development Mac (`einszwovier.local`) to production Mac (`admin@124.local`) using SCP carbon copy method.
+
+## Prerequisites
+
+- SSH access to production Mac: Configure SSH shortcut for easy access
+- Both Macs on same network
+- Docker Desktop installed on production Mac (124.local)
+- Git configured on production Mac
+
+### Configure SSH Access (Recommended)
+
+Add to `~/.ssh/config` on dev Mac:
+
+```ssh-config
+Host 124
+  HostName 124.local
+  User admin
+  ForwardAgent yes
+```
+
+Then test: `ssh 124 "echo 'Connection works!'"`
+
+## Migration Steps
+
+### 1. Push Latest Changes (on dev Mac)
+
+```bash
+cd /Users/aron124/webapp_124
+git push forgejo main
+git push origin main  # optional: backup to GitHub
+```
+
+### 2. Stop All Services (on dev Mac)
+
+```bash
+cd /Users/aron124/webapp_124
+docker compose down
+```
+
+**Verify all stopped:**
+
+```bash
+docker compose ps  # should show nothing running
+```
+
+### 3. Copy Everything to Production Mac
+
+**On production Mac (124.local), run:**
+
+```bash
+# Create parent directory if needed
+mkdir -p /Users/admin
+
+# SCP entire project (this will take a while - includes all Docker volumes)
+scp -r aron124@einszwovier.local:/Users/aron124/webapp_124 /Users/admin/
+
+# Estimated transfer time: 5-30 minutes depending on:
+# - Ollama models size (~several GB)
+# - Matrix message history
+# - BookStack content
+# - LLM cache
+```
+
+**What gets copied:**
+
+- ✅ All source code and git history
+- ✅ `.env` file with credentials
+- ✅ Matrix database & message history (`matrix/data/`)
+- ✅ Ollama LLM models (`ollama/`)
+- ✅ Open WebUI data (`open-webui/`)
+- ✅ BookStack content & database (`bookstack/`)
+- ✅ Docmost database (`docmost/`)
+- ✅ User uploads (`data/uploads/`)
+- ✅ Docker Compose configuration
+
+### 4. Fix File Permissions (on production Mac)
+
+```bash
+cd /Users/admin/webapp_124
+
+# Ensure you own all files
+sudo chown -R $(whoami):staff .
+
+# Fix Docker volume permissions if needed
+chmod -R 755 matrix/ ollama/ open-webui/ bookstack/ docmost/ data/
+```
+
+### 5. Start Services (on production Mac)
+
+```bash
+cd /Users/admin/webapp_124
+docker compose up -d
+```
+
+### 6. Verify Everything Works
+
+```bash
+# Check all services are running
+docker compose ps
+
+# Check health status (wait ~30 seconds for health checks)
+docker compose ps | grep -i healthy
+
+# Check logs for errors
+docker compose logs --tail=50
+
+# Test web interface
+open http://localhost
+# or http://einszwovier.local (if DNS is set up)
+```
+
+### 7. Restart Dev Mac Services (optional)
+
+If you want to keep dev Mac running alongside:
+
+```bash
+# On dev Mac
+cd /Users/aron124/webapp_124
+docker compose up -d
+```
+
+**Note:** Both will share same Matrix homeserver name - you may need to:
+
+- Change `server_name` in `matrix/data/homeserver.yaml` on one instance
+- Use different external ports in `docker-compose.yml`
+
+## Verification Checklist
+
+- [ ] All 11 services show as "healthy" in `docker compose ps`
+- [ ] Web interface accessible at <http://localhost> or <http://einszwovier.local>
+- [ ] Cost calculator can analyze PDFs
+- [ ] Matrix integration works (submit test order)
+- [ ] BookStack accessible at configured port
+- [ ] Open WebUI (LLM chat) accessible
+- [ ] JupyterHub accessible and courses load
+- [ ] Forgejo instance accessible
+- [ ] Element Web (Matrix client) accessible
+
+## Troubleshooting
+
+### Services won't start
+
+```bash
+# Check logs
+docker compose logs [service-name]
+
+# Common issues:
+# - Port conflicts: Change ports in docker-compose.yml
+# - Permission errors: Run chown command again
+# - Volume corruption: May need to delete and recreate volumes
+```
+
+### Matrix won't connect
+
+```bash
+# Check Matrix logs
+docker compose logs synapse
+
+# Verify environment variables
+cat .env | grep MATRIX
+
+# Test Matrix health endpoint
+curl http://localhost:8008/_matrix/client/versions
+```
+
+### Git issues
+
+```bash
+# Verify remotes still work
+git remote -v
+git fetch forgejo
+
+# If needed, reconfigure
+git remote set-url forgejo https://forgejo.petau.net/aron/124-webapp.git
+```
+
+## Rollback Plan
+
+If migration fails, dev Mac (`einszwovier.local`) still has everything:
+
+1. Stop services on production Mac: `docker compose down`
+2. Restart on dev Mac: `docker compose up -d`
+3. Debug issue before retrying migration
+
+## Post-Migration Cleanup (optional)
+
+After confirming production Mac works for 1-2 weeks:
+
+**On dev Mac:**
+
+```bash
+cd /Users/aron124/webapp_124
+docker compose down -v  # removes volumes too
+cd ..
+rm -rf webapp_124  # or keep as backup
+```
+
+## Network Configuration
+
+Both Macs are on `einszwovier.local` domain. You may want to:
+
+- Update DNS to point `einszwovier.local` → production Mac IP
+- Configure nginx reverse proxy for external access
+- Set up SSL certificates for HTTPS
+- Configure firewall rules
+
+## Data That Won't Transfer (if using git clone method)
+
+If you later need to do a clean migration via git clone instead:
+
+- Matrix message history (excluded in `.gitignore`)
+- Matrix signing keys (will regenerate)
+- Ollama models (need to re-download)
+- BookStack uploads/database (excluded in `.gitignore`)
+- User uploaded PDFs (excluded in `.gitignore`)
+
+**But with SCP method, ALL of this transfers! ✅**