EZ-Homelab/docs/quick-reference.md

Quick Reference Guide

Common Commands

Note: Replace infrastructure.yml with your compose file name:

• infrastructure.yml - Core services
• media.yml - Media stack
• monitoring.yml - Monitoring services
• development.yml - Development tools

Service Management

# Start all services in a compose file (from stack directory)
cd /opt/stacks/stack-name/
docker compose up -d

# Start all services (from anywhere, using full path)
docker compose -f /opt/stacks/stack-name/docker-compose.yml up -d

# Start specific service (from stack directory)
cd /opt/stacks/stack-name/
docker compose up -d service-name

# Start specific service (from anywhere)
docker compose -f /opt/stacks/stack-name/docker-compose.yml up -d service-name

# Stop all services (from stack directory)
cd /opt/stacks/stack-name/
docker compose down

# Stop all services (from anywhere)
docker compose -f /opt/stacks/stack-name/docker-compose.yml down

# Stop specific service (from stack directory)
cd /opt/stacks/stack-name/
docker compose stop service-name

# Stop specific service (from anywhere)
docker compose -f /opt/stacks/stack-name/docker-compose.yml stop service-name

# Restart service (from stack directory)
cd /opt/stacks/stack-name/
docker compose restart service-name

# Restart service (from anywhere)
docker compose -f /opt/stacks/stack-name/docker-compose.yml restart service-name

# Remove service and volumes (from stack directory)
cd /opt/stacks/stack-name/
docker compose down -v

# Remove service and volumes (from anywhere)
docker compose -f /opt/stacks/stack-name/docker-compose.yml down -v

Note: There's more than one way to manage containers - use whichever is most convenient:

• Navigate to /opt/stacks/stack-name/ and use short commands
• Use full paths with -f flag from anywhere in the system

Monitoring

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

# Check service status
docker compose -f docker-compose/file.yml ps

# View resource usage
docker stats

# Inspect service
docker inspect container-name

Updates

# Pull latest images
docker compose -f docker-compose/file.yml pull

# Pull and update specific service
docker compose -f docker-compose/file.yml pull service-name
docker compose -f docker-compose/file.yml up -d service-name

Network Management

# List networks
docker network ls

# Inspect network
docker network inspect homelab-network

# Create network
docker network create network-name

# Remove network
docker network rm network-name

Volume Management

# List volumes
docker volume ls

# Inspect volume
docker volume inspect volume-name

# Remove volume
docker volume rm volume-name

# Backup volume
docker run --rm -v volume-name:/data -v $(pwd)/backups:/backup \
  busybox tar czf /backup/backup.tar.gz /data

# Restore volume
docker run --rm -v volume-name:/data -v $(pwd)/backups:/backup \
  busybox tar xzf /backup/backup.tar.gz -C /

System Maintenance

# View disk usage
docker system df

# Clean up unused resources
docker system prune

# Clean up everything (careful!)
docker system prune -a --volumes

# Remove unused images
docker image prune

# Remove unused volumes
docker volume prune

# Remove unused networks
docker network prune

Port Reference

Infrastructure Services

• 80: Nginx Proxy Manager (HTTP)
• 443: Nginx Proxy Manager (HTTPS)
• 81: Nginx Proxy Manager (Admin)
• 53: Pi-hole (DNS)
• 8080: Pi-hole (Web UI)
• 9000: Portainer
• 9443: Portainer (HTTPS)

Media Services

• 32400: Plex
• 8096: Jellyfin
• 8989: Sonarr
• 7878: Radarr
• 9696: Prowlarr
• 8081: qBittorrent

Monitoring Services

• 9090: Prometheus
• 3000: Grafana
• 9100: Node Exporter
• 8082: cAdvisor
• 3001: Uptime Kuma
• 3100: Loki

Development Services

• 8443: Code Server
• 8929: GitLab
• 2222: GitLab SSH
• 5432: PostgreSQL
• 6379: Redis
• 5050: pgAdmin
• 8888: Jupyter Lab
• 1880: Node-RED

Environment Variables Quick Reference

# User/Group
PUID=1000              # Your user ID (get with: id -u)
PGID=1000              # Your group ID (get with: id -g)

# General
TZ=America/New_York    # Your timezone
SERVER_IP=192.168.1.100  # Server IP address

# Paths
USERDIR=/home/username/homelab
MEDIADIR=/mnt/media
DOWNLOADDIR=/mnt/downloads
PROJECTDIR=/home/username/projects

Network Setup

# Create all networks at once
docker network create homelab-network
docker network create media-network
docker network create monitoring-network
docker network create database-network

Service URLs

After starting services, access them at:

Infrastructure:
http://SERVER_IP:81        - Nginx Proxy Manager
http://SERVER_IP:8080      - Pi-hole
http://SERVER_IP:9000      - Portainer

