# 🚀 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)
```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
```

## 📁 Step 1: Create Project Structure

```bash
# 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:

```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
```

## 🔧 Step 3: Configure Environment

Create an environment file for easy customization:

```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
```

## 🚀 Step 4: Deploy the Service

```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
```

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
```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
```

### 🔐 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
   ```bash
   # 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
   ```bash
   mkdir ~/homelab/portainer
   # Adapt the pattern for Portainer
   ```

3. **Nginx Proxy Manager** - Manage reverse proxy with SSL
   ```bash
   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:
```yaml
ports:
  - "3002:3001"  # Use port 3002 instead
```

### 🔧 Different Data Location
To store data elsewhere:
```yaml
volumes:
  - /home/user/uptime-data:/app/data:rw
```

### 🔧 Add Resource Limits
For a more powerful server:
```yaml
deploy:
  resources:
    limits:
      memory: 1G
      cpus: '1.0'
```

## 🚨 Troubleshooting

### ❌ Service Won't Start
```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/
```

### ❌ Can't Access Web Interface
```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
```

### ❌ Data Not Persisting
```bash
# Check volume mount
docker inspect Uptime-Kuma | grep -A 10 Mounts

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

## 🎯 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

- **[03-Architecture-Overview](03-Architecture-Overview.md)**: Understand how everything fits together
- **[20-Service-Categories](20-Service-Categories.md)**: Explore what services are available
- **[30-Deployment-Guide](30-Deployment-Guide.md)**: Learn advanced deployment patterns
- **[40-Common-Issues](40-Common-Issues.md)**: 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!*

## 🔗 Related Documents

- **[00-Homelab-Documentation-Index](00-Homelab-Documentation-Index.md)**: Main documentation index
- **[01-What-is-a-Homelab](01-What-is-a-Homelab.md)**: Understanding homelabs
- **[04-Prerequisites](04-Prerequisites.md)**: What you need before starting
- **[22-Popular-Services](22-Popular-Services.md)**: Essential services to deploy next