Add .gitignore and remove CLAUDE.md from repository
- Created comprehensive .gitignore file covering: • Development documentation (CLAUDE.md) • Log files and temporary files • IDE/editor configurations • OS-generated files • Docker artifacts • Environment files with secrets - Removed CLAUDE.md from repository tracking while preserving local copy - CLAUDE.md remains available for local development but won't be public This keeps development documentation private while maintaining clean public repo. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Stephen Klein
+34
@@ -0,0 +1,34 @@
|
|||||||
|
# HOPS .gitignore
|
||||||
|
|
||||||
|
# Claude Code development documentation
|
||||||
|
CLAUDE.md
|
||||||
|
|
||||||
|
# Log files
|
||||||
|
*.log
|
||||||
|
|
||||||
|
# Temporary files
|
||||||
|
*.tmp
|
||||||
|
*.temp
|
||||||
|
|
||||||
|
# IDE and editor files
|
||||||
|
.vscode/
|
||||||
|
.idea/
|
||||||
|
*.swp
|
||||||
|
*.swo
|
||||||
|
*~
|
||||||
|
|
||||||
|
# OS generated files
|
||||||
|
.DS_Store
|
||||||
|
.DS_Store?
|
||||||
|
._*
|
||||||
|
.Spotlight-V100
|
||||||
|
.Trashes
|
||||||
|
ehthumbs.db
|
||||||
|
Thumbs.db
|
||||||
|
|
||||||
|
# Environment files (if containing secrets)
|
||||||
|
.env.local
|
||||||
|
.env.*.local
|
||||||
|
|
||||||
|
# Docker build artifacts
|
||||||
|
docker-compose.override.yml
|
||||||
@@ -1,261 +0,0 @@
|
|||||||
# CLAUDE.md
|
|
||||||
|
|
||||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
||||||
|
|
||||||
## Project Overview
|
|
||||||
|
|
||||||
HOPS (Homelab Orchestration Provisioning Script) is a comprehensive automation tool for deploying homelab infrastructure using Docker Compose. It provides menu-driven installation, management, and monitoring of popular homelab services including media servers, download clients, monitoring tools, and more.
|
|
||||||
|
|
||||||
**Cross-Platform Support**: HOPS now supports Linux (Ubuntu/Debian/Mint), macOS, and Windows (via WSL2) systems with intelligent platform detection and abstraction.
|
|
||||||
|
|
||||||
## Architecture
|
|
||||||
|
|
||||||
### Core Components
|
|
||||||
|
|
||||||
- **Main Script (`hops.sh`)**: Primary entry point providing menu-driven interface for all operations
|
|
||||||
- **Installer (`install`)**: Handles service installation and Docker Compose deployment
|
|
||||||
- **Uninstaller (`uninstall`)**: Manages complete removal of services and configurations
|
|
||||||
- **Service Definitions (`services`)**: Contains Docker Compose service templates and configurations
|
|
||||||
- **Library System (`lib/`)**: Modular abstraction layer for cross-platform compatibility
|
|
||||||
- `lib/common.sh`: Shared logging, UI, and utility functions
|
|
||||||
- `lib/system.sh`: OS detection, system requirements, and platform abstraction
|
|
||||||
|
|
||||||
### Key Design Patterns
|
|
||||||
|
|
||||||
- **Modular Architecture**: Each major function is separated into dedicated scripts
|
|
||||||
- **Cross-Platform Abstraction**: OS-specific operations are abstracted through lib/system.sh
|
|
||||||
- **Service-Driven**: All services are defined as Docker Compose configurations with standardized patterns
|
|
||||||
- **Error Handling**: Comprehensive error handling with logging and rollback capabilities
|
|
||||||
- **Security First**: Built-in security hardening, platform-appropriate firewall configuration, and secure password generation
|
|
||||||
|
|
||||||
## Development Commands
|
|
||||||
|
|
||||||
### Running HOPS
|
|
||||||
```bash
|
|
||||||
# Main script (requires root on Linux, admin on macOS)
|
|
||||||
sudo ./hops.sh
|
|
||||||
|
|
||||||
# Direct installation (Linux)
|
|
||||||
sudo ./install
|
|
||||||
|
|
||||||
# Direct installation (macOS)
|
|
||||||
sudo ./install
|
|
||||||
|
|
||||||
# Direct installation (Windows WSL2)
|
|
||||||
sudo ./install
|
|
||||||
|
|
||||||
# Uninstallation
|
|
||||||
sudo ./uninstall
|
|
||||||
```
|
|
||||||
|
|
||||||
### Platform-Specific Requirements
|
|
||||||
|
|
||||||
**Linux (Ubuntu/Debian/Mint):**
|
|
||||||
- Root/sudo access
|
|
||||||
- Internet connection
|
|
||||||
- 2GB+ RAM, 10GB+ disk space
|
|
||||||
|
|
||||||
**macOS:**
|
|
||||||
- Admin access
|
|
||||||
- Internet connection
|
|
||||||
- 2GB+ RAM, 10GB+ disk space
|
|
||||||
- Homebrew will be installed automatically if not present
|
|
||||||
- Docker Desktop will be installed automatically via Homebrew
|
|
||||||
|
|
||||||
**Windows (WSL2):**
|
|
||||||
- Windows 10/11 with WSL2 enabled
|
|
||||||
- Ubuntu 20.04+ distribution in WSL2
|
|
||||||
- Docker Desktop with WSL2 backend
|
|
||||||
- Admin access to install prerequisites
|
|
||||||
- 2GB+ RAM, 10GB+ disk space
|
|
||||||
|
|
||||||
### Testing and Validation
|
|
||||||
```bash
|
|
||||||
# Check script syntax
|
|
||||||
bash -n hops.sh
|
|
||||||
bash -n install
|
|
||||||
bash -n services
|
|
||||||
bash -n uninstall
|
|
||||||
bash -n lib/system.sh
|
|
||||||
bash -n lib/common.sh
|
|
||||||
|
|
||||||
# Test OS detection and system requirements
|
|
||||||
source lib/common.sh && source lib/system.sh && detect_os && check_system_requirements 2 10
|
|
||||||
|
|
||||||
# Test service definitions
|
|
||||||
source services
|
|
||||||
generate_service_definition jellyfin
|
|
||||||
```
|
|
||||||
|
|
||||||
### Log Management
|
|
||||||
```bash
|
|
||||||
# View installation logs (Linux)
|
|
||||||
sudo tail -f /var/log/hops/hops-main-*.log
|
|
||||||
|
|
||||||
# View installation logs (macOS)
|
|
||||||
sudo tail -f /usr/local/var/log/hops/hops-main-*.log
|
|
||||||
|
|
||||||
# View Docker Compose logs
|
|
||||||
cd ~/hops && docker compose logs -f [service-name]
|
|
||||||
```
|
|
||||||
|
|
||||||
## Service Architecture
|
|
||||||
|
|
||||||
### Service Definition Pattern
|
|
||||||
All services follow a standardized Docker Compose pattern:
|
|
||||||
- LinuxServer.io containers with PUID/PGID/TZ environment variables
|
|
||||||
- Platform-aware volume mounting:
|
|
||||||
- **Linux**: `/opt/appdata` for configs, `/mnt/media` for data
|
|
||||||
- **macOS**: `/Users/[user]/hops/config` for configs, `/Users/[user]/hops/media` for data
|
|
||||||
- Health checks for web services
|
|
||||||
- Unified network configuration (`homelab` network)
|
|
||||||
- Restart policy: `unless-stopped`
|
|
||||||
- Platform-specific features (timezone mounts, GPU access) handled automatically
|
|
||||||
|
|
||||||
### Supported Service Categories
|
|
||||||
1. **Media Management**: Sonarr, Radarr, Lidarr, Readarr, Bazarr, Prowlarr, Tdarr, Huntarr
|
|
||||||
2. **Download Clients**: qBittorrent, Transmission, NZBGet, SABnzbd
|
|
||||||
3. **Media Servers**: Jellyfin, Plex, Emby, Jellystat
|
|
||||||
4. **Request Management**: Overseerr, Jellyseerr, Ombi
|
|
||||||
5. **Reverse Proxy**: Traefik, Nginx Proxy Manager, Authelia
|
|
||||||
6. **Monitoring**: Portainer, Uptime Kuma, Watchtower
|
|
||||||
|
|
||||||
## File Structure
|
|
||||||
|
|
||||||
### Linux File Structure
|
|
||||||
```
|
|
||||||
~/hops/ # Main deployment directory
|
|
||||||
├── docker-compose.yml # Generated service definitions
|
|
||||||
├── .env # Environment variables
|
|
||||||
└── logs/ # Application logs
|
|
||||||
|
|
||||||
/opt/appdata/ # Application configurations
|
|
||||||
└── [service-name]/ # Individual service configs
|
|
||||||
|
|
||||||
/mnt/media/ # Media storage
|
|
||||||
├── movies/
|
|
||||||
├── tv/
|
|
||||||
├── music/
|
|
||||||
└── downloads/
|
|
||||||
```
|
|
||||||
|
|
||||||
### macOS File Structure
|
|
||||||
```
|
|
||||||
~/hops/ # Main deployment directory
|
|
||||||
├── docker-compose.yml # Generated service definitions
|
|
||||||
├── .env # Environment variables
|
|
||||||
├── logs/ # Application logs
|
|
||||||
├── config/ # Application configurations
|
|
||||||
│ └── [service-name]/ # Individual service configs
|
|
||||||
└── media/ # Media storage
|
|
||||||
├── movies/
|
|
||||||
├── tv/
|
|
||||||
├── music/
|
|
||||||
└── downloads/
|
|
||||||
```
|
|
||||||
|
|
||||||
## Environment Configuration
|
|
||||||
|
|
||||||
Key environment variables in `~/hops/.env`:
|
|
||||||
- `PUID`/`PGID`: User/group IDs for file permissions
|
|
||||||
- `TZ`: Timezone configuration
|
|
||||||
- `DATA_ROOT`: Media storage location
|
|
||||||
- `CONFIG_ROOT`: Application configuration location
|
|
||||||
- Security passwords (auto-generated)
|
|
||||||
|
|
||||||
## Security Features
|
|
||||||
|
|
||||||
- **Firewall Integration**:
|
|
||||||
- **Linux**: Automatic UFW rule management
|
|
||||||
- **macOS**: Manual firewall configuration (automatic setup skipped)
|
|
||||||
- **Secure Password Generation**: Cryptographically secure passwords
|
|
||||||
- **File Permission Hardening**: Restrictive permissions on sensitive files
|
|
||||||
- **Network Isolation**: Docker network segregation
|
|
||||||
- **SSL/TLS Support**: Automatic certificate management with reverse proxies
|
|
||||||
|
|
||||||
## Error Handling
|
|
||||||
|
|
||||||
- **Comprehensive Logging**: All operations logged to platform-specific directories
|
|
||||||
- **Linux**: `/var/log/hops/`
|
|
||||||
- **macOS**: `/usr/local/var/log/hops/`
|
|
||||||
- **Rollback Capability**: Automatic rollback on deployment failure
|
|
||||||
- **Dependency Validation**: Pre-deployment system requirement checks
|
|
||||||
- **Service Health Monitoring**: Built-in health checks for all services
|
|
||||||
|
|
||||||
## Key Functions
|
|
||||||
|
|
||||||
### In `hops.sh`
|
|
||||||
- `show_main_menu()`: Primary interface
|
|
||||||
- `manage_services()`: Service start/stop/restart
|
|
||||||
- `show_service_status()`: Real-time monitoring
|
|
||||||
- `show_access_info()`: Service URL and credential display
|
|
||||||
|
|
||||||
### In `services`
|
|
||||||
- `generate_service_definition()`: Creates Docker Compose service blocks
|
|
||||||
- `get_linuxserver_env()`: Standard environment variables
|
|
||||||
- `get_web_healthcheck()`: Health check configurations
|
|
||||||
- `get_timezone_mount()`: Platform-specific timezone handling
|
|
||||||
- `get_gpu_devices()`: Platform-specific GPU access
|
|
||||||
|
|
||||||
### In `install`
|
|
||||||
- Service selection and dependency resolution
|
|
||||||
- Docker Compose file generation
|
|
||||||
- Cross-platform dependency installation
|
|
||||||
- Security hardening implementation
|
|
||||||
- Post-deployment verification
|
|
||||||
|
|
||||||
### In `lib/system.sh`
|
|
||||||
- `detect_os()`: Cross-platform OS detection
|
|
||||||
- `check_system_requirements()`: Platform-aware system validation
|
|
||||||
- `install_package()`: Package manager abstraction
|
|
||||||
- `install_docker()`: Platform-specific Docker installation
|
|
||||||
- `get_primary_ip()`: Network interface detection
|
|
||||||
- `get_default_*_path()`: Platform-specific path resolution
|
|
||||||
|
|
||||||
## Development Guidelines
|
|
||||||
|
|
||||||
- **Bash Best Practices**: Use `set -e` for error handling, quote variables, use readonly for constants
|
|
||||||
- **Cross-Platform Compatibility**: Always use lib/system.sh abstraction functions instead of direct OS commands
|
|
||||||
- **Logging**: Use the logging functions (`log`, `error_exit`, `warning`, `success`, `info`)
|
|
||||||
- **Color Output**: Use predefined color constants for consistent formatting
|
|
||||||
- **Service Patterns**: Follow the established Docker Compose patterns when adding new services
|
|
||||||
- **Security**: Never commit secrets, use secure password generation, implement proper file permissions
|
|
||||||
- **Path Handling**: Use `get_default_*_path()` functions for platform-specific paths
|
|
||||||
|
|
||||||
## Common Operations
|
|
||||||
|
|
||||||
### Adding New Services
|
|
||||||
1. Add service definition function in `services`
|
|
||||||
2. Add service to installer menu in `install`
|
|
||||||
3. Configure any required dependencies or special handling
|
|
||||||
4. Test deployment and health checks
|
|
||||||
|
|
||||||
### Debugging Issues
|
|
||||||
1. Check logs in platform-specific directories:
|
|
||||||
- **Linux**: `/var/log/hops/`
|
|
||||||
- **macOS**: `/usr/local/var/log/hops/`
|
|
||||||
2. Verify Docker Compose syntax with `docker compose config`
|
|
||||||
3. Check service health with `docker compose ps`
|
|
||||||
4. Review firewall rules:
|
|
||||||
- **Linux**: `sudo ufw status`
|
|
||||||
- **macOS**: Check System Preferences > Security & Privacy > Firewall
|
|
||||||
|
|
||||||
## Platform-Specific Notes
|
|
||||||
|
|
||||||
### macOS Considerations
|
|
||||||
- **Architecture Support**: Both Intel (x86_64) and Apple Silicon (ARM64) are supported
|
|
||||||
- **Docker Desktop**: Automatically installed via Homebrew if not present
|
|
||||||
- **Homebrew**: Automatically installed if not present
|
|
||||||
- **GPU Acceleration**: Not available (Docker containers cannot access macOS GPU)
|
|
||||||
- **Firewall**: Manual configuration required (automatic UFW setup skipped)
|
|
||||||
- **File Permissions**: Uses user's home directory structure for better compatibility
|
|
||||||
- **Service Management**: Uses launchctl instead of systemctl where applicable
|
|
||||||
|
|
||||||
### Linux Considerations
|
|
||||||
- **Architecture Support**: x86_64 only
|
|
||||||
- **Docker Engine**: Installed via official Docker script
|
|
||||||
- **Package Management**: Uses apt-get for Ubuntu/Debian/Mint
|
|
||||||
- **GPU Acceleration**: Available for Intel GPUs via /dev/dri passthrough
|
|
||||||
- **Firewall**: Automatic UFW configuration
|
|
||||||
- **File Permissions**: Uses system-wide directories (/opt, /mnt)
|
|
||||||
- **Service Management**: Uses systemctl for service management
|
|
||||||
Reference in New Issue
Block a user