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:

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