124-webapp/MIGRATION.md

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:

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)

cd /Users/aron124/webapp_124
git push forgejo main
git push origin main  # optional: backup to GitHub

2. Stop All Services (on dev Mac)

cd /Users/aron124/webapp_124
docker compose down

Verify all stopped:

docker compose ps  # should show nothing running

3. Copy Everything to Production Mac

On production Mac (124.local), run:

# 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)

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)

cd /Users/admin/webapp_124
docker compose up -d

6. Verify Everything Works

# 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:

# 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

# 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

# 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

# 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:

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! ✅