# 🤖 AGENTS.md - Homelab Repository Guide

*AI Agent contributor guide for Vish's homelab infrastructure repository*

## Agent Identity

- **Nickname**: Vesper

## Repository Overview

This is a **GitOps-managed homelab infrastructure** repository containing Docker Compose configurations, documentation, and automation scripts for a comprehensive homelab setup.

### Key Characteristics
- **65+ active Portainer stacks** deployed via GitOps
- **Multi-host architecture**: Atlantis, Calypso, homelab_vm, concord_nuc, raspberry-pi-5-vish
- **Production environment**: Live services with 24/7 uptime requirements
- **Comprehensive monitoring**: Prometheus, Grafana, AlertManager stack
- **Documentation-heavy**: Extensive markdown documentation with cross-references

## Repository Structure

```
homelab/
├── hosts/                    # Host-specific configurations
│   ├── Atlantis/            # Primary NAS (Synology DS1821+)
│   ├── Calypso/             # Secondary NAS/compute
│   ├── homelab_vm/          # Main VM services
│   ├── concord_nuc/         # Intel NUC services
│   └── raspberry-pi-5-vish/ # Pi-based services
├── docs/                    # Comprehensive documentation
│   ├── getting-started/     # Beginner guides
│   ├── infrastructure/      # Infrastructure docs
│   ├── services/           # Service documentation
│   ├── admin/              # Administrative guides
│   └── troubleshooting/    # Problem resolution
├── common/                 # Shared configurations
├── scripts/               # Automation utilities
├── ansible/              # Ansible playbooks
└── archive/              # Deprecated configurations
```

## Critical Guidelines

### 🚨 Production Environment
- **NEVER modify production compose files** without understanding impact
- **Test changes in development** before applying to production
- **Verify GitOps compatibility** - Portainer pulls from this repo
- **Maintain service availability** - 65+ services depend on these configs

### 📝 Documentation Standards
- **Fix broken links** when found (currently ~4 remaining)
- **Update cross-references** when moving/renaming files
- **Maintain INDEX.md** as the central navigation hub
- **Use relative paths** for internal documentation links

### 🔧 GitOps Workflow
- **All changes go through Git** - Portainer auto-deploys from main branch
- **Preserve file paths** - Stacks reference specific file locations
- **Test deployments** before pushing to main
- **Monitor stack health** after changes

## Common Tasks

### Adding New Services
1. **Choose appropriate host** based on resource requirements
2. **Create docker-compose.yml** in host directory
3. **Add documentation** in `docs/services/individual/`
4. **Update service inventory** in `docs/services/`
5. **Test deployment** via Portainer
6. **Monitor service health**

### Documentation Updates
1. **Check for broken links** using link checker scripts
2. **Update INDEX.md** if adding new major sections
3. **Maintain consistent formatting** with existing docs
4. **Test all cross-references** after changes

### Infrastructure Changes
1. **Document changes** in appropriate infrastructure docs
2. **Update monitoring** if adding new hosts/services
3. **Verify backup coverage** for new systems
4. **Update network documentation** if needed

## Service Categories

### Core Infrastructure
- **Monitoring**: Prometheus, Grafana, AlertManager
- **Networking**: Nginx Proxy Manager, Pi-hole, WireGuard
- **Storage**: Syncthing, Seafile, backup services
- **Authentication**: Authentik SSO

### Media & Entertainment
- **Streaming**: Plex, Jellyfin
- **Management**: Arr suite (Sonarr, Radarr, etc.)
- **Books**: Calibre, AudioBookShelf

### Productivity
- **Communication**: Matrix, Mattermost, Mastodon
- **Documents**: Paperless-ngx, Stirling PDF
- **Development**: Gitea, OpenHands, CI/CD runners

### Home Automation
- **Platform**: Home Assistant
- **Protocols**: Zigbee2MQTT, Z-Wave
- **Monitoring**: Various IoT sensors

## Monitoring & Alerting

### Key Metrics
- **Service availability**: All services monitored via Uptime Kuma
- **System resources**: CPU, memory, disk, network
- **Container health**: Docker container status
- **Network performance**: Latency, throughput

### Alert Channels
- **NTFY**: Push notifications for critical alerts
- **Email**: Backup notification channel
- **Dashboard**: Grafana visual alerts

## Backup Strategy

### Data Protection
- **3-2-1 rule**: 3 copies, 2 different media, 1 offsite
- **Automated backups**: Daily incremental, weekly full
- **Configuration backups**: Docker volumes, configs
- **Documentation backups**: Git repository mirroring

### Recovery Procedures
- **Service restoration**: Docker stack redeployment
- **Data recovery**: Backup restoration procedures
- **Disaster recovery**: Complete infrastructure rebuild

## Security Considerations

### Access Control
- **VPN-only access**: Tailscale mesh network
- **SSO integration**: Authentik for centralized auth
- **Network segmentation**: VLANs for different service tiers
- **Regular updates**: Automated security patching

### Data Protection
- **Encryption**: Data at rest and in transit
- **Secrets management**: Docker secrets, environment variables
- **Audit logging**: Comprehensive access logging
- **Vulnerability scanning**: Regular security assessments

## Development Workflow

### Local Development
1. **Clone repository** to development environment
2. **Test changes** in isolated environment
3. **Validate compose files** using validation scripts
4. **Check documentation links** before committing

### Deployment Process
1. **Commit changes** to feature branch
2. **Test deployment** in staging environment
3. **Merge to main** after validation
4. **Monitor GitOps deployment** via Portainer
5. **Verify service health** post-deployment

## Troubleshooting

### Common Issues
- **Service startup failures**: Check logs, resource constraints
- **Network connectivity**: Verify network configuration
- **Storage issues**: Check disk space, mount points
- **Authentication problems**: Verify SSO configuration

### Diagnostic Tools
- **Portainer**: Container management and logs
- **Grafana**: Performance metrics and alerts
- **SSH access**: Direct system administration
- **Log aggregation**: Centralized logging system

## Best Practices

### Code Quality
- **Use official images** when possible
- **Pin image versions** for stability
- **Document environment variables** and volumes
- **Follow Docker best practices** for security

### Documentation
- **Keep docs current** with infrastructure changes
- **Use clear, descriptive titles** and sections
- **Include troubleshooting steps** for common issues
- **Maintain consistent formatting** across all docs

### Monitoring
- **Monitor everything** that matters to service availability
- **Set appropriate thresholds** to avoid alert fatigue
- **Document alert procedures** for quick response
- **Regular health checks** for all critical services

---

**Remember**: This is a production homelab with real users and services. Changes should be made thoughtfully with proper testing and documentation. When in doubt, ask questions and test thoroughly before deploying to production.

**Status**: ✅ Repository actively maintained with 65+ production services