Skip to content

README.md

Latest commit

 

History

History
390 lines (293 loc) · 12.3 KB

README.md

File metadata and controls

390 lines (293 loc) · 12.3 KB

🚀 BlendOS Awesome Stack

License: MIT BlendOS Podman Status

The definitive container-first self-hosting solution designed specifically for blendOS's immutable architecture.

BlendOS Awesome Stack combines the stability of immutable systems with the power of containerized services to create a comprehensive, maintainable, and scalable infrastructure platform.

🌟 Why BlendOS Awesome Stack?

🏗️ Built for Immutable Systems

  • Container-First Design: Everything runs in containers, never modifies the immutable base
  • Declarative Configuration: System state entirely defined in YAML
  • Atomic Updates: Changes are either fully applied or not at all
  • Rollback Safety: Easy system recovery and state management

⚡ Optimized for Modern Hardware

  • Intel + NVIDIA Acceleration: Full hardware transcoding support
  • Multi-Core Utilization: Designed for high-performance systems
  • Memory Efficient: Smart resource allocation across services
  • Remote Management: Built for headless server operation

🔧 Modular Architecture

Choose exactly what you need:

  • 🎬 Media Stack: Plex, Jellyfin, *arr services
  • 💻 Development Stack: Code environments, databases, CI/CD
  • 📊 Monitoring Stack: Grafana, Prometheus, system metrics
  • 📋 Productivity Stack: Vaultwarden, NextCloud, office tools
  • 🌐 Networking Stack: VPN, reverse proxy, network services

🚀 Quick Start

✨ Enhanced One-Line Installation (Recommended)

