homelab-optimized/docs/getting-started/04-Prerequisites.md

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 - Interactive Linux learning
• Docker Official Tutorial - Container fundamentals
• Networking Basics
• 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

# Essential packages
sudo apt update && sudo apt install -y \
    curl \
    wget \
    git \
    vim \
    htop \
    net-tools \
    openssh-server \
    ufw \
    fail2ban

Docker Installation

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# Add user to docker group
sudo usermod -aG docker $USER
# Logout and login again

Network Connectivity Problems

# Check network configuration
ip addr show
ip route show
systemctl status networking

# Test connectivity
ping 8.8.8.8
nslookup google.com

Storage Issues

# Check disk space
df -h
du -sh /*

# Check RAID status
cat /proc/mdstat
sudo mdadm --detail /dev/md0

Service Discovery Issues

# 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 - Deploy your first service
2. Architecture Overview - Understand the design
3. Service Categories - Explore available services
4. GitOps Deployment - Learn deployment workflows

Support Resources

Documentation

• Infrastructure Overview
• Troubleshooting Guide
• Security Guidelines

Community

• Homelab Subreddit
• Self-Hosted Community
• Docker Community

Official Documentation

• Docker Documentation
• Ubuntu Server Guide
• Ansible Documentation

---

Ensure all prerequisites are met before proceeding with the homelab deployment to avoid common setup issues and ensure a smooth installation process.