Sanitized mirror from private repository - 2026-03-21 11:39:16 UTC

docs/troubleshooting/beginner-troubleshooting.md

@@ -0,0 +1,577 @@
+# 🔧 Beginner's Homelab Troubleshooting Guide
+
+**🆘 When Things Go Wrong - Don't Panic!**
+
+This guide helps beginners diagnose and fix common homelab issues. Remember: every expert was once a beginner, and troubleshooting is a skill that improves with practice.
+
+## 🚨 Emergency Quick Fixes
+
+### **"I Can't Access Anything!"**
+```bash
+# Quick diagnostic steps (5 minutes):
+1. Check if your computer has internet access
+   - Try browsing to google.com
+   - If no internet: Router/ISP issue
+
+2. Check if you can ping your NAS
+   - Windows: ping 192.168.1.100
+   - Mac/Linux: ping 192.168.1.100
+   - If no response: Network issue
+
+3. Check NAS power and status lights
+   - Power light: Should be solid blue/green
+   - Network light: Should be solid or blinking
+   - Drive lights: Should not be red
+
+4. Try accessing NAS web interface
+   - http://192.168.1.100:5000 (or your NAS IP)
+   - If accessible: Service-specific issue
+   - If not accessible: NAS system issue
+```
+
+### **"My Services Are Down!"**
+```bash
+# Service recovery steps:
+1. Check Docker container status
+   - Docker → Container → Check running status
+   - If stopped: Click Start button
+
+2. Check system resources
+   - Resource Monitor → CPU, RAM, Storage
+   - If high usage: Restart problematic containers
+
+3. Check logs
+   - Docker → Container → Details → Log
+   - Look for error messages in red
+
+4. Restart container if needed
+   - Stop container → Wait 30 seconds → Start
+```
+
+---
+
+## 🔍 Systematic Troubleshooting
+
+### **Step 1: Identify the Problem**
+
+#### **Network Issues**
+```bash
+Symptoms:
+- Can't access NAS web interface
+- Services timeout or don't load
+- File transfers are very slow
+- Can't connect from other devices
+
+Quick tests:
+- ping [nas-ip]
+- nslookup [nas-hostname]
+- speedtest from NAS (if available)
+```
+
+#### **Storage Issues**
+```bash
+Symptoms:
+- "Disk full" errors
+- Very slow file operations
+- RAID degraded warnings
+- SMART errors in logs
+
+Quick checks:
+- Storage Manager → Check available space
+- Storage Manager → HDD/SSD → Check drive health
+- Control Panel → Log Center → Check for errors
+```
+
+#### **Performance Issues**
+```bash
+Symptoms:
+- Slow web interface
+- Containers crashing
+- High CPU/RAM usage
+- System freezes or reboots
+
+Quick checks:
+- Resource Monitor → Check CPU/RAM usage
+- Task Manager → Check running processes
+- Docker → Check container resource usage
+```
+
+#### **Service-Specific Issues**
+```bash
+Symptoms:
+- One service not working while others work fine
+- Service accessible but not functioning correctly
+- Authentication failures
+- Database connection errors
+
+Quick checks:
+- Check service logs
+- Verify service configuration
+- Test service dependencies
+- Check port conflicts
+```
+
+### **Step 2: Gather Information**
+
+#### **System Information Checklist**
+```bash
+Before asking for help, collect this information:
+
+☐ NAS model and DSM version
+☐ Exact error message (screenshot if possible)
+☐ What you were doing when the problem occurred
+☐ When the problem started
+☐ What you've already tried
+☐ System logs (if available)
+☐ Network configuration details
+☐ Recent changes to the system
+```
+
+#### **How to Find System Information**
+```bash
+# DSM Version:
+Control Panel → Info Center → General
+
+# System Logs:
+Control Panel → Log Center → System
+
+# Network Configuration:
+Control Panel → Network → Network Interface
+
+# Storage Status:
+Storage Manager → Storage → Overview
+
+# Running Services:
+Package Center → Installed
+
+# Docker Status:
+Docker → Container (if Docker is installed)
+```
+
+---
+
+## 🛠️ Common Problems and Solutions
+
+### **Problem: Can't Access NAS Web Interface**
+
+#### **Possible Causes and Solutions**
+
+**1. Network Configuration Issues**
+```bash
+Symptoms: Browser shows "This site can't be reached"
+
+Diagnosis:
+- ping [nas-ip] from your computer
+- Check if NAS IP changed (DHCP vs static)
+
+Solutions:
+- Set static IP on NAS
+- Check router DHCP reservations
+- Use Synology Assistant to find NAS
+- Try http://find.synology.com
+```
+
+**2. Firewall Blocking Access**
+```bash
+Symptoms: Connection timeout, no response
+
+Diagnosis:
+- Try from different device on same network
+- Check Windows/Mac firewall settings
+
+Solutions:
+- Temporarily disable computer firewall
+- Add exception for NAS IP range
+- Check router firewall settings
+```
+
+**3. Wrong Port or Protocol**
+```bash
+Symptoms: "Connection refused" or wrong page loads
+
+Diagnosis:
+- Check if using HTTP vs HTTPS
+- Verify port number (default 5000/5001)
+
+Solutions:
+- Try http://[nas-ip]:5000
+- Try https://[nas-ip]:5001
+- Check Control Panel → Network → DSM Settings
+```
+
+### **Problem: Docker Containers Won't Start**
+
+#### **Possible Causes and Solutions**
+
+**1. Insufficient Resources**
+```bash
+Symptoms: Container starts then immediately stops
+
+Diagnosis:
+- Resource Monitor → Check RAM usage
+- Docker → Container → Details → Log
+
+Solutions:
+- Stop unnecessary containers
+- Increase RAM allocation
+- Restart NAS to free memory
+```
+
+**2. Port Conflicts**
+```bash
+Symptoms: "Port already in use" error
+
+Diagnosis:
+- Check which service is using the port
+- Network → Port Forwarding
+
+Solutions:
+- Change container port mapping
+- Stop conflicting service
+- Use different external port
+```
+
+**3. Volume Mount Issues**
+```bash
+Symptoms: Container starts but data is missing
+
+Diagnosis:
+- Check if volume paths exist
+- Verify permissions on folders
+
+Solutions:
+- Create missing folders
+- Fix folder permissions
+- Use absolute paths in volume mounts
+```
+
+### **Problem: Slow Performance**
+
+#### **Possible Causes and Solutions**
+
+**1. High CPU/RAM Usage**
+```bash
+Symptoms: Slow web interface, timeouts
+
+Diagnosis:
+- Resource Monitor → Check usage graphs
+- Task Manager → Identify heavy processes
+
+Solutions:
+- Restart resource-heavy containers
+- Reduce concurrent operations
+- Upgrade RAM if consistently high
+- Schedule intensive tasks for off-hours
+```
+
+**2. Network Bottlenecks**
+```bash
+Symptoms: Slow file transfers, streaming issues
+
+Diagnosis:
+- Test network speed from different devices
+- Check for WiFi interference
+
+Solutions:
+- Use wired connection for large transfers
+- Upgrade to Gigabit network
+- Check for network congestion
+- Consider 10GbE for heavy usage
+```
+
+**3. Storage Issues**
+```bash
+Symptoms: Slow file operations, high disk usage
+
+Diagnosis:
+- Storage Manager → Check disk health
+- Resource Monitor → Check disk I/O
+
+Solutions:
+- Run disk defragmentation (if supported)
+- Check for failing drives
+- Add SSD cache
+- Reduce concurrent disk operations
+```
+
+### **Problem: Services Keep Crashing**
+
+#### **Possible Causes and Solutions**
+
+**1. Memory Leaks**
+```bash
+Symptoms: Service works initially, then stops
+
+Diagnosis:
+- Monitor RAM usage over time
+- Check container restart count
+
+Solutions:
+- Restart container regularly (cron job)
+- Update to newer image version
+- Reduce container memory limits
+- Report bug to service maintainer
+```
+
+**2. Configuration Errors**
+```bash
+Symptoms: Service fails to start or crashes immediately
+
+Diagnosis:
+- Check container logs for error messages
+- Verify configuration file syntax
+
+Solutions:
+- Review configuration files
+- Use default configuration as starting point
+- Check documentation for required settings
+- Validate JSON/YAML syntax
+```
+
+**3. Dependency Issues**
+```bash
+Symptoms: Service starts but features don't work
+
+Diagnosis:
+- Check if required services are running
+- Verify network connectivity between containers
+
+Solutions:
+- Start dependencies first
+- Use Docker networks for container communication
+- Check service discovery configuration
+- Verify database connections
+```
+
+---
+
+## 📊 Monitoring and Prevention
+
+### **Set Up Basic Monitoring**
+
+#### **Built-in Synology Monitoring**
+```bash
+# Enable these monitoring features:
+☐ Resource Monitor → Enable notifications
+☐ Storage Manager → Enable SMART notifications
+☐ Control Panel → Notification → Configure email
+☐ Security → Enable auto-block
+☐ Log Center → Enable log rotation
+```
+
+#### **Essential Monitoring Checks**
+```bash
+# Daily checks (automated):
+- Disk space usage
+- RAID array health
+- System temperature
+- Network connectivity
+- Service availability
+
+# Weekly checks (manual):
+- Review system logs
+- Check backup status
+- Update system and packages
+- Review security logs
+- Test disaster recovery procedures
+```
+
+### **Preventive Maintenance**
+
+#### **Weekly Tasks (15 minutes)**
+```bash
+☐ Check system notifications
+☐ Review Resource Monitor graphs
+☐ Verify backup completion
+☐ Check available storage space
+☐ Update Docker containers (if auto-update disabled)
+```
+
+#### **Monthly Tasks (1 hour)**
+```bash
+☐ Update DSM and packages
+☐ Review and clean up logs
+☐ Check SMART status of all drives
+☐ Test UPS functionality
+☐ Review user access and permissions
+☐ Clean up old files and downloads
+```
+
+#### **Quarterly Tasks (2-3 hours)**
+```bash
+☐ Full system backup
+☐ Test disaster recovery procedures
+☐ Review and update documentation
+☐ Security audit and password changes
+☐ Plan capacity upgrades
+☐ Review monitoring and alerting setup
+```
+
+---
+
+## 🆘 When to Ask for Help
+
+### **Before Posting in Forums**
+
+#### **Information to Gather**
+```bash
+# Always include this information:
+- Exact hardware model (NAS, drives, network equipment)
+- Software versions (DSM, Docker, specific applications)
+- Exact error messages (screenshots preferred)
+- What you were trying to accomplish
+- What you've already tried
+- Relevant log entries
+- Network configuration details
+```
+
+#### **How to Get Good Help**
+```bash
+✅ Be specific about the problem
+✅ Include relevant technical details
+✅ Show what you've already tried
+✅ Be patient and polite
+✅ Follow up with solutions that worked
+
+❌ Don't just say "it doesn't work"
+❌ Don't post blurry photos of screens
+❌ Don't ask for help without trying basic troubleshooting
+❌ Don't bump posts immediately
+❌ Don't cross-post the same question everywhere
+```
+
+### **Best Places to Get Help**
+
+#### **Synology-Specific Issues**
+```bash
+1. Synology Community Forum
+   - Official support
+   - Knowledgeable community
+   - Searchable knowledge base
+
+2. r/synology (Reddit)
+   - Active community
+   - Quick responses
+   - Good for general questions
+```
+
+#### **Docker and Self-Hosting Issues**
+```bash
+1. r/selfhosted (Reddit)
+   - Large community
+   - Application-specific help
+   - Good for service recommendations
+
+2. LinuxServer.io Discord
+   - Real-time chat support
+   - Excellent for Docker issues
+   - Very helpful community
+
+3. Application-specific forums
+   - Plex forums for Plex issues
+   - Nextcloud community for Nextcloud
+   - GitHub issues for open-source projects
+```
+
+#### **General Homelab Questions**
+```bash
+1. r/homelab (Reddit)
+   - Broad homelab community
+   - Hardware recommendations
+   - Architecture discussions
+
+2. ServeTheHome Forum
+   - Enterprise-focused
+   - Hardware reviews
+   - Advanced configurations
+```
+
+---
+
+## 🔧 Essential Tools for Troubleshooting
+
+### **Built-in Synology Tools**
+```bash
+# Always use these first:
+- Resource Monitor (real-time system stats)
+- Log Center (system and application logs)
+- Storage Manager (drive health and RAID status)
+- Network Center (network diagnostics)
+- Security Advisor (security recommendations)
+- Package Center (application management)
+```
+
+### **External Tools**
+```bash
+# Network diagnostics:
+- ping (connectivity testing)
+- nslookup/dig (DNS resolution)
+- iperf3 (network speed testing)
+- Wireshark (packet analysis - advanced)
+
+# System monitoring:
+- Uptime Kuma (service monitoring)
+- Grafana + Prometheus (advanced monitoring)
+- PRTG (network monitoring)
+
+# Mobile apps:
+- DS finder (find Synology devices)
+- DS file (file access and management)
+- DS cam (surveillance station)
+```
+
+---
+
+## 📚 Learning Resources
+
+### **Essential Reading**
+```bash
+# Documentation:
+- Synology Knowledge Base
+- Docker Documentation
+- Your specific application documentation
+
+# Communities:
+- r/homelab wiki
+- r/synology community info
+- LinuxServer.io documentation
+```
+
+### **Video Tutorials**
+```bash
+# YouTube Channels:
+- SpaceInvaderOne (Docker tutorials)
+- TechnoTim (homelab guides)
+- Marius Hosting (Synology-specific)
+- NetworkChuck (networking basics)
+```
+
+---
+
+## 🎯 Troubleshooting Mindset
+
+### **Stay Calm and Methodical**
+```bash
+✅ Take breaks when frustrated
+✅ Document what you try
+✅ Change one thing at a time
+✅ Test after each change
+✅ Keep backups of working configurations
+✅ Learn from each problem
+```
+
+### **Build Your Skills**
+```bash
+# Each problem is a learning opportunity:
+- Understand the root cause, not just the fix
+- Document solutions for future reference
+- Share knowledge with the community
+- Practice troubleshooting in low-pressure situations
+- Build a personal knowledge base
+```
+
+---
+
+**🔧 Remember**: Troubleshooting is a skill that improves with practice. Every expert has broken things and learned from the experience. Don't be afraid to experiment, but always have backups of important data and working configurations.
+
+**🆘 When in doubt**: Stop, take a break, and ask for help. The homelab community is incredibly supportive and helpful to beginners who show they've tried to solve problems themselves first.