homelab-optimized/docs/getting-started/quick-start.md

🚀 Quick Start Guide

🟢 Beginner-Friendly

Get up and running with your first homelab service in under 30 minutes! This guide will walk you through deploying a simple service using the established patterns from this homelab.

🎯 What We'll Build

We'll deploy Uptime Kuma - a simple, beginner-friendly monitoring tool that will:

• Monitor your other services
• Send you alerts when things go down
• Provide a beautiful dashboard
• Teach you the basic deployment patterns

📋 Prerequisites

✅ What You Need

• A computer running Linux (Ubuntu, Debian, or similar)
• Docker and Docker Compose installed
• Basic command line knowledge
• 30 minutes of time

🔧 Install Docker (if needed)

# Update system
sudo apt update && sudo apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add your user to docker group
sudo usermod -aG docker $USER

# Install Docker Compose
sudo apt install docker-compose -y

# Verify installation
docker --version
docker-compose --version

📁 Step 1: Create Project Structure

# Create project directory
mkdir -p ~/homelab/monitoring
cd ~/homelab/monitoring

# Create the directory structure
mkdir -p uptime-kuma/data

📝 Step 2: Create Docker Compose File

Create the main configuration file:

cat > uptime-kuma/docker-compose.yml << 'EOF'
version: '3.9'

services:
  uptime-kuma:
    image: louislam/uptime-kuma:latest
    container_name: Uptime-Kuma
    hostname: uptime-kuma
    
    # Security settings
    security_opt:
      - no-new-privileges:true
    user: 1000:1000  # Adjust for your system
    
    # Health check
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3001/api/status-page/heartbeat/default"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s
    
    # Restart policy
    restart: on-failure:5
    
    # Resource limits
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '0.5'
    
    # Port mapping
    ports:
      - "3001:3001"
    
    # Data persistence
    volumes:
      - ./data:/app/data:rw
      - /etc/localtime:/etc/localtime:ro
    
    # Environment variables
    environment:
      - TZ=America/Los_Angeles  # Change to your timezone
    
    # Custom network
    networks:
      - monitoring-network

networks:
  monitoring-network:
    name: monitoring-network
    ipam:
      config:
        - subnet: 192.168.100.0/24
EOF

🔧 Step 3: Configure Environment

Create an environment file for easy customization:

cat > uptime-kuma/.env << 'EOF'
# Timezone (change to your location)
TZ=America/Los_Angeles

# User ID and Group ID (run 'id' command to find yours)
PUID=1000
PGID=1000

# Port (change if 3001 is already in use)
PORT=3001
EOF

🚀 Step 4: Deploy the Service

# Navigate to the service directory
cd uptime-kuma

# Start the service
docker-compose up -d

# Check if it's running
docker-compose ps

# View logs
docker-compose logs -f

You should see output like:

uptime-kuma_1  | Welcome to Uptime Kuma
uptime-kuma_1  | Server is running on port 3001

🌐 Step 5: Access Your Service

1. Open your web browser
2. Navigate to: http://your-server-ip:3001
3. Create admin account on first visit
4. Start monitoring services!

🎯 Step 6: Add Your First Monitor

1. Click "Add New Monitor"
2. Configure a basic HTTP monitor:
   • Monitor Type: HTTP(s)
   • Friendly Name: Google
   • URL: https://google.com
   • Heartbeat Interval: 60 seconds
3. Click "Save"

Congratulations! You've deployed your first homelab service! 🎉

🔍 Understanding What We Built

📦 Docker Compose Structure

# This tells Docker what version of compose syntax we're using
version: '3.9'

# Services section defines our containers
services:
  uptime-kuma:                    # Service name
    image: louislam/uptime-kuma   # Docker image to use
    container_name: Uptime-Kuma   # Custom container name
    ports:                        # Port mapping (host:container)
      - "3001:3001"
    volumes:                      # Data persistence
      - ./data:/app/data:rw       # Maps local ./data to container /app/data
    environment:                  # Environment variables
      - TZ=America/Los_Angeles

🔐 Security Features

• no-new-privileges: Prevents privilege escalation
• User mapping: Runs as non-root user
• Resource limits: Prevents resource exhaustion
• Health checks: Monitors service health

