Vish/homelab-optimized

Fork 0

Files

Gitea Mirror Bot bd82e850ee

Documentation / Deploy to GitHub Pages (push) Has been cancelled

Details

Documentation / Build Docusaurus (push) Has started running

Details

Sanitized mirror from private repository - 2026-03-21 11:14:37 UTC

2026-03-21 11:14:37 +00:00

10 KiB

Raw Blame History

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:

Quick Start Guide - Deploy your first service
Architecture Overview - Understand the design
Service Categories - Explore available services
GitOps Deployment - Learn deployment workflows

Support Resources

Documentation

Community

Official Documentation

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

10 KiB Raw Blame History