Media:
http://SERVER_IP:32400/web - Plex
http://SERVER_IP:8096      - Jellyfin
http://SERVER_IP:8989      - Sonarr
http://SERVER_IP:7878      - Radarr
http://SERVER_IP:9696      - Prowlarr
http://SERVER_IP:8081      - qBittorrent

Monitoring:
http://SERVER_IP:9090      - Prometheus
http://SERVER_IP:3000      - Grafana
http://SERVER_IP:3001      - Uptime Kuma

Development:
http://SERVER_IP:8443      - Code Server
http://SERVER_IP:8929      - GitLab
http://SERVER_IP:5050      - pgAdmin
http://SERVER_IP:8888      - Jupyter Lab
http://SERVER_IP:1880      - Node-RED

Troubleshooting Quick Fixes

Service won't start

# 1. Check logs
docker compose -f docker-compose/file.yml logs service-name

# 2. Validate configuration
docker compose -f docker-compose/file.yml config

# 3. Check what's using the port
sudo netstat -tlnp | grep PORT_NUMBER

Permission errors

# Check your IDs
id -u  # Should match PUID in .env
id -g  # Should match PGID in .env

# Fix ownership
sudo chown -R 1000:1000 ./config/service-name

Network issues

# Check network exists
docker network inspect homelab-network

# Recreate network
docker network rm homelab-network
docker network create homelab-network
docker compose -f docker-compose/file.yml up -d

Container keeps restarting

# Watch logs in real-time
docker compose -f docker-compose/file.yml logs -f service-name

# Check resource usage
docker stats container-name

# Inspect container
docker inspect container-name | less

Testing GPU Support (NVIDIA)

# Test if nvidia-container-toolkit works
docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi

# If successful, you should see your GPU info

Backup Commands

# Backup all config directories
tar czf backup-config-$(date +%Y%m%d).tar.gz config/

# Backup a specific volume
docker run --rm \
  -v volume-name:/data \
  -v $(pwd)/backups:/backup \
  busybox tar czf /backup/volume-name-$(date +%Y%m%d).tar.gz /data

# Backup .env file (store securely!)
cp .env .env.backup

Health Checks

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

# Check specific service health
docker inspect --format='{{json .State.Health}}' container-name | jq

Resource Limits

Add to service definition if needed:

deploy:
  resources:
    limits:
      cpus: '2'
      memory: 4G
    reservations:
      cpus: '0.5'
      memory: 1G

Common Patterns

Add a new service

1. Choose the appropriate compose file
2. Add service definition following existing patterns
3. Use environment variables from .env
4. Connect to homelab-network
5. Pin specific image version
6. Add labels for organization
7. Test: docker compose -f file.yml config
8. Deploy: docker compose -f file.yml up -d service-name

Update a service version

1. Edit compose file with new version
2. Pull new image: docker compose -f file.yml pull service-name
3. Recreate: docker compose -f file.yml up -d service-name
4. Check logs: docker compose -f file.yml logs -f service-name

Remove a service

1. Stop service: docker compose -f file.yml stop service-name
2. Remove service: docker compose -f file.yml rm service-name
3. Remove from compose file
4. Optional: Remove volumes: docker volume rm volume-name
5. Optional: Remove config: rm -rf config/service-name

AI Assistant Usage in VS Code

Ask for help:

• "Add Jellyfin to my media stack"
• "Configure GPU for Plex"
• "Create monitoring dashboard setup"
• "Help me troubleshoot port conflicts"
• "Generate a compose file for Home Assistant"

The AI will:

• Check existing services
• Follow naming conventions
• Avoid port conflicts
• Use proper network configuration
• Include health checks
• Add documentation comments
• Suggest related services

Quick Deployment

Minimal setup

# 1. Clone and configure
# Note: Replace 'kelinfoxy' with your username if you forked this repository
git clone https://github.com/kelinfoxy/AI-Homelab.git
cd AI-Homelab
cp .env.example .env
nano .env  # Edit values

# 2. Create network
docker network create homelab-network

# 3. Start Portainer (for container management)
docker compose -f docker-compose/infrastructure.yml up -d portainer

# 4. Access at http://SERVER_IP:9000

Full stack deployment

# After minimal setup, deploy everything:
docker compose -f docker-compose/infrastructure.yml up -d
docker compose -f docker-compose/media.yml up -d
docker compose -f docker-compose/monitoring.yml up -d
docker compose -f docker-compose/development.yml up -d

Maintenance Schedule

Daily (automated)

• Watchtower checks for updates at 4 AM

Weekly

• Review logs for each stack:

  docker compose -f docker-compose/infrastructure.yml logs --tail=100
  docker compose -f docker-compose/media.yml logs --tail=100
  docker compose -f docker-compose/monitoring.yml logs --tail=100
  

• Check disk space: docker system df

Monthly

• Update pinned versions in compose files
• Backup volumes and configs
• Review security updates

Quarterly

• Full system audit
• Documentation review
• Performance optimization