Vish/homelab-optimized
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Sanitized mirror from private repository - 2026-03-30 19:03:43 UTC
Some checks failed
Documentation / Build Docusaurus (push) Failing after 2m52s
Details
Documentation / Deploy to GitHub Pages (push) Has been skipped
Details

Browse Source
This commit is contained in:
Gitea Mirror Bot
2026-03-30 19:03:43 +00:00
commit d14fd7afbd
1282 changed files with 331629 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

411
docs/getting-started/04-Prerequisites.md Normal file
View File

@@ -0,0 +1,411 @@
# Prerequisites
## Overview
Before diving into this homelab setup, ensure you have the necessary knowledge, tools, and hardware. This guide outlines the minimum requirements and recommended skills for successfully deploying and managing the infrastructure.
## Required Knowledge
### Essential Skills
- **Linux Administration**: Command line proficiency, file system navigation, package management
- **Networking Fundamentals**: TCP/IP, DNS, DHCP, VLANs, routing basics
- **Docker Basics**: Container concepts, docker-compose, image management
- **Git Version Control**: Repository management, branching, merging
### Recommended Skills
- **System Administration**: Service management, log analysis, troubleshooting
- **Security Practices**: SSH keys, firewall configuration, SSL/TLS certificates
- **Scripting**: Bash, Python, or similar for automation tasks
- **Monitoring**: Understanding metrics, alerting, and observability
### Learning Resources
- [Linux Journey](https://linuxjourney.com/) - Interactive Linux learning
- [Docker Official Tutorial](https://docs.docker.com/get-started/) - Container fundamentals
- [Networking Basics](https://www.cisco.com/c/en/us/solutions/small-business/resource-center/networking/networking-basics.html)
- [Git Handbook](https://guides.github.com/introduction/git-handbook/) - Version control basics
## Hardware Requirements
### Minimum Hardware
- **CPU**: 4 cores, 2.0GHz+ (x86_64 architecture)
- **RAM**: 8GB (16GB recommended)
- **Storage**: 500GB available space
- **Network**: Gigabit Ethernet connection
- **Power**: Uninterruptible Power Supply (UPS) recommended
### Recommended Hardware
- **CPU**: 8+ cores, 3.0GHz+ (Intel Xeon or AMD EPYC)
- **RAM**: 32GB+ with ECC support
- **Storage**: 2TB+ with RAID redundancy
- **Network**: 10GbE capable with managed switches
- **Power**: Enterprise UPS with network monitoring
### This Homelab Hardware
- **Atlantis**: Dell PowerEdge R720, 32GB RAM, 12TB RAID-10
- **Calypso**: Custom AMD Ryzen, 64GB RAM, 8TB RAID-1
- **Concord NUC**: Intel NUC, 16GB RAM, 1TB NVMe
- **Homelab VM**: Proxmox VM, 8GB RAM, 500GB virtual disk
- **Raspberry Pi**: Pi 5, 8GB RAM, 256GB microSD
## Software Requirements
### Operating System
- **Primary**: Ubuntu Server 22.04 LTS
- **Alternative**: Debian 12, CentOS Stream 9, Rocky Linux 9
- **Raspberry Pi**: Raspberry Pi OS Lite
### Core Software Stack
```bash
# Essential packages
sudo apt update && sudo apt install -y \
curl \
wget \
git \
vim \
htop \
net-tools \
openssh-server \
ufw \
fail2ban
```
### Docker Installation
```bash
# Install Docker Engine
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
# Install Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
# Add user to docker group
sudo usermod -aG docker $USER
```
### Git Configuration
```bash
# Configure Git
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
# Generate SSH key for Git
ssh-keygen -t ed25519 -C "your.email@example.com"
```
## Network Prerequisites
### Network Configuration
- **Static IP Addresses**: Servers should have static IPs
- **DNS Resolution**: Proper hostname resolution
- **Firewall Rules**: Appropriate port access
- **Time Synchronization**: NTP configuration
### Required Ports
| Service | Port | Protocol | Purpose |
|---------|------|----------|---------|
| SSH | 22 | TCP | Remote administration |
| HTTP | 80 | TCP | Web services |
| HTTPS | 443 | TCP | Secure web services |
| Docker API | 2376 | TCP | Docker remote API |
| Portainer | 9000 | TCP | Container management |
| Grafana | 3000 | TCP | Monitoring dashboards |
| Prometheus | 9090 | TCP | Metrics collection |
### Network Setup Example
```bash
# Configure static IP (Ubuntu/Netplan)
sudo vim /etc/netplan/00-installer-config.yaml
network:
version: 2
ethernets:
ens18:
dhcp4: false
addresses:
- 192.168.10.10/24
gateway4: 192.168.10.1
nameservers:
addresses:
- 192.168.10.1
- 8.8.8.8
# Apply configuration
sudo netplan apply
```
## Security Prerequisites
### SSH Security
```bash
# Generate SSH key pair
ssh-keygen -t ed25519 -f ~/.ssh/homelab_key
# Configure SSH client
cat >> ~/.ssh/config << EOF
Host atlantis
HostName 192.168.10.10
User homelab
IdentityFile ~/.ssh/homelab_key
Port 22
EOF
# Copy public key to servers
ssh-copy-id -i ~/.ssh/homelab_key.pub homelab@192.168.10.10
```
### Firewall Configuration
```bash
# Enable UFW firewall
sudo ufw enable
# Allow SSH
sudo ufw allow ssh
# Allow HTTP/HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
# Allow specific services
sudo ufw allow 9000/tcp # Portainer
sudo ufw allow 3000/tcp # Grafana
```
### SSL/TLS Certificates
- **Let's Encrypt**: Free SSL certificates for public domains
- **Self-signed**: For internal services
- **Certificate Management**: Automated renewal processes
## Storage Prerequisites
### Disk Configuration
```bash
# Check available disks
lsblk
# Create RAID array (example)
sudo mdadm --create --verbose /dev/md0 --level=1 --raid-devices=2 /dev/sdb /dev/sdc
# Format and mount
sudo mkfs.ext4 /dev/md0
sudo mkdir /mnt/storage
sudo mount /dev/md0 /mnt/storage
# Add to fstab for persistence
echo '/dev/md0 /mnt/storage ext4 defaults 0 2' | sudo tee -a /etc/fstab
```
### Backup Strategy
- **Local Backups**: Regular snapshots to secondary storage
- **Remote Backups**: Offsite backup to cloud or remote location
- **Backup Testing**: Regular restore testing procedures
- **Retention Policy**: Define backup retention schedules
## Monitoring Prerequisites
### System Monitoring
```bash
# Install monitoring tools
sudo apt install -y \
htop \
iotop \
nethogs \
ncdu \
smartmontools
# Enable SMART monitoring
sudo systemctl enable smartd
sudo systemctl start smartd
```
### Log Management
```bash
# Configure log rotation
sudo vim /etc/logrotate.d/docker
/var/lib/docker/containers/*/*.log {
rotate 7
daily
compress
size=1M
missingok
delaycompress
copytruncate
}
```
## Development Environment
### Local Development Setup
```bash
# Install development tools
sudo apt install -y \
build-essential \
python3 \
python3-pip \
nodejs \
npm \
code
# Install useful Python packages
pip3 install --user \
docker-compose \
ansible \
requests \
pyyaml
```
### IDE Configuration
- **VS Code**: Remote SSH extension for server editing
- **Vim/Neovim**: Terminal-based editing with plugins
- **JetBrains**: Remote development capabilities
## Automation Prerequisites
### Ansible Setup
```bash
# Install Ansible
sudo apt install -y ansible
# Create inventory file
cat > inventory.ini << EOF
[homelab]
atlantis ansible_host=192.168.10.10
calypso ansible_host=192.168.10.20
concord ansible_host=192.168.10.30
[homelab:vars]
ansible_user=homelab
ansible_ssh_private_key_file=~/.ssh/homelab_key
EOF
# Test connectivity
ansible -i inventory.ini homelab -m ping
```
### CI/CD Prerequisites
- **Git Repository**: Version control for configurations
- **CI/CD Platform**: Gitea Actions, GitHub Actions, or GitLab CI
- **Container Registry**: Docker Hub or private registry
- **Deployment Keys**: SSH keys for automated deployments
## Backup and Recovery
### Backup Tools
```bash
# Install backup utilities
sudo apt install -y \
rsync \
restic \
borgbackup \
duplicity
# Configure restic repository
export RESTIC_REPOSITORY="/mnt/backup/restic"
export RESTIC_PASSWORD="REDACTED_PASSWORD"
restic init
```
### Recovery Planning
- **Documentation**: Detailed recovery procedures
- **Testing**: Regular disaster recovery drills
- **Offsite Storage**: Remote backup locations
- **Recovery Time Objectives**: Define acceptable downtime
## Validation Checklist
### Pre-deployment Checklist
- [ ] Hardware meets minimum requirements
- [ ] Operating system installed and updated
- [ ] Docker and Docker Compose installed
- [ ] Git configured with SSH keys
- [ ] Network connectivity verified
- [ ] Firewall rules configured
- [ ] SSH access working
- [ ] Storage properly configured
- [ ] Backup strategy implemented
- [ ] Monitoring tools installed
### Post-deployment Checklist
- [ ] All services accessible
- [ ] Monitoring dashboards functional
- [ ] Backup jobs running successfully
- [ ] Security hardening applied
- [ ] Documentation updated
- [ ] Team access configured
- [ ] Alerting rules tested
- [ ] Performance baselines established
## Common Issues and Solutions
### Docker Permission Issues
```bash
# Add user to docker group
sudo usermod -aG docker $USER
# Logout and login again
```
### Network Connectivity Problems
```bash
# Check network configuration
ip addr show
ip route show
systemctl status networking
# Test connectivity
ping 8.8.8.8
nslookup google.com
```
### Storage Issues
```bash
# Check disk space
df -h
du -sh /*
# Check RAID status
cat /proc/mdstat
sudo mdadm --detail /dev/md0
```
### Service Discovery Issues
```bash
# Check DNS resolution
nslookup service.local
dig service.local
# Check service status
docker ps
docker-compose ps
systemctl status docker
```
## Next Steps
Once prerequisites are met:
1. **[Quick Start Guide](QUICK_START.md)** - Deploy your first service
2. **[Architecture Overview](03-Architecture-Overview.md)** - Understand the design
3. **[Service Categories](../services/categories.md)** - Explore available services
4. **[GitOps Deployment](../GITOPS_DEPLOYMENT_GUIDE.md)** - Learn deployment workflows
## Support Resources
### Documentation
- [Infrastructure Overview](../infrastructure/INFRASTRUCTURE_OVERVIEW.md)
- [Troubleshooting Guide](../troubleshooting/README.md)
- [Security Guidelines](../security/README.md)
### Community
- [Homelab Subreddit](https://reddit.com/r/homelab)
- [Self-Hosted Community](https://reddit.com/r/selfhosted)
- [Docker Community](https://forums.docker.com/)
### Official Documentation
- [Docker Documentation](https://docs.docker.com/)
- [Ubuntu Server Guide](https://ubuntu.com/server/docs)
- [Ansible Documentation](https://docs.ansible.com/)
---
*Ensure all prerequisites are met before proceeding with the homelab deployment to avoid common setup issues and ensure a smooth installation process.*