homelab-optimized/docs/admin/service-deprecation-policy.md

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

   # 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
• Service Inventory