From 6bbbb6523825441e42edf9b3ca9641b819056af4 Mon Sep 17 00:00:00 2001 From: olaf Date: Sun, 16 Nov 2025 10:39:49 +0000 Subject: [PATCH] Initial migration guide structure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Created repository layout (docs, screenshots, backups, docker-configs) - Added comprehensive README with project overview - Created 01-overview.md with migration strategy - Created 02-gitea-migration.md execution template - Defined success criteria and risk mitigation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- README.md | 62 ++++++++++++ docs/01-overview.md | 86 +++++++++++++++++ docs/02-gitea-migration.md | 188 +++++++++++++++++++++++++++++++++++++ 3 files changed, 336 insertions(+) create mode 100644 README.md create mode 100644 docs/01-overview.md create mode 100644 docs/02-gitea-migration.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..e011616 --- /dev/null +++ b/README.md @@ -0,0 +1,62 @@ +# Dockge Migration Guide + +Complete documentation for migrating services from photon.obnh.io to fry.obr.sh using Dockge WebUI. + +## Project Overview + +This repository contains comprehensive migration documentation, scripts, and verification records for moving containerized services between servers. + +**Source Server:** photon.obnh.io +**Target Server:** fry.obr.sh (45.131.64.213) +**Management Tool:** Dockge WebUI +**Migration Date:** 2025-11-16 + +## Services to Migrate + +1. **Gitea** - Git hosting service with PostgreSQL database +2. Additional services (TBD) + +## Repository Structure + +``` +/ +├── docs/ # Migration documentation +│ ├── 01-overview.md # Migration overview and planning +│ ├── 02-gitea-migration.md # Gitea-specific migration steps +│ └── templates/ # Document templates +├── screenshots/ # Verification screenshots +├── docker-configs/ # Exported docker-compose.yml files +├── backups/ # Database dumps and backups +└── scripts/ # Migration automation scripts +``` + +## Migration Workflow + +1. **Pre-Migration** + - Service inventory and dependency mapping + - Backup all data (databases, volumes, configs) + - Screenshot current state in Dockge + +2. **Migration** + - Stop services on source server + - Export docker-compose configurations + - Transfer data to target server + - Deploy on target server + +3. **Post-Migration** + - Verify service functionality via browser + - DNS/routing verification + - Documentation and commit to git + +## Documentation Standards + +- All timestamps in ISO 8601 format +- Screenshots required for all WebUI operations +- Browser verification via Playwright automation +- Git commits after each major step + +## Author + +Orchestrated by: @agent-zen-orchestrator +Executed by: Specialized sub-agents +Date: 2025-11-16 diff --git a/docs/01-overview.md b/docs/01-overview.md new file mode 100644 index 0000000..9f2f01d --- /dev/null +++ b/docs/01-overview.md @@ -0,0 +1,86 @@ +# Migration Overview + +**Document Version:** 1.0 +**Created:** 2025-11-16T10:30:00Z +**Last Updated:** 2025-11-16T10:30:00Z + +## Objective + +Migrate Gitea service from photon.obnh.io to fry.obr.sh with zero data loss and minimal downtime. + +## Infrastructure Details + +### Source Server: photon.obnh.io +- **Role:** Legacy container host +- **Management:** Dockge WebUI +- **Services:** Gitea (gitea + gitea_postgres containers) + +### Target Server: fry.obr.sh +- **IP:** 45.131.64.213 +- **Role:** New container host +- **Management:** Dockge WebUI +- **Status:** Ready for deployment + +## Critical Components + +### Gitea Service +- **Container 1:** gitea (application) +- **Container 2:** gitea_postgres (database) +- **Database:** PostgreSQL with critical repository data +- **Volumes:** Git repository data, configs, database files + +## Migration Strategy + +1. **Backup-First Approach** + - Full PostgreSQL dump before any changes + - Volume snapshots where applicable + - Verify backup integrity + +2. **Graceful Shutdown** + - Stop application container first + - Stop database container second + - Verify all processes stopped + +3. **Data Transfer** + - Secure transfer of database dumps + - Transfer docker-compose configuration + - Preserve volume data + +4. **Staged Deployment** + - Deploy database container first + - Restore database from dump + - Deploy application container + - Verify connectivity + +5. **Verification** + - Browser-based functional testing + - DNS resolution verification + - Repository access testing + +## Risk Mitigation + +- **Database Corruption:** Full pg_dump before migration +- **Network Issues:** Local backups retained on source +- **Configuration Drift:** Exact docker-compose.yml export +- **Service Downtime:** Documented rollback procedure + +## Success Criteria + +- [ ] Gitea accessible via browser on fry.obr.sh +- [ ] All repositories intact and browsable +- [ ] User authentication functional +- [ ] Database queries responding correctly +- [ ] DNS routing verified (if applicable) +- [ ] All documentation committed to git + +## Timeline + +- **Preparation:** 30 minutes +- **Backup:** 15 minutes +- **Migration:** 45 minutes +- **Verification:** 30 minutes +- **Total:** ~2 hours + +## Next Steps + +Proceed to [02-gitea-migration.md](./02-gitea-migration.md) for detailed execution steps. diff --git a/docs/02-gitea-migration.md b/docs/02-gitea-migration.md new file mode 100644 index 0000000..2d5bdf6 --- /dev/null +++ b/docs/02-gitea-migration.md @@ -0,0 +1,188 @@ +# Gitea Migration - Detailed Execution Log + +**Service:** Gitea (Git hosting) +**Started:** 2025-11-16T10:30:00Z +**Status:** In Progress + +## Pre-Migration Checklist + +- [ ] Dockge WebUI accessible on photon.obnh.io +- [ ] Both containers (gitea + gitea_postgres) visible +- [ ] Screenshots captured +- [ ] Database backup created +- [ ] Backup verified and transferred + +## Step 1: Pre-Migration Backup + +### Actions Required +1. Access photon.obnh.io Dockge WebUI +2. Identify gitea_postgres container +3. Execute pg_dump command +4. Save backup to `/home/olaf/dockge-migration-guide/backups/` +5. Verify backup file integrity + +### Commands +```bash +# Database dump (to be executed on photon) +docker exec gitea_postgres pg_dump -U gitea gitea > gitea_db_backup_$(date +%Y%m%d_%H%M%S).sql + +# Verify backup +ls -lh gitea_db_backup_*.sql +``` + +### Evidence +- Screenshot: `screenshots/01-photon-dockge-containers.png` +- Backup file: `backups/gitea_db_backup_TIMESTAMP.sql` + +--- + +## Step 2: Screenshot Documentation + +### Dockge Container View +- [ ] Screenshot showing both gitea containers +- [ ] Container status visible (running/stopped) +- [ ] File: `screenshots/01-photon-dockge-containers.png` + +--- + +## Step 3: Stop Gitea Service + +### Procedure +1. Navigate to Dockge WebUI on photon +2. Stop gitea container (application first) +3. Screenshot the stop action +4. Stop gitea_postgres container (database second) +5. Screenshot the stop action +6. Verify both containers stopped + +### Evidence +- Screenshot: `screenshots/02-stop-gitea-container.png` +- Screenshot: `screenshots/03-stop-postgres-container.png` +- Screenshot: `screenshots/04-both-containers-stopped.png` + +--- + +## Step 4: Export Docker Compose Configuration + +### Actions +1. Open Dockge WebUI on photon +2. Navigate to Gitea stack +3. Copy entire docker-compose.yml content +4. Save to `docker-configs/gitea-compose-photon.yml` +5. Screenshot the configuration view + +### Evidence +- Config file: `docker-configs/gitea-compose-photon.yml` +- Screenshot: `screenshots/05-docker-compose-export.png` + +--- + +## Step 5: Database Transfer + +### Actions +1. Transfer database dump to fry.obr.sh +2. Verify file integrity (checksum) +3. Prepare for restore + +### Commands +```bash +# Transfer to fry +scp gitea_db_backup_*.sql root@fry.obr.sh:/tmp/ + +# Verify on fry +ssh root@fry.obr.sh "md5sum /tmp/gitea_db_backup_*.sql" +``` + +--- + +## Step 6: Deploy on Fry + +### Procedure +1. Access Dockge WebUI on fry.obr.sh +2. Create new stack named "gitea" +3. Paste docker-compose.yml content +4. Start postgres container first +5. Restore database +6. Start gitea container +7. Screenshot each step + +### Database Restore +```bash +# Restore database (execute on fry) +docker exec -i gitea_postgres psql -U gitea gitea < /tmp/gitea_db_backup_*.sql +``` + +### Evidence +- Screenshot: `screenshots/06-fry-dockge-new-stack.png` +- Screenshot: `screenshots/07-fry-compose-paste.png` +- Screenshot: `screenshots/08-fry-postgres-started.png` +- Screenshot: `screenshots/09-fry-gitea-started.png` + +--- + +## Step 7: Browser Verification + +### Playwright Automation +- [ ] Navigate to git.photon.obnh.io (should resolve to fry) +- [ ] Verify login page loads +- [ ] Test repository browsing +- [ ] Screenshot successful access + +### Verification Points +1. DNS resolution (should point to 45.131.64.213) +2. HTTPS certificate valid +3. Login page renders +4. Repository list accessible +5. Git operations functional + +### Evidence +- Screenshot: `screenshots/10-browser-login-page.png` +- Screenshot: `screenshots/11-browser-repo-list.png` + +--- + +## Step 8: Final Verification + +### Checklist +- [ ] Gitea accessible via browser +- [ ] All repositories visible +- [ ] User authentication working +- [ ] Git clone/push operations tested +- [ ] DNS routing verified + +--- + +## Post-Migration + +### Actions +- [ ] Commit all screenshots to git +- [ ] Update this document with timestamps +- [ ] Tag git commit: `gitea-migration-complete` +- [ ] Archive backups + +### Rollback Procedure (if needed) +1. Stop containers on fry +2. Restart containers on photon +3. Verify service restoration +4. Document incident + +--- + +## Timeline + +| Step | Started | Completed | Duration | Status | +|------|---------|-----------|----------|--------| +| Pre-Migration Backup | | | | Pending | +| Screenshot Documentation | | | | Pending | +| Stop Gitea Service | | | | Pending | +| Export Configuration | | | | Pending | +| Database Transfer | | | | Pending | +| Deploy on Fry | | | | Pending | +| Browser Verification | | | | Pending | +| Git Commit | | | | Pending | + +--- + +## Notes + +*This document will be updated in real-time as the migration progresses.*