OrangeLab

Private distributed self-hosting infrastructure.

Features

• 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.

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 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, 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. 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.

GPU

Both NVIDIA and AMD GPUs are supported. Some applications (Ollama, Frigate) supports Intel GPUs. 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/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

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), public exposure, mesh VPN choice (Tailscale/Headscale)
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
• caddy - serves the bare domain (WebFinger, redirects)
• headscale - self-hosted Tailscale control plane
• headplane - web UI for Headscale
• technitium - DNS server and ad-blocker
• zot - OCI registry and pull-through image cache

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

Security:

• pocket-id - OpenID Connect provider with passkey authentication

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
• forgejo - Self-hosted GitHub alternative

IoT:

• home-assistant - sensor and home automation platform
• frigate - Local NVR with realtime AI object detection
• matter - Matter controller for Home Assistant
• mosquitto - MQTT broker for Home Assistant/Frigate
• openthread - Thread border router

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
• 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