# 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)