olaf/dockge-migration-guide
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial migration guide structure

Browse Source 
- 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 <noreply@anthropic.com>
This commit is contained in:
olaf
2025-11-16 10:39:49 +00:00
commit 6bbbb65238
3 changed files with 336 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
README.md Normal file
View File

@@ -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

86
docs/01-overview.md Normal file
View File

@@ -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.

188
docs/02-gitea-migration.md Normal file
View File

@@ -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.*