📊 Monitoring Features

• Health checks: Docker monitors the container
• Restart policy: Automatically restarts on failure
• Logging: All output captured by Docker

🎓 Next Steps - Expand Your Homelab

🟢 Beginner Services (Try Next)

1. Pi-hole - Block ads network-wide

   # Copy the uptime-kuma pattern and adapt for Pi-hole
   mkdir ~/homelab/pihole
   # Use the Pi-hole configuration from Atlantis/pihole.yml
   

2. Portainer - Manage Docker containers with a web UI

   mkdir ~/homelab/portainer
   # Adapt the pattern for Portainer
   

3. Nginx Proxy Manager - Manage reverse proxy with SSL

   mkdir ~/homelab/proxy
   # Use the pattern from Atlantis/nginxproxymanager/
   

🟡 Intermediate Services (When Ready)

1. Plex or Jellyfin - Media streaming
2. Vaultwarden - Password manager
3. Grafana + Prometheus - Advanced monitoring

🔴 Advanced Services (For Later)

1. GitLab - Complete DevOps platform
2. Home Assistant - Smart home automation
3. Matrix Synapse - Decentralized chat

🛠️ Common Customizations

🔧 Change the Port

If port 3001 is already in use:

ports:
  - "3002:3001"  # Use port 3002 instead

🔧 Different Data Location

To store data elsewhere:

volumes:
  - /home/user/uptime-data:/app/data:rw

🔧 Add Resource Limits

For a more powerful server:

deploy:
  resources:
    limits:
      memory: 1G
      cpus: '1.0'

🚨 Troubleshooting

❌ Service Won't Start

# Check logs for errors
docker-compose logs

# Check if port is already in use
sudo netstat -tulpn | grep :3001

# Check file permissions
ls -la data/

❌ Can't Access Web Interface

# Check if container is running
docker ps

# Test internal connectivity
docker exec Uptime-Kuma curl http://localhost:3001

# Check firewall
sudo ufw status
sudo ufw allow 3001

❌ Data Not Persisting

# Check volume mount
docker inspect Uptime-Kuma | grep -A 10 Mounts

# Fix permissions
sudo chown -R 1000:1000 ./data

📚 Learning Resources

📖 Understanding Docker

• Images: Pre-built software packages
• Containers: Running instances of images
• Volumes: Persistent data storage
• Networks: How containers communicate

🔗 Useful Commands

# View running containers
docker ps

# View all containers (including stopped)
docker ps -a

# View container logs
docker logs container-name

# Execute command in container
docker exec -it container-name /bin/bash

# Stop and remove everything
docker-compose down

# Update and restart
docker-compose pull && docker-compose up -d

🎯 What You've Learned

✅ Docker Compose basics
✅ Service deployment patterns
✅ Data persistence with volumes
✅ Network configuration
✅ Security best practices
✅ Health monitoring
✅ Troubleshooting basics

🌐 External Access (Optional)

Once you have services running locally, you might want to access them from outside your home network:

🌟 Option 1: Tailscale (Recommended)

Zero-config mesh VPN with split-brain DNS

# Install Tailscale on your server and devices
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

# Access services using local hostnames from anywhere:
# http://your-server.vish.local:3001

📖 Complete Tailscale Setup Guide

🔧 Option 2: Port Forwarding (Traditional)

Forward specific ports on your router

• Forward port 3001 to your server's IP
• Access via: http://your-external-ip:3001
• ⚠️ Security risk: Exposes services directly to internet

📖 Port Forwarding Guide

🛡️ Security Recommendation

Use Tailscale for secure, easy access without exposing services to the internet!

📋 Next Reading

• 🌟 Tailscale Setup Guide: RECOMMENDED - Secure external access
• Architecture Overview: Understand how everything fits together
• Service Categories: Explore what services are available
• Deployment Guide: Learn advanced deployment patterns
• Common Issues: Troubleshoot problems

---

🎉 Congratulations! You've successfully deployed your first homelab service using the same patterns used across all 176 services in this infrastructure. You're now ready to explore more complex services and build your own homelab empire!

Remember: Every expert was once a beginner. Start small, learn continuously, and don't be afraid to break things - that's how you learn!