Private distributed self-hosting infrastructure.
- Infrastructure as code and deployment automation (Pulumi ↗)
- Lightweight Kubernetes cluster (K3S ↗)
- Encrypted networking (Tailscale ↗ or self-hosted Headscale)
- 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.
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 iscsiadm - provided by iscsi-initiator-utils on Fedora, open-iscsi on Alpine and Debian) can be installed.
Tested with:
- Bluefin (Developer edition, https://projectbluefin.io/ ↗) based on Fedora Silverblue
- Fedora
- Alpine
- ZimaOS
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.
Minimum 2-4GB memory required for Longhorn. 16-32GB+ allows to run most components on a single host. More might be needed for AI workloads.
Recommended setup to run all applications is 3+ nodes with 64GB+ memory combined for storage replication and redundancy.
Both NVIDIA and AMD GPUs are supported. Some applications (Ollama, Frigate) supports Intel GPUs. See Hardware module for more information.
- decentralized - uses your physical machines potentially spread out over geographical locations, minimise dependency on external services and cloud providers
- private by default - uses Tailscale/Headscale/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
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.
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
After setting up the Kubernetes cluster, deploy the required core modules:
- Network - Routing provider (Tailscale or Traefik), public exposure, mesh VPN choice (Tailscale/Headscale)
- Storage - Distributed storage (Longhorn) and optionally backups (S3)
- Hardware - (Optional) GPU support
- Data - (Optional) Databases
Information about general application configuration and deployment can be found at Configuration Guide
After core components are deployed, install any applications you need from the list below.
More information about stacks in general at Multi-Stack Deployment
cert-manager- certificate managementtailscale-operator- ingress support with Tailscale authenticationtraefik- reverse proxy for custom domain supportcaddy- serves the bare domain (WebFinger, redirects)headscale- self-hosted Tailscale control planeheadplane- web UI for Headscaletechnitium- DNS server and ad-blockerzot- OCI registry and pull-through image cache
nfd- Node Feature Discovery (GPU autodetection)amd-gpu-operator- AMD GPU supportnvidia-gpu-operator- NVidia GPU support
Data:
cloudnative-pg- PostgreSQL operatormariadb-operator- MariaDB operator
beszel- Beszel lightweight monitoringprometheus- Prometheus/Grafana monitoring
pocket-id- OpenID Connect provider with passkey authentication
Apps:
nextcloud- File sharing, calendars, contacts, tasksvaultwarden- Bitwarden-compatible password manager
AI:
invokeai- generative AI plaform, community editionn8n- AI workflow automationollama- local large language modelsopen-webui- Open WebUI frontendkubeai- (Experimental) Private AI SDK for Kubernetes with OpenAI-compatible APIautomatic1111- (Deprecated) Stable Diffusion WebUI.sdnext- (Deprecated) Stable Diffusion WebUI.
bitcoin-core- Bitcoin Core nodebitcoin-knots- Bitcoin Knots nodeelectrs- Electrs (Electrum) server implementationmempool- Blockchain explorer
Dev:
debug- (Experimental) Troubleshooting utilities and volume access toolsforgejo- Self-hosted GitHub alternative
IoT:
home-assistant- sensor and home automation platformfrigate- Local NVR with realtime AI object detectionmatter- Matter controller for Home Assistantmosquitto- MQTT broker for Home Assistant/Frigateopenthread- Thread border router
droppedneedle- Self-hosted music discovery, requests, and native library engineimmich- Self-hosted photo and video backup solutionjellyfin- Streaming movies, TV shows and musiclidarr- Music collection managerprowlarr- Indexer manager for the *arr ecosystemradarr- Movie collection managerseerr- Media discoveryslskd- Soulseek download client for DroppedNeedlesonarr- TV show collection managertransmission- BitTorrent download client
↗ - AI generated documentation and good place to ask questions
- Installation - Admin node - Initial Pulumi and Tailscale setup
- Pulumi backend and state - Local (recommended) or Pulumi Cloud state backends, backups and switching
- Installation - Linux node configuration - Configure nodes (firewall, suspend settings)
- Installation - Alpine Linux - Node configuration for Alpine Linux
- Installation - Fedora Linux - Node configuration for plain Fedora
- 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
- Public services - Publish applications and expose the Traefik public gateway with a router forward or VPS proxy
- Public proxy on a VPS - Expose public services through Headscale or Tailscale without router port forwarding (tested on Ubuntu, Debian and Fedora)
- Backup and Restore - Using Longhorn backups with S3 storage
- Configuration Guide - Application configuration and deployment
- Migrating nodes to Headscale - Moving an existing cluster off Tailscale to a self-hosted control plane
- 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