# 🎆 Ultimate Media Stack with automatic dependency installation
bash <(curl -sL https://raw.githubusercontent.com/wlfogle/blendos-awesome-stack/master/scripts/install-media-stack.sh)

# ⚙️ Or enhanced rebuild script (manual deps)
bash <(curl -sL https://raw.githubusercontent.com/wlfogle/blendos-awesome-stack/master/scripts/rebuild-ultimate-stack-enhanced.sh)

✅ The enhanced installer automatically:

  • Detects BlendOS system and optimizes for immutable architecture
  • Installs missing dependencies (Docker, Docker Compose, curl, etc.)
  • Configures 65+ services across 6 deployment phases
  • Sets up VPN-secured downloads and monitoring
  • Creates management dashboards and shortcuts

Traditional Repository Installation

# Clone the repository
git clone https://github.com/wlfogle/blendos-awesome-stack
cd blendos-awesome-stack

# Install media stack only (recommended for first time)
sudo ./scripts/install.sh

# Or install everything
sudo ./scripts/install.sh --all

Preview Before Installing

# See what would be installed without making changes
sudo ./scripts/install.sh --dry-run --all

📦 Available Stacks

🎬 Media Stack (Default)

Complete media server solution with hardware acceleration:

Service Purpose Port Status
Plex Media server with transcoding :32400 ✅ Ready
Jellyfin Open-source media server :8096 ✅ Ready
Sonarr TV series management :8989 ✅ Ready
Radarr Movie management :7878 ✅ Ready
Lidarr Music management :8686 ✅ Ready
Readarr Book management :8787 ✅ Ready
qBittorrent Download client :8080 ✅ Ready
Prowlarr Indexer management :9696 ✅ Ready
Jackett Additional indexers :9117 ✅ Ready
Overseerr Request management :5055 ✅ Ready
Ombi Alternative requests :3579 ✅ Ready
Tautulli Plex analytics :8181 ✅ Ready

📋 Productivity Stack

Self-hosted productivity and collaboration tools:

Service Purpose Port Status
Vaultwarden Password manager (Bitwarden) :8088 ✅ Ready
NextCloud Cloud storage & sync :8089 ✅ Ready
OnlyOffice Office suite :8082 🚧 Planned
Joplin Server Note taking :8083 🚧 Planned
Kanboard Project management :8084 🚧 Planned
Matrix Communication :8085 🚧 Planned
BookStack Wiki/documentation :8087 🚧 Planned

💻 Development Stack (Coming Soon)

Complete development environment:

  • Code Server: VS Code in browser
  • GitLab/Gitea: Git repository hosting
  • PostgreSQL/MySQL: Database services
  • Redis: Caching and sessions
  • Jenkins: CI/CD pipelines

📊 Monitoring Stack (Coming Soon)

System monitoring and alerting:

  • Grafana: Metrics visualization
  • Prometheus: Metrics collection
  • Uptime Kuma: Service monitoring
  • ELK Stack: Log management

🌐 Networking Stack (Coming Soon)

Network services and security:

  • WireGuard: VPN server
  • Traefik: Reverse proxy
  • Fail2Ban: Security monitoring

🛠️ Installation Options

Individual Stacks

# Media stack only (default)
sudo ./scripts/install.sh --media

# Add productivity tools
sudo ./scripts/install.sh --media --productivity

# Development environment
sudo ./scripts/install.sh --development --monitoring

Hardware Options

# Disable GPU acceleration
sudo ./scripts/install.sh --no-gpu

# Disable VNC/remote desktop
sudo ./scripts/install.sh --no-vnc

# Skip dependency installation
sudo ./scripts/install.sh --skip-deps

🔧 Management

Service Control

# Check status of all stacks
awesome-stack status

# Start/stop individual stacks
awesome-stack media start
awesome-stack productivity stop
awesome-stack all restart

# Quick access to logs
awesome-stack media logs
awesome-stack productivity logs plex

System Information

# Comprehensive system status
awesome-stack status

# Hardware monitoring
awesome-stack hardware

# Container resource usage
awesome-stack resources

🌐 Access Your Services

After installation, access your services through these URLs:

Media Services

Productivity Services

Remote Access

🏗️ Architecture

System Design

blendOS Host (Immutable)
├── Podman Containers
│   ├── Media Stack (:8000-8999)
│   ├── Productivity Stack (:8000-8999)
│   ├── Development Stack (:9000-9999)
│   ├── Monitoring Stack (:3000-3999)
│   └── Networking Stack (:1000-1999)
├── Virtual Displays (VNC)
│   ├── :99-:108 (Xvfb + VNC + noVNC)
│   └── Web Access (:6099-6108)
└── GPU Passthrough (Looking Glass)
    ├── Intel iGPU (Transcoding)
    └── NVIDIA RTX (Gaming/Compute)

Container Strategy

  • Isolated Networks: Each stack runs in its own network
  • Shared Volumes: Media and download directories shared
  • Resource Limits: CPU and memory limits per service
  • Health Checks: Automatic service monitoring
  • Auto-Restart: Services restart on failure

📋 System Requirements

Minimum Requirements

  • OS: blendOS (latest)
  • CPU: 4+ cores
  • RAM: 8GB+
  • Storage: 100GB+ available
  • Network: Stable internet connection

Recommended Hardware

  • CPU: Intel i7/i9 or AMD Ryzen 7/9
  • RAM: 32GB+ (our test system: 62GB)
  • GPU: Intel iGPU + dedicated GPU for transcoding
  • Storage: NVMe SSD + bulk storage drives
  • Network: Gigabit+ connection

Our Test Configuration

  • CPU: Intel i9-13900HX (32 threads) ✅
  • RAM: 62GB DDR5 ✅
  • GPU: NVIDIA RTX 4080 + Intel iGPU ✅
  • Storage: Multiple NVMe drives
  • Network: Gigabit fiber connection

🔒 Security

Built-in Security Features

  • Container Isolation: Services can't access host system
  • Network Segmentation: Isolated container networks
  • Regular Updates: Automated container updates
  • Secure Defaults: Security-focused default configurations
  • VPN Ready: Built-in VPN server support

Recommended Security Steps

  1. Change Default Passwords: Update all default passwords
  2. Enable 2FA: Use Vaultwarden for 2FA storage
  3. Network Security: Configure firewall rules
  4. Regular Backups: Set up automated backups
  5. Monitor Logs: Review system and container logs

📚 Documentation

🤝 Contributing

We welcome contributions! Here's how you can help:

Ways to Contribute

  • 🐛 Bug Reports: Found an issue? Let us know!
  • 💡 Feature Requests: Have ideas for improvements?
  • 📝 Documentation: Help improve our docs
  • 🧪 Testing: Test on different hardware configurations
  • 💻 Code: Submit pull requests for new features

Development Setup

# Fork and clone the repository
git clone https://github.com/yourusername/blendos-awesome-stack
cd blendos-awesome-stack

# Create a feature branch
git checkout -b feature/amazing-new-feature

# Make your changes and test
sudo ./scripts/install.sh --dry-run

# Submit a pull request

📊 Project Status

Current Phase: Alpha Development 🚧

Stack Status Completion
Media ✅ Ready 100%
Productivity 🚧 In Progress 60%
Development 📋 Planned 0%
Monitoring 📋 Planned 0%
Networking 📋 Planned 0%

Upcoming Milestones

  • v0.2.0: Complete productivity stack
  • v0.3.0: Development environment
  • v0.4.0: Monitoring and alerting
  • v0.5.0: Networking services
  • v1.0.0: Stable release

❓ FAQ

Q: Why blendOS specifically?

A: blendOS's immutable architecture provides excellent stability for long-running services while the container support makes it perfect for self-hosting.

Q: Can I run this on other distributions?

A: This stack is optimized for blendOS. While the containers will work elsewhere, the installation and management scripts are blendOS-specific.

Q: How much resources does this use?

A: With all stacks running, expect to use 8-16GB RAM and 4-8 CPU cores under normal load. Individual stacks use much less.

Q: Is this suitable for production?

A: Currently in alpha. We recommend testing thoroughly before production use. Beta release planned for Q2 2025.

Q: How do I backup my data?

A: All container data is stored in /opt/awesome-stack/. Regular backups of this directory will preserve all configurations and data.

📞 Support

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • blendOS Team: For creating an excellent immutable distribution
  • Podman Project: For containerization without daemon
  • Community Contributors: Everyone who helps test and improve this project

⭐ Star this repository if it helped you! ⭐

Built with ❤️ for the blendOS community