homelab-optimized/docs/getting-started/QUICK_START.md

Quick Start Guide

Overview

This guide will help you deploy your first service in the homelab environment within 15 minutes. We'll use Uptime Kuma as an example service since it's lightweight, useful, and demonstrates the core deployment workflow.

Prerequisites Check

Before starting, ensure you have:

• SSH access to a homelab server
• Docker and Docker Compose installed
• Git repository access
• Basic understanding of Docker concepts

# Quick verification
ssh homelab@server-ip
docker --version
docker-compose --version
git --version

Step 1: Choose Your Deployment Method

Option A: Portainer (Recommended for Beginners)

• Web-based interface
• Visual stack management
• Built-in monitoring
• Easy rollbacks

Option B: Command Line (Recommended for Advanced Users)

• Direct Docker Compose
• Faster deployment
• Scriptable automation
• Full control

Step 2: Deploy Uptime Kuma (Portainer Method)

Access Portainer

1. Navigate to Portainer
2. Login with your credentials
3. Select the local endpoint

Create New Stack

1. Go to Stacks → Add Stack
2. Name: uptime-kuma-quickstart
3. Choose Web Editor

Paste Configuration

version: '3.8'

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma-quickstart
    restart: unless-stopped
    
    ports:
      - "3001:3001"
    
    volumes:
      - uptime-kuma-data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock:ro
    
    environment:
      - PUID=1000
      - PGID=1000
    
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.uptime-kuma.rule=Host(`uptime.vish.local`)"
      - "traefik.http.services.uptime-kuma.loadbalancer.server.port=3001"

volumes:
  uptime-kuma-data:
    driver: local

Deploy Stack

1. Click Deploy the Stack
2. Wait for deployment to complete
3. Check Containers tab for running status

Access Service

• Direct: http://server-ip:3001
• Domain: http://uptime.vish.local (if DNS configured)

Step 3: Deploy Uptime Kuma (Command Line Method)

Clone Repository

# Clone homelab repository
git clone https://git.vish.gg/Vish/homelab.git
cd homelab

# Navigate to appropriate server directory
cd hosts/raspberry-pi-5-vish  # or your target server

Create Service File

# Create uptime-kuma.yml
cat > uptime-kuma-quickstart.yml << 'EOF'
version: '3.8'

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1
    container_name: uptime-kuma-quickstart
    restart: unless-stopped
    
    ports:
      - "3001:3001"
    
    volumes:
      - uptime-kuma-data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock:ro
    
    environment:
      - PUID=1000
      - PGID=1000

volumes:
  uptime-kuma-data:
    driver: local
EOF

Deploy Service

# Deploy with Docker Compose
docker-compose -f uptime-kuma-quickstart.yml up -d

# Check status
docker-compose -f uptime-kuma-quickstart.yml ps

# View logs
docker-compose -f uptime-kuma-quickstart.yml logs -f

Step 4: Initial Configuration

First-Time Setup

1. Access Uptime Kuma at http://server-ip:3001
2. Create admin account:
   • Username: admin
   • Password: "REDACTED_PASSWORD"
   • Email: admin@vish.local

Add Your First Monitor

1. Click Add New Monitor

2. Configure basic HTTP monitor:

   • Monitor Type: HTTP(s)
   • Friendly Name: Homelab Wiki
   • URL: https://git.vish.gg/Vish/homelab/wiki
   • Heartbeat Interval: 60 seconds
   • Max Retries: 3

3. Click Save

Configure Notifications (Optional)

1. Go to Settings → Notifications
2. Add notification method:
   • NTFY: http://homelab-vm.vish.local:80/homelab-alerts
   • Email: Configure SMTP settings
   • Discord: Add webhook URL

Step 5: Verification & Testing

Health Check

# Check container health
docker ps | grep uptime-kuma

# Test HTTP endpoint
curl -I http://localhost:3001

# Check logs for errors
docker logs uptime-kuma-quickstart

Monitor Verification

1. Wait 2-3 minutes for first heartbeat
2. Verify monitor shows UP status
3. Check response time graphs
4. Test notification (if configured)

Resource Usage

# Check resource consumption
docker stats uptime-kuma-quickstart

# Expected usage:
# CPU: < 5%
# Memory: < 100MB
# Network: Minimal

Step 6: Integration with Homelab

Add to Monitoring Stack

# Add to existing monitoring docker-compose.yml
  uptime-kuma:
    # ... existing configuration ...
    
    networks:
      - monitoring
    
    labels:
      - "monitoring.enable=true"
      - "backup.enable=true"

networks:
  monitoring:
    external: true

Configure Reverse Proxy

# Nginx Proxy Manager configuration
# Host: uptime.vish.local
# Forward Hostname/IP: uptime-kuma-quickstart
# Forward Port: 3001
# SSL: Let's Encrypt or self-signed

Add to Backup Schedule

# Add volume to backup script
echo "uptime-kuma-data" >> /etc/backup/volumes.list

# Test backup
./scripts/backup-volumes.sh uptime-kuma-data

Common Quick Start Issues

Port Already in Use

# Check what's using port 3001
netstat -tulpn | grep :3001

# Solution: Change external port
ports:
  - "3002:3001"  # Use port 3002 instead

