EZ-Homelab/docs/getting-started.md

Getting Started Guide

This guide will walk you through setting up your AI-powered homelab from scratch.

Prerequisites

Before you begin, ensure you have:

• A Linux server (Ubuntu 22.04+ recommended)
• Docker Engine 24.0+ installed
• Docker Compose V2 installed
• Git installed
• At least 8GB RAM (16GB+ recommended)
• Sufficient disk space (100GB+ recommended)
• Static IP address for your server
• VS Code with GitHub Copilot extension (for AI assistance)

Step 1: Verify Docker Installation

# Check Docker version
docker --version
# Should show: Docker version 24.0.0 or higher

# Check Docker Compose version
docker compose version
# Should show: Docker Compose version v2.x.x

# Test Docker works
docker run --rm hello-world
# Should download and run successfully

Step 2: Clone the Repository

# Navigate to your home directory
cd ~

# Clone the repository
git clone https://github.com/kelinfoxy/AI-Homelab.git

# Enter the directory
cd AI-Homelab

Step 3: Configure Environment Variables

# Copy the example environment file
cp .env.example .env

# Get your user and group IDs
id -u  # This is your PUID
id -g  # This is your PGID

# Edit the .env file
nano .env

Update these values in .env:

# Your user/group IDs
PUID=1000           # Replace with your user ID
PGID=1000           # Replace with your group ID

# Your timezone (find yours: timedatectl list-timezones)
TZ=America/New_York

# Your server's IP address
SERVER_IP=192.168.1.100  # Replace with your actual IP

# Directory paths
USERDIR=/home/yourusername/homelab  # Update username
MEDIADIR=/mnt/media                 # Update if different
DOWNLOADDIR=/mnt/downloads          # Update if different

# Set secure passwords for services
GRAFANA_ADMIN_PASSWORD=your-secure-password-here
CODE_SERVER_PASSWORD=your-secure-password-here
POSTGRES_PASSWORD=your-secure-password-here
PGADMIN_PASSWORD=your-secure-password-here
JUPYTER_TOKEN=your-secure-token-here
PIHOLE_PASSWORD=your-secure-password-here

Save and exit (Ctrl+X, Y, Enter in nano)

Step 4: Create Docker Networks

# Create the main homelab network
docker network create homelab-network

# Create additional networks for better security
docker network create media-network
docker network create monitoring-network
docker network create database-network

# Verify networks were created
docker network ls

Step 5: Create Configuration Directories

# Create the main config directory
mkdir -p config

# Create config directories for services you plan to use
mkdir -p config/{nginx-proxy-manager,pihole,portainer}
mkdir -p config/{plex,sonarr,radarr,prowlarr,qbittorrent,jellyfin}
mkdir -p config/{prometheus,grafana,loki,promtail}
mkdir -p config/{code-server,postgres,redis}

# Set proper permissions
sudo chown -R $(id -u):$(id -g) config/

Step 6: Copy Configuration Templates (Optional)

For services that need config files:

# Prometheus
mkdir -p config/prometheus
cp config-templates/prometheus/prometheus.yml config/prometheus/

# Loki
mkdir -p config/loki
cp config-templates/loki/loki-config.yml config/loki/

# Promtail
mkdir -p config/promtail
cp config-templates/promtail/promtail-config.yml config/promtail/

# Redis
mkdir -p config/redis
cp config-templates/redis/redis.conf config/redis/

Step 7: Start Your First Service (Portainer)

Portainer provides a web UI for managing Docker containers. It's a great first service to deploy.

# Start Portainer
docker compose -f docker-compose/infrastructure.yml up -d portainer

# Check if it's running
docker compose -f docker-compose/infrastructure.yml ps

# View logs
docker compose -f docker-compose/infrastructure.yml logs -f portainer

Access Portainer:

1. Open your browser
2. Navigate to http://YOUR_SERVER_IP:9000
3. Create an admin account on first login
4. Select "Get Started" and choose local Docker environment

Step 8: Deploy Infrastructure Services

# Start all infrastructure services
docker compose -f docker-compose/infrastructure.yml up -d

# Check status
docker compose -f docker-compose/infrastructure.yml ps

