379 lines
9.3 KiB
Markdown
379 lines
9.3 KiB
Markdown
# 🚀 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
|
|
```
|
|
|
|
## 📚 Learning Resources
|
|
|
|
### 📖 **Understanding Docker**
|
|
- **Images**: Pre-built software packages
|
|
- **Containers**: Running instances of images
|
|
- **Volumes**: Persistent data storage
|
|
- **Networks**: How containers communicate
|
|
|
|
### 🔗 **Useful Commands**
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
# 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](../infrastructure/tailscale-setup-guide.md)**
|
|
|
|
### 🔧 **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](../infrastructure/port-forwarding-guide.md)**
|
|
|
|
### 🛡️ **Security Recommendation**
|
|
**Use Tailscale for secure, easy access without exposing services to the internet!**
|
|
|
|
## 📋 Next Reading
|
|
|
|
- **[🌟 Tailscale Setup Guide](../infrastructure/tailscale-setup-guide.md)**: **RECOMMENDED** - Secure external access
|
|
- **[Architecture Overview](architecture.md)**: Understand how everything fits together
|
|
- **[Service Categories](../services/categories.md)**: Explore what services are available
|
|
- **[Deployment Guide](../admin/deployment.md)**: Learn advanced deployment patterns
|
|
- **[Common Issues](../troubleshooting/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!* |