Sanitized mirror from private repository - 2026-04-04 11:21:25 UTC

docs/admin/service-deprecation-policy.md

@@ -0,0 +1,177 @@
+# Service Deprecation Policy
+
+*Guidelines for retiring services in the homelab*
+
+---
+
+## Purpose
+
+This policy outlines the process for deprecating and removing services from the homelab infrastructure.
+
+---
+
+## Reasons for Deprecation
+
+### Technical Reasons
+- Security vulnerabilities with no fix
+- Unsupported upstream project
+- Replaced by better alternative
+- Excessive resource consumption
+
+### Operational Reasons
+- Service frequently broken
+- No longer maintained
+- Too complex for needs
+
+### Personal Reasons
+- No longer using service
+- Moved to cloud alternative
+
+---
+
+## Deprecation Stages
+
+### Stage 1: Notice (2 weeks)
+- Mark service as deprecated in documentation
+- Notify active users
+- Stop new deployments
+- Document in CHANGELOG
+
+### Stage 2: Warning (1 month)
+- Display warning in service UI
+- Send notification to users
+- Suggest alternatives
+- Monitor usage
+
+### Stage 3: Archive (1 month)
+- Export data
+- Create backup
+- Move configs to archive/
+- Document removal in CHANGELOG
+
+### Stage 4: Removal
+- Delete containers
+- Remove from GitOps
+- Update documentation
+- Update service inventory
+
+---
+
+## Decision Criteria
+
+### Keep Service If:
+- Active users > 1
+- Replaces paid service
+- Critical infrastructure
+- Regular updates available
+
+### Deprecate Service If:
+- No active users (30+ days)
+- Security issues unfixed
+- Unmaintained (>6 months no updates)
+- Replaced by better option
+
+### Exceptions
+- Critical infrastructure (extend timeline)
+- Security vulnerability (accelerate)
+- User request (evaluate)
+
+---
+
+## Archive Process
+
+### Before Removal
+
+1. **Export Data**
+   ```bash
+   # Database
+   docker exec <db> pg_dump -U user db > backup.sql
+    
+   # Files
+   tar -czf service-data.tar.gz /data/path
+    
+   # Config
+   cp -r compose/ archive/service-name/
+   ```
+
+2. **Document**
+   - Date archived
+   - Reason for removal
+   - Data location
+   - Replacement (if any)
+
+3. **Update Dependencies**
+   - Check for dependent services
+   - Update those configs
+   - Test after changes
+
+### Storage Location
+
+```
+archive/
+├── services/
+│   └── <service-name>/
+│       ├── docker-compose.yml
+│       ├── config/
+│       └── README.md (removal notes)
+└── backups/
+    └── <service-name>/
+        └── (data backups)
+```
+
+---
+
+## Quick Removal Checklist
+
+- [ ] Notify users
+- [ ] Export data
+- [ ] Backup configs
+- [ ] Remove from Portainer
+- [ ] Delete Git repository
+- [ ] Remove from Nginx Proxy Manager
+- [ ] Remove from Authentik (if SSO)
+- [ ] Update documentation
+- [ ] Update service inventory
+- [ ] Document in CHANGELOG
+
+---
+
+## Emergency Removal
+
+For critical security issues:
+
+1. **Immediate** - Stop service
+2. **Within 24h** - Export data
+3. **Within 48h** - Remove from Git
+4. **Within 1 week** - Full documentation
+
+---
+
+## Restoring Archived Services
+
+If service needs to be restored:
+
+1. Copy from archive/
+2. Review config for outdated settings
+3. Test in non-production first
+4. Update to latest image
+5. Deploy to production
+
+---
+
+## Service Inventory Review
+
+Quarterly review all services:
+
+| Service | Last Used | Users | Issues | Decision |
+|---------|-----------|-------|--------|----------|
+| Service A | 30 days | 1 | None | Keep |
+| Service B | 90 days | 0 | None | Deprecate |
+| Service C | 7 days | 2 | Security | Migrate |
+
+---
+
+## Links
+
+- [CHANGELOG](../CHANGELOG.md)
+- [Service Inventory](../services/VERIFIED_SERVICE_INVENTORY.md)