OrangeLab

Private distributed self-hosting infrastructure.

Features

• Infrastructure as code and deployment automation (Pulumi ↗)
• Lightweight Kubernetes cluster (K3S ↗)
• Encrypted networking (Tailscale ↗)
• Distributed replicated storage (Longhorn ↗)
• Daily incremental backups to S3 (RustFS ↗)
• Custom domain support (Traefik ↗)
• SSL certificate provisioning (Cert-manager ↗)
• GPU support (AMD, NVIDIA) for local AI workloads
• PostgreSQL, MariaDB, and Redis database management

Deploy applications using included Pulumi stacks (stacks/ folder) or create your own by referencing @orangelab/pulumi.

Hardware requirements

Linux

Most Linux systems with kernel 6.11.6+ and SELinux are supported. That includes your own hardware (e.g. laptops, mini PCs, Rasberry Pi and Zimaboard) as well as any cloud instances.

The main requirement is that K3S and Longhorn (including open-iscsi and iscsiadm) can be installed.

Note: Installation instructions assume your machines are running Bluefin (Developer edition, https://projectbluefin.io/ ↗) based on Fedora Silverblue unless otherwise noted.

Windows, MacOS

Windows and MacOS support is limited, specifically they cannot be used as Longhorn storage nodes.

See Disabling Longhorn Guide with instructions on using local-path-provisioner instead of Longhorn.

Memory

Minimum 2-4GB memory required for Longhorn. Recommended 8-16GB+ allows to run most components on a single host. More might be needed for AI workloads.

GPU

Both NVIDIA and AMD GPUs are supported. See Hardware module for more information.

Principles and goals

• decentralized - uses your physical machines potentially spread out over geographical locations, minimise dependency on external services and cloud providers
• private by default - uses Tailscale/WireGuard for end to end encrypted communication, making services public has to be explicitly enabled
• OSS - only open source components that can be run locally
• automation - use Pulumi and Helm to automate most tasks and configuration
• easy to use - no deep Kubernetes knowledge required, sensible defaults
• offline mode - continue working (with some limitations) over local network when internet connection lost
• lightweight - can be run on a single laptop using default configuration, focus on consumer hardware
• scalable - distribute workloads across multiple machines, optional use of cloud instances
• self-healing - in case of problems, the system should recover with minimal user intervention
• immutable - no snowflakes, as long as there is at least one Longhorn replica available, components can be destroyed and easily recreated
• simple disaster recovery - all you need to recreate the system from scratch is Longhorn backups and Pulumi configs

Installation

Warning

This project is under active development. It is recommended to use static Longhorn volumes and fromVolume setting so applications can be destroyed and redeployed without data loss.

Kubernetes Cluster

Configure Pulumi then install Tailscale and K3S on each node you want to add to the cluster:

• Installation - Admin node - Initial Pulumi and Tailscale setup
• Installation - Linux node configuration - Configure nodes (firewall, suspend settings)
• Installation - SSH configuration (Optional) - Configure SSH keys on nodes for easier access
• Installation - K3s cluster - Install Kubernetes cluster and label nodes

Core components

After setting up the Kubernetes cluster, deploy the required core modules:

1. Network - Routing provider (Tailscale or Traefik)
2. Storage - Distributed storage (Longhorn) and optionally backups (S3)
3. Hardware - (Optional) GPU support
4. Data - (Optional) Databases

Information about general application configuration and deployment can be found at Configuration Guide

Application deployment

After core components are deployed, install any applications you need from the list below.

More information about stacks in general at Multi-Stack Deployment

Available applications

Core stack

Network:

• cert-manager - certificate management
• tailscale-operator - ingress support with Tailscale authentication
• traefik - reverse proxy for custom domain support
• technitium - DNS server and ad-blocker

Storage:

• longhorn - replicated storage
• rustfs - S3-compatible storage (Longhorn backup target)

Hardware:

• nfd - Node Feature Discovery (GPU autodetection)
• amd-gpu-operator - AMD GPU support
• nvidia-gpu-operator - NVidia GPU support

Data:

• cloudnative-pg - PostgreSQL operator
• mariadb-operator - MariaDB operator

Monitoring:

• beszel - Beszel lightweight monitoring
• prometheus - Prometheus/Grafana monitoring

Optional application stacks

Apps:

• nextcloud - File sharing, calendars, contacts, tasks
• vaultwarden - Bitwarden-compatible password manager

AI:

• invokeai - generative AI plaform, community edition
• n8n - AI workflow automation
• ollama - local large language models
• open-webui - Open WebUI frontend
• kubeai - (Experimental) Private AI SDK for Kubernetes with OpenAI-compatible API
• automatic1111 - (Deprecated) Stable Diffusion WebUI.
• sdnext - (Deprecated) Stable Diffusion WebUI.

Bitcoin:

• bitcoin-core - Bitcoin Core node
• bitcoin-knots - Bitcoin Knots node
• electrs - Electrs (Electrum) server implementation
• mempool - Blockchain explorer

Dev:

• debug - (Experimental) Troubleshooting utilities and volume access tools

IoT:

• home-assistant - sensor and home automation platform

Media:

• droppedneedle - Self-hosted music discovery, requests, and native library engine
• immich - Self-hosted photo and video backup solution
• jellyfin - Streaming movies, TV shows and music
• lidarr - Music collection manager
• prowlarr - Indexer manager for the *arr ecosystem
• radarr - Movie collection manager
• seerr - Media discovery
• slskd - Soulseek download client for DroppedNeedle
• sonarr - TV show collection manager
• transmission - BitTorrent download client

Documentation

• ↗ - AI generated documentation and good place to ask questions
• Installation - Admin node - Initial Pulumi and Tailscale setup
• Installation - Linux node configuration - Configure nodes (firewall, suspend settings)
• Installation - Alpine Linux - Node configuration for Alpine Linux
• Installation - Zimaboard (ZimaOS) - Node configuration for ZimaOS
• Installation - SSH configuration - Configure SSH keys on nodes for easier access
• Installation - K3s cluster - Install Kubernetes cluster and label nodes
• Backup and Restore - Using Longhorn backups with S3 storage
• Configuration Guide - Application configuration and deployment
• Disabling Longhorn - Running OrangeLab without distributed storage
• Multi-Stack Deployment - Deploy applications as independent Pulumi stacks
• Troubleshooting - Common issues and solutions
• Upgrade Guide - Upgrading your OrangeLab installation