Permission Denied

# Fix volume permissions
sudo chown -R 1000:1000 /var/lib/docker/volumes/uptime-kuma-data

# Or use named volume (recommended)
volumes:
  uptime-kuma-data:
    driver: local

Container Won't Start

# Check Docker daemon
systemctl status docker

# Check logs
docker logs uptime-kuma-quickstart

# Restart container
docker-compose restart uptime-kuma

Can't Access Web Interface

# Check firewall
sudo ufw status
sudo ufw allow 3001/tcp

# Check container port binding
docker port uptime-kuma-quickstart

# Test local connectivity
curl http://localhost:3001

Next Steps

Expand Monitoring

1. Add More Monitors:

   • Internal services (Plex, Nextcloud, etc.)
   • External websites
   • API endpoints
   • Database connections

2. Configure Status Pages:

   • Public status page for external services
   • Internal dashboard for homelab services
   • Custom branding and themes

3. Set Up Alerting:

   • Email notifications for critical services
   • NTFY push notifications
   • Discord/Slack integration
   • Escalation policies

Deploy More Services

1. Grafana - Advanced monitoring dashboards
2. Nextcloud - Personal cloud storage
3. Plex - Media server
4. Portainer - Container management

Learn Advanced Concepts

1. GitOps Deployment - Infrastructure as code
2. Service Categories - Explore all available services
3. Architecture Overview - Understand the infrastructure
4. Security Guidelines - Harden your deployment

Deployment Templates

Basic Service Template

version: '3.8'

services:
  service-name:
    image: organization/service:latest
    container_name: service-name
    restart: unless-stopped
    
    ports:
      - "8080:8080"
    
    volumes:
      - service-data:/data
      - service-config:/config
    
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York

volumes:
  service-data:
  service-config:

Service with Database

version: '3.8'

services:
  app:
    image: app:latest
    container_name: app
    restart: unless-stopped
    depends_on:
      - db
    
    ports:
      - "8080:8080"
    
    environment:
      - DB_HOST=db
      - DB_USER=appuser
      - DB_PASS="REDACTED_PASSWORD"
      - DB_NAME=appdb
  
  db:
    image: postgres:15
    container_name: app-db
    restart: unless-stopped
    
    environment:
      - POSTGRES_USER=appuser
      - POSTGRES_PASSWORD="REDACTED_PASSWORD"
      - POSTGRES_DB=appdb
    
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

Service with Reverse Proxy

version: '3.8'

services:
  app:
    image: app:latest
    container_name: app
    restart: unless-stopped
    
    expose:
      - "8080"
    
    networks:
      - proxy
    
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.app.rule=Host(`app.vish.local`)"
      - "traefik.http.services.app.loadbalancer.server.port=8080"

networks:
  proxy:
    external: true

Automation Scripts

Quick Deploy Script

#!/bin/bash
# quick-deploy.sh

SERVICE_NAME=$1
SERVER=$2

if [ -z "$SERVICE_NAME" ] || [ -z "$SERVER" ]; then
    echo "Usage: $0 <service-name> <server>"
    echo "Example: $0 uptime-kuma raspberry-pi"
    exit 1
fi

echo "Deploying $SERVICE_NAME on $SERVER..."

# Navigate to server directory
cd "hosts/$SERVER" || exit 1

# Check if service file exists
if [ ! -f "$SERVICE_NAME.yml" ]; then
    echo "Error: $SERVICE_NAME.yml not found in hosts/$SERVER/"
    exit 1
fi

# Deploy service
docker-compose -f "$SERVICE_NAME.yml" up -d

# Wait for service to start
sleep 10

# Check status
docker-compose -f "$SERVICE_NAME.yml" ps

echo "Deployment complete!"
echo "Check logs with: docker-compose -f hosts/$SERVER/$SERVICE_NAME.yml logs -f"

Health Check Script

#!/bin/bash
# health-check.sh

SERVICE_NAME=$1
EXPECTED_PORT=$2

if [ -z "$SERVICE_NAME" ] || [ -z "$EXPECTED_PORT" ]; then
    echo "Usage: $0 <service-name> <port>"
    exit 1
fi

echo "Checking health of $SERVICE_NAME on port $EXPECTED_PORT..."

# Check container status
if docker ps | grep -q "$SERVICE_NAME"; then
    echo "✅ Container is running"
else
    echo "❌ Container is not running"
    exit 1
fi

# Check port accessibility
if curl -f "http://localhost:$EXPECTED_PORT" > /dev/null 2>&1; then
    echo "✅ Service is responding"
else
    echo "❌ Service is not responding"
    exit 1
fi

echo "✅ Health check passed!"

Support & Resources

Documentation

• Full Documentation - Complete homelab documentation
• Service Categories - All available services
• Troubleshooting - Common issues and solutions

Community

• Homelab Subreddit - Community discussions
• Self-Hosted - Self-hosting community
• Docker Community - Docker support

Tools

• Portainer - Container management
• Grafana - Monitoring dashboards
• Uptime Kuma - Service monitoring

---

This quick start guide gets you up and running with your first service deployment. Once comfortable with the basics, explore the comprehensive documentation for advanced configurations and additional services.