Sanitized mirror from private repository - 2026-04-06 02:25:47 UTC

2026-04-06 02:25:48 +00:00
commit fad8c41112
1407 changed files with 358727 additions and 0 deletions
--- a/docs/getting-started/QUICK_START.md
+++ b/docs/getting-started/QUICK_START.md
@@ -0,0 +1,504 @@
+# 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
+
+```bash
+# 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](http://atlantis.vish.local:9000)
+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
+```yaml
+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
+```bash
+# 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
+```bash
+# 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
+```bash
+# 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
+```bash
+# 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
+```bash
+# 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
+```yaml
+# 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
+```yaml
+# 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
+```bash
+# 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
+```bash
+# Check what's using port 3001
+netstat -tulpn | grep :3001
+
+# Solution: Change external port
+ports:
+  - "3002:3001"  # Use port 3002 instead
+```
+
+### Permission Denied
+```bash
+# 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
+```bash
+# 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
+```bash
+# 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](../services/individual/grafana.md)** - Advanced monitoring dashboards
+2. **[Nextcloud](../services/individual/nextcloud.md)** - Personal cloud storage
+3. **[Plex](../services/individual/plex.md)** - Media server
+4. **[Portainer](../services/individual/portainer.md)** - Container management
+
+### Learn Advanced Concepts
+1. **[GitOps Deployment](../GITOPS_DEPLOYMENT_GUIDE.md)** - Infrastructure as code
+2. **[Service Categories](20-Service-Categories.md)** - Explore all available services
+3. **[Architecture Overview](03-Architecture-Overview.md)** - Understand the infrastructure
+4. **[Security Guidelines](../security/README.md)** - Harden your deployment
+
+## Deployment Templates
+
+### Basic Service Template
+```yaml
+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
+```yaml
+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
+```yaml
+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
+```bash
+#!/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
+```bash
+#!/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](../README.md)** - Complete homelab documentation
+- **[Service Categories](20-Service-Categories.md)** - All available services
+- **[Troubleshooting](40-Common-Issues.md)** - Common issues and solutions
+
+### Community
+- **[Homelab Subreddit](https://reddit.com/r/homelab)** - Community discussions
+- **[Self-Hosted](https://reddit.com/r/selfhosted)** - Self-hosting community
+- **[Docker Community](https://forums.docker.com/)** - Docker support
+
+### Tools
+- **[Portainer](http://atlantis.vish.local:9000)** - Container management
+- **[Grafana](http://atlantis.vish.local:3000)** - Monitoring dashboards
+- **[Uptime Kuma](http://raspberry-pi.vish.local:3001)** - 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.*