Initial commit: Phase 1 foundation documentation
This commit is contained in:
290
README.md
Normal file
290
README.md
Normal file
@@ -0,0 +1,290 @@
|
||||
# 🏠 Homelab Infrastructure
|
||||
|
||||
**Owner:** Your Name
|
||||
**Last Updated:** October 31, 2025
|
||||
**Status:** Operational
|
||||
**Purpose:** Personal learning, self-hosted services, development environment
|
||||
|
||||
---
|
||||
|
||||
## 📋 Quick Reference
|
||||
|
||||
| Resource | Value | Status |
|
||||
|----------|-------|--------|
|
||||
| **Platform** | Unraid 7.2.0 | ✅ Running |
|
||||
| **Hostname** | Tower | ✅ Online |
|
||||
| **IP Address** | 192.168.68.51/22 | ✅ Active |
|
||||
| **Uptime** | 3 minutes (as of last config) | ✅ Stable |
|
||||
| **Services** | 6 running / 32 total | ⚠️ Cleanup needed |
|
||||
|
||||
---
|
||||
|
||||
## 🖥️ Hardware Overview
|
||||
|
||||
### Compute
|
||||
- **CPU:** AMD Ryzen 9 7945HX (16 cores / 32 threads)
|
||||
- Base: 2.5 GHz
|
||||
- Boost: 5.46 GHz
|
||||
- Current Load: <1% (massive headroom)
|
||||
- **Memory:** 60GB DDR4/DDR5
|
||||
- Used: 4.4GB (7%)
|
||||
- Available: 56GB
|
||||
- **GPU:** NVIDIA GeForce RTX 4090
|
||||
- Status: Available for transcoding/AI workloads
|
||||
- VRAM: 24GB
|
||||
|
||||
### Storage
|
||||
- **Parity:** 12TB WD Red Plus (sdb)
|
||||
- **Data Disk 1:** 12TB WD Red Plus (sdc) - 1TB used (10%)
|
||||
- **Cache Pool:** 932GB WD Red SN700 NVMe - 578GB used (63%) ⚠️
|
||||
- **Boot Drive:** 58GB Kingston USB 3.0
|
||||
|
||||
### Network
|
||||
- **NIC:** Realtek RTL8125 2.5GbE
|
||||
- **Primary Network:** 192.168.68.0/22 (br0)
|
||||
- **VPN:** Tailscale (100.122.220.126)
|
||||
- **Remote Access:** Cloudflare Tunnel
|
||||
|
||||
---
|
||||
|
||||
## 🌐 Network Architecture
|
||||
|
||||
```
|
||||
Internet
|
||||
│
|
||||
├─── TP-Link Router (192.168.68.1)
|
||||
│ │
|
||||
│ ├─── Raspberry Pi Zero (Pi-hole + Unbound DNS)
|
||||
│ ├─── Unraid Server (192.168.68.51) ← YOU ARE HERE
|
||||
│ ├─── Gaming PC
|
||||
│ ├─── Laptop (daily driver)
|
||||
│ └─── PiKVM (remote server management)
|
||||
│
|
||||
└─── Cloudflare Tunnel (external access)
|
||||
└─── Tailscale VPN (secure remote)
|
||||
```
|
||||
|
||||
**Subnets:**
|
||||
- Primary LAN: `192.168.68.0/22` (1022 usable IPs)
|
||||
- Docker Bridge: `172.17.0.0/16`
|
||||
- Libvirt: `192.168.122.0/24`
|
||||
- Tailscale: `100.64.0.0/10` (CGNAT range)
|
||||
|
||||
---
|
||||
|
||||
## 📦 Running Services
|
||||
|
||||
| Service | Container | Port(s) | Purpose |
|
||||
|---------|-----------|---------|---------|
|
||||
| **LLM Interface** | open-webui | 3000 | ChatGPT-like UI for local models |
|
||||
| **Reverse Proxy** | NginxProxyManager | 1880, 7818, 18443 | SSL termination, routing |
|
||||
| **Git Server** | Gitea | 22, 3002 | Version control (GitHub alternative) |
|
||||
| **Remote Desktop** | ApacheGuacamole | 4000 | Browser-based RDP/VNC/SSH |
|
||||
| **Tunnel** | Cloudflared | 46495 | Secure external access |
|
||||
| **Password Manager** | Vaultwarden | 4743 | Self-hosted Bitwarden |
|
||||
|
||||
**Access URLs:**
|
||||
- Unraid Dashboard: `http://192.168.68.51`
|
||||
- Gitea: `http://192.168.68.51:3002`
|
||||
- Nginx Proxy Manager: `http://192.168.68.51:7818`
|
||||
- open-webui: `http://192.168.68.51:3000`
|
||||
- Vaultwarden: `http://192.168.68.51:4743`
|
||||
- Guacamole: `http://192.168.68.51:4000`
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation Structure
|
||||
|
||||
```
|
||||
infrastructure/
|
||||
├── README.md ← You are here
|
||||
├── docs/
|
||||
│ ├── network-map.md # Detailed network topology
|
||||
│ ├── service-inventory.md # Complete service catalog
|
||||
│ ├── quick-start.md # Emergency recovery guide
|
||||
│ └── runbooks/
|
||||
│ └── restart-services.md # Common procedures
|
||||
├── docker-compose/ # Future: Compose stacks
|
||||
├── configs/ # Configuration files
|
||||
├── scripts/ # Automation scripts
|
||||
└── .gitignore # Git exclusions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Current Focus Areas
|
||||
|
||||
### ✅ Working Well
|
||||
- Core infrastructure stable (reverse proxy, VPN, Git)
|
||||
- Professional tools in place (Gitea, NPM, Vaultwarden)
|
||||
- Remote access configured (Tailscale + Cloudflare)
|
||||
- GPU available for acceleration projects
|
||||
|
||||
### ⚠️ Needs Attention
|
||||
- **Monitoring:** Grafana/InfluxDB/Telegraf stack stopped (no observability)
|
||||
- **Cache Storage:** 63% full - approaching performance threshold
|
||||
- **Container Cleanup:** 26 of 32 containers stopped (decision needed)
|
||||
- **Backups:** No automated backup strategy evident
|
||||
- **Documentation:** Starting to build comprehensive docs (this repo!)
|
||||
|
||||
### 🚀 Planned Improvements
|
||||
- Phase 1: Foundation documentation (IN PROGRESS)
|
||||
- Phase 2: Restart monitoring stack
|
||||
- Phase 3: Implement backup strategy
|
||||
- Phase 4: Container consolidation
|
||||
- Phase 5: GPU utilization projects
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Quick Commands
|
||||
|
||||
### System Information
|
||||
```bash
|
||||
# Check system status
|
||||
uname -a
|
||||
uptime
|
||||
|
||||
# Resource usage
|
||||
free -h
|
||||
df -h
|
||||
docker stats --no-stream
|
||||
```
|
||||
|
||||
### Docker Management
|
||||
```bash
|
||||
# List all containers
|
||||
docker ps -a
|
||||
|
||||
# View logs
|
||||
docker logs <container_name>
|
||||
|
||||
# Restart service
|
||||
docker restart <container_name>
|
||||
|
||||
# System cleanup (careful!)
|
||||
docker system prune -a
|
||||
```
|
||||
|
||||
### Network Troubleshooting
|
||||
```bash
|
||||
# Check interfaces
|
||||
ip addr show
|
||||
|
||||
# Test connectivity
|
||||
ping 192.168.68.1
|
||||
ping 8.8.8.8
|
||||
|
||||
# DNS resolution
|
||||
nslookup google.com
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📖 Learning Resources
|
||||
|
||||
**Official Documentation:**
|
||||
- [Unraid Docs](https://docs.unraid.net/)
|
||||
- [Docker Docs](https://docs.docker.com/)
|
||||
- [Gitea Docs](https://docs.gitea.io/)
|
||||
|
||||
**Community:**
|
||||
- [r/unraid](https://reddit.com/r/unraid)
|
||||
- [r/homelab](https://reddit.com/r/homelab)
|
||||
- [r/selfhosted](https://reddit.com/r/selfhosted)
|
||||
|
||||
**YouTube Channels:**
|
||||
- SpaceInvaderOne (Unraid specialist)
|
||||
- Techno Tim (homelab projects)
|
||||
- NetworkChuck (networking, Docker, security)
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Security Notes
|
||||
|
||||
**Access Control:**
|
||||
- ✅ Tailscale VPN for secure remote access
|
||||
- ✅ Cloudflare Tunnel (no open ports on router)
|
||||
- ✅ Reverse proxy with SSL capability
|
||||
- ⚠️ Review firewall rules (currently permissive)
|
||||
- ⚠️ Enable MFA where available
|
||||
|
||||
**Secrets Management:**
|
||||
- ⚠️ Current: Environment variables (plain text)
|
||||
- 🎯 Goal: Docker Secrets or encrypted vault
|
||||
- 📋 TODO: Implement proper secrets rotation
|
||||
|
||||
---
|
||||
|
||||
## 📞 Getting Help
|
||||
|
||||
**When things break:**
|
||||
1. Check `docs/troubleshooting/` (future section)
|
||||
2. Review container logs: `docker logs <name>`
|
||||
3. Consult `docs/runbooks/` for procedures
|
||||
4. Search Unraid forums
|
||||
5. Ask in r/unraid or r/homelab
|
||||
|
||||
**Emergency Contacts:**
|
||||
- Document important contacts here (ISP, etc.)
|
||||
|
||||
---
|
||||
|
||||
## 📝 Change Log
|
||||
|
||||
| Date | Change | Impact |
|
||||
|------|--------|--------|
|
||||
| 2025-10-31 | Initial documentation created | Foundation established |
|
||||
| 2025-10-31 | System configuration exported | Baseline captured |
|
||||
|
||||
---
|
||||
|
||||
## 🎓 Project History
|
||||
|
||||
**Completed:**
|
||||
- Unraid server setup and configuration
|
||||
- Docker container deployment (32 total)
|
||||
- Network infrastructure (VPN, tunnel, reverse proxy)
|
||||
- GPU passthrough capability
|
||||
- Core services: Git, password manager, remote access
|
||||
|
||||
**In Progress:**
|
||||
- Documentation project (Phase 1) ← YOU ARE HERE
|
||||
- Monitoring stack restart
|
||||
- Backup strategy implementation
|
||||
|
||||
**Planned:**
|
||||
- Container cleanup and consolidation
|
||||
- GPU utilization projects (Jellyfin transcoding, AI/ML)
|
||||
- Network segmentation (VLANs)
|
||||
- Infrastructure as Code (Ansible/Terraform)
|
||||
|
||||
---
|
||||
|
||||
## 🏆 Goals
|
||||
|
||||
**Short-term (1-3 months):**
|
||||
- Complete documentation (all phases)
|
||||
- Restart and configure monitoring
|
||||
- Implement automated backups
|
||||
- Clean up stopped containers
|
||||
- Define service strategy (what to keep/remove)
|
||||
|
||||
**Long-term (3-12 months):**
|
||||
- Build professional portfolio of projects
|
||||
- Master Docker Compose and orchestration
|
||||
- Implement CI/CD pipelines
|
||||
- Create homelab tutorials/blog posts
|
||||
- Achieve 95%+ uptime for critical services
|
||||
|
||||
---
|
||||
|
||||
## 📜 License
|
||||
|
||||
Personal infrastructure - not licensed for public use.
|
||||
Documentation and configurations © 2025
|
||||
|
||||
---
|
||||
|
||||
**Last Review:** October 31, 2025
|
||||
**Next Review:** December 1, 2025
|
||||
**Status:** Living document - update as infrastructure evolves
|
||||
Reference in New Issue
Block a user