# Services now running:
# - Nginx Proxy Manager: http://YOUR_SERVER_IP:81
# - Pi-hole: http://YOUR_SERVER_IP:8080/admin
# - Portainer: http://YOUR_SERVER_IP:9000
# - Watchtower: (runs in background, no UI)

Configure Nginx Proxy Manager (Optional)

1. Access: http://YOUR_SERVER_IP:81
2. Login with default credentials:
   • Email: admin@example.com
   • Password: changeme
3. Change password immediately
4. Add proxy hosts for your services

Configure Pi-hole (Optional)

1. Access: http://YOUR_SERVER_IP:8080/admin
2. Login with password from .env (PIHOLE_PASSWORD)
3. Configure DNS settings
4. Update your router to use Pi-hole as DNS server

Step 9: Deploy Media Services (Optional)

If you want a media server setup:

# Start media services
docker compose -f docker-compose/media.yml up -d

# Check status
docker compose -f docker-compose/media.yml ps

# Services now running:
# - Plex: http://YOUR_SERVER_IP:32400/web
# - Jellyfin: http://YOUR_SERVER_IP:8096
# - Sonarr: http://YOUR_SERVER_IP:8989
# - Radarr: http://YOUR_SERVER_IP:7878
# - Prowlarr: http://YOUR_SERVER_IP:9696
# - qBittorrent: http://YOUR_SERVER_IP:8081

Initial Media Service Setup

Plex:

1. Access: http://YOUR_SERVER_IP:32400/web
2. Sign in with your Plex account
3. Add your media libraries

Sonarr/Radarr:

1. Access the web UI
2. Go to Settings → Profiles → Quality
3. Configure your quality preferences
4. Add Prowlarr as an indexer
5. Add qBittorrent as a download client

Step 10: Deploy Monitoring Services (Optional)

For system and service monitoring:

# Start monitoring services
docker compose -f docker-compose/monitoring.yml up -d

# Check status
docker compose -f docker-compose/monitoring.yml ps

# Services now running:
# - Prometheus: http://YOUR_SERVER_IP:9090
# - Grafana: http://YOUR_SERVER_IP:3000
# - Node Exporter: http://YOUR_SERVER_IP:9100
# - cAdvisor: http://YOUR_SERVER_IP:8082
# - Uptime Kuma: http://YOUR_SERVER_IP:3001

Configure Grafana

1. Access: http://YOUR_SERVER_IP:3000
2. Login with credentials from .env:
   • Username: admin
   • Password: GRAFANA_ADMIN_PASSWORD from .env
3. Add Prometheus as a data source:
   • URL: http://prometheus:9090
4. Import dashboards:
   • Dashboard ID 1860 for Node Exporter
   • Dashboard ID 893 for Docker metrics

Configure Uptime Kuma

1. Access: http://YOUR_SERVER_IP:3001
2. Create an account on first login
3. Add monitors for your services

Step 11: Deploy Development Services (Optional)

If you need development tools:

# Start development services
docker compose -f docker-compose/development.yml up -d

# Check status
docker compose -f docker-compose/development.yml ps

# Services now running:
# - Code Server: http://YOUR_SERVER_IP:8443
# - PostgreSQL: localhost:5432
# - Redis: localhost:6379
# - pgAdmin: http://YOUR_SERVER_IP:5050
# - Jupyter Lab: http://YOUR_SERVER_IP:8888
# - Node-RED: http://YOUR_SERVER_IP:1880

Step 12: Set Up VS Code with GitHub Copilot

1. Install VS Code on your local machine (if not already installed)

2. Install GitHub Copilot extension:

   • Open VS Code
   • Go to Extensions (Ctrl+Shift+X)
   • Search for "GitHub Copilot"
   • Click Install
   • Sign in with your GitHub account

3. Clone your repository in VS Code:

   # On your local machine
   git clone https://github.com/kelinfoxy/AI-Homelab.git
   cd AI-Homelab
   code .
   

4. Start using AI assistance:

   • Open Copilot Chat (Ctrl+Shift+I or click the chat icon)
   • The AI assistant automatically follows the guidelines in .github/copilot-instructions.md
   • Ask questions like:
     • "Help me add Home Assistant to my homelab"
     • "Create a backup script for my Docker volumes"
     • "How do I configure GPU support for Plex?"

Step 13: Verify Everything is Running

# Check all running containers
docker ps

# Check container health
docker ps --format "table {{.Names}}\t{{.Status}}"

# View resource usage
docker stats --no-stream

# Check disk usage
docker system df

Step 14: Set Up Backups

Create a backup script:

# Create a backup directory
mkdir -p ~/backups

# Create a simple backup script
cat > ~/backup-homelab.sh << 'EOF'
#!/bin/bash
BACKUP_DIR=~/backups
DATE=$(date +%Y%m%d)

# Backup config directories
tar czf $BACKUP_DIR/config-$DATE.tar.gz ~/AI-Homelab/config/

# Backup .env file
cp ~/AI-Homelab/.env $BACKUP_DIR/.env-$DATE

# Backup Docker volumes (example for Portainer)
docker run --rm \
  -v portainer-data:/data \
  -v $BACKUP_DIR:/backup \
  busybox tar czf /backup/portainer-data-$DATE.tar.gz /data

echo "Backup completed: $DATE"
EOF

# Make it executable
chmod +x ~/backup-homelab.sh

# Test the backup
~/backup-homelab.sh

Set up a cron job for automated backups:

# Open crontab
crontab -e

# Add this line to run backup daily at 2 AM
0 2 * * * /home/yourusername/backup-homelab.sh

Step 15: Configure Firewall (Optional but Recommended)

If using UFW:

# Allow SSH (if not already allowed)
sudo ufw allow 22/tcp

# Allow web traffic (if exposing services to internet)
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# Allow specific services from local network only
# Replace 192.168.1.0/24 with your network
sudo ufw allow from 192.168.1.0/24 to any port 9000 proto tcp  # Portainer
sudo ufw allow from 192.168.1.0/24 to any port 81 proto tcp    # Nginx Proxy Manager
sudo ufw allow from 192.168.1.0/24 to any port 3000 proto tcp  # Grafana

# Enable firewall
sudo ufw enable

Next Steps

Now that your homelab is running:

1. Explore Services:

   • Access each service's web UI
   • Configure settings as needed
   • Set up integrations between services

2. Add More Services:

   • Ask GitHub Copilot for help adding new services
   • Follow the patterns in existing compose files
   • Check awesome-selfhosted for ideas

3. Optimize:

   • Review logs for errors
   • Adjust resource limits
   • Set up proper monitoring and alerts

4. Secure:

   • Change all default passwords
   • Set up SSL certificates (use Nginx Proxy Manager)
   • Enable 2FA where available
   • Keep services updated

5. Learn:

   • Read the Docker Guidelines
   • Experiment with new services
   • Use AI assistance to understand and modify configurations

Troubleshooting

Can't access services

1. Check if service is running:

   docker ps
   

2. Check service logs:

   docker compose -f docker-compose/file.yml logs service-name
   

3. Verify network connectivity:

   ping YOUR_SERVER_IP
   

4. Check firewall:

   sudo ufw status
   

Permission errors

# Fix config directory permissions
sudo chown -R $(id -u):$(id -g) config/

# Verify PUID/PGID in .env match your user
id -u  # Should match PUID in .env
id -g  # Should match PGID in .env

Port already in use

# Find what's using the port
sudo netstat -tlnp | grep PORT_NUMBER

# Stop the conflicting service or change the port in docker-compose

Out of disk space

# Check disk usage
df -h

# Clean up Docker resources
docker system prune -a

# Remove old logs
docker compose logs --tail=0 service-name

Getting Help

• Documentation: Check the docs/ directory for comprehensive guides
• AI Assistance: Use GitHub Copilot in VS Code for real-time help
• Community: Search for service-specific help in respective communities
• Issues: Open an issue on GitHub for problems with this repository

Success Checklist

• Docker and Docker Compose installed
• Repository cloned
• .env file configured
• Networks created
• Config directories created
• Portainer running and accessible
• Infrastructure services deployed
• At least one service category deployed (media/monitoring/dev)
• VS Code with GitHub Copilot set up
• Backup strategy in place
• Firewall configured (if applicable)
• All services accessible and working

Congratulations! Your AI-powered homelab is now running! 🎉