homelab-optimized/archive/dokuwiki/getting-started-quick-start.txt

====== 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) ====
<code bash>
# 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
</code>

===== Step 1: Create Project Structure =====

<code bash>
# Create project directory
mkdir -p ~/homelab/monitoring
cd ~/homelab/monitoring

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

===== Step 2: Create Docker Compose File =====

Create the main configuration file:

<code bash>
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
</code>

===== Step 3: Configure Environment =====

Create an environment file for easy customization:

<code bash>
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
</code>

===== Step 4: Deploy the Service =====

<code bash>
# 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
</code>

You should see output like:
<code>
uptime-kuma_1  | Welcome to Uptime Kuma
uptime-kuma_1  | Server is running on port 3001
</code>

===== Step 5: Access Your Service =====

  - **Open your web browser**
  - **Navigate to**: ''http://your-server-ip:3001''
  - **Create admin account** on first visit
  - **Start monitoring services!**

===== Step 6: Add Your First Monitor =====

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

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

===== Understanding What We Built =====

==== Docker Compose Structure ====
<code yaml>
# 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
</code>

==== 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) ====
  - **Pi-hole** - Block ads network-wide
    <code bash>
    # Copy the uptime-kuma pattern and adapt for Pi-hole
    mkdir ~/homelab/pihole
    # Use the Pi-hole configuration from Atlantis/pihole.yml
    </code>

  - **Portainer** - Manage Docker containers with a web UI
    <code bash>
    mkdir ~/homelab/portainer
    # Adapt the pattern for Portainer
    </code>

  - **Nginx Proxy Manager** - Manage reverse proxy with SSL
    <code bash>
    mkdir ~/homelab/proxy
    # Use the pattern from Atlantis/nginxproxymanager/
    </code>

==== 🟡 Intermediate Services (When Ready) ====
  - **Plex or Jellyfin** - Media streaming
  - **Vaultwarden** - Password manager
  - **Grafana + Prometheus** - Advanced monitoring

==== 🔴 Advanced Services (For Later) ====
  - **GitLab** - Complete DevOps platform
  - **Home Assistant** - Smart home automation
  - **Matrix Synapse** - Decentralized chat

===== Common Customizations =====

==== Change the Port ====
If port 3001 is already in use:
<code yaml>
ports:
  - "3002:3001"  # Use port 3002 instead
</code>

==== Different Data Location ====
To store data elsewhere:
<code yaml>
volumes:
  - /home/user/uptime-data:/app/data:rw
</code>

==== Add Resource Limits ====
For a more powerful server:
<code yaml>
deploy:
  resources:
    limits:
      memory: 1G
      cpus: '1.0'
</code>

===== Troubleshooting =====

==== Service Won't Start ====
<code bash>
# 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/
</code>

==== Can't Access Web Interface ====
<code bash>
# 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
</code>

==== Data Not Persisting ====
<code bash>
# Check volume mount
docker inspect Uptime-Kuma | grep -A 10 Mounts

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

===== What You've Learned =====

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

===== Next Reading =====

  * [[getting-started:architecture|Architecture Overview]]: Understand how everything fits together
  * [[services:categories|Service Categories]]: Explore what services are available
  * [[admin:deployment|Deployment Guide]]: Learn advanced deployment patterns
  * [[troubleshooting:common-issues|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!//