buun-stack
A remotely accessible Kubernetes home lab with OIDC authentication. Build a modern development environment with integrated data analytics and AI capabilities. Includes a complete open data stack for data ingestion, transformation, serving, and orchestration—built on open-source components you can run locally and port to any cloud.
- 📺 Remote-Accessible Kubernetes Home Lab (YouTube playlist)
- 📝 Building a Remote-Accessible Kubernetes Home Lab with k3s (Dev.to article)
Architecture
Foundation
- k3s: Lightweight Kubernetes distribution
- Just: Task runner with templated configurations
- Cloudflare Tunnel: Secure internet connectivity
Core Components (Required)
- PostgreSQL: Database cluster with pgvector extension
- Keycloak: Identity and access management with OIDC authentication
Recommended Components
- HashiCorp Vault: Centralized secrets management
- Used by most stack modules for secure credential storage
- Can be deployed without, but highly recommended
- External Secrets Operator: Kubernetes secret synchronization from Vault
- Automatically syncs secrets from Vault to Kubernetes Secrets
- Provides secure secret rotation and lifecycle management
Storage (Optional)
Data & Analytics (Optional)
- JupyterHub: Interactive computing with collaborative notebooks
- Trino: Distributed SQL query engine for querying multiple data sources
- ClickHouse: High-performance columnar analytics database
- Qdrant: Vector database for AI/ML applications
- Lakekeeper: Apache Iceberg REST Catalog for data lake management
- Metabase: Business intelligence and data visualization
- DataHub: Data catalog and metadata management
Orchestration (Optional)
- Dagster: Modern data orchestration platform
- Apache Airflow: Workflow orchestration and task scheduling
Security (Optional)
- OAuth2 Proxy: Authentication proxy for adding Keycloak authentication
Quick Start
For detailed step-by-step instructions, see the Installation Guide.
-
Clone and configure
git clone https://github.com/buun-ch/buun-stack cd buun-stack mise install just env::setup -
Deploy cluster and services
just k8s::install just longhorn::install just vault::install just postgres::install just keycloak::install -
Configure authentication
just keycloak::create-realm just vault::setup-oidc-auth just keycloak::create-user just k8s::setup-oidc-auth
Component Details
k3s
Lightweight Kubernetes distribution optimized for edge computing and resource-constrained environments.
Longhorn
Enterprise-grade distributed storage system providing:
- Highly available block storage
- Backup and disaster recovery
- No single point of failure
- Support for NFS persistent volumes
HashiCorp Vault
Centralized secrets management offering:
- Secure secret storage
- Dynamic secrets generation
- Encryption as a service
- Integration with External Secrets Operator for automatic Kubernetes Secret synchronization
Keycloak
Open-source identity and access management providing:
- Single Sign-On (SSO)
- OIDC/OAuth2 authentication
- User federation and identity brokering
PostgreSQL
Production-ready relational database for:
- Keycloak data storage
- Application databases
- Vector similarity search with pgvector extension for AI/ML workloads
External Secrets Operator
Kubernetes operator for syncing secrets from external systems:
- Automatically syncs secrets from Vault to Kubernetes Secrets
- Supports multiple secret backends
- Provides secure secret rotation and lifecycle management
MinIO
S3-compatible object storage system providing:
- High-performance distributed object storage
- AWS S3 API compatibility
- Erasure coding for data protection
- Multi-tenancy support
JupyterHub
Multi-user platform for interactive computing with Keycloak authentication and persistent storage.
📖 See JupyterHub Documentation
Metabase
Business intelligence and data visualization platform with PostgreSQL integration.
Trino
Fast distributed SQL query engine for big data analytics with:
- Multi-Source Queries: Query PostgreSQL, Iceberg, and other data sources in a single query
- Keycloak Authentication: OAuth2 for Web UI and password authentication for JDBC clients
- Metabase Integration: Connect via Starburst driver for data visualization
- Sample Data: TPCH catalog with benchmark data for testing
DataHub
Modern data catalog and metadata management platform with OIDC integration.
ClickHouse
High-performance columnar OLAP database for analytics and data warehousing.
📖 See ClickHouse Documentation
Qdrant
High-performance vector database for AI/ML applications with similarity search and rich filtering.
Lakekeeper
Apache Iceberg REST Catalog for managing data lake tables with OIDC authentication.
📖 See Lakekeeper Documentation
Apache Airflow
Modern workflow orchestration platform for data pipelines with JupyterHub integration.
Dagster
Modern data orchestration platform for building data pipelines and managing data assets.
Common Operations
User Management
Create additional users:
just keycloak::create-user
Add user to group:
just keycloak::add-user-to-group <username> <group>
Database Management
Create database:
just postgres::create-db <dbname>
Create database user:
just postgres::create-user <username>
Grant privileges:
just postgres::grant <dbname> <username>
Secret Management
Store secrets in Vault:
just vault::put <path> <key>=<value>
Retrieve secrets:
just vault::get <path> <field>
Security & Authentication
OAuth2 Proxy Integration
For applications that don't natively support Keycloak/OIDC authentication, buun-stack provides OAuth2 Proxy integration to add Keycloak authentication to any application:
- Universal Authentication: Add Keycloak SSO to any web application
- Automatic Setup: Configures Keycloak client, secrets, and proxy deployment
- Security: Prevents unauthorized access by routing all traffic through authentication
- Easy Management: Simple recipes for setup and removal
Setup OAuth2 authentication for any application:
# For CH-UI (included in installation prompt)
just ch-ui::setup-oauth2-proxy
# For any custom application
just oauth2-proxy::setup-for-app <app-name> <app-host> [namespace] [upstream-service]
Remove OAuth2 authentication:
just ch-ui::remove-oauth2-proxy
just oauth2-proxy::remove-for-app <app-name> [namespace]
The OAuth2 Proxy automatically:
- Creates a Keycloak client with proper audience mapping
- Generates secure secrets and stores them in Vault
- Deploys proxy with Traefik ingress routing
- Disables direct application access to ensure security
Remote Access
Once configured, you can access your cluster from anywhere:
# SSH access
ssh ssh.yourdomain.com
# Kubernetes API
kubectl --context yourpc-oidc get nodes
# Web interfaces
# Vault: https://vault.yourdomain.com
# Keycloak: https://auth.yourdomain.com
# Trino: https://trino.yourdomain.com
# Metabase: https://metabase.yourdomain.com
# Airflow: https://airflow.yourdomain.com
# JupyterHub: https://jupyter.yourdomain.com
Customization
Adding Custom Recipes
You can extend buun-stack with your own Just recipes and services:
-
Copy the example files:
cp custom-example.just custom.just cp -r custom-example custom -
Use the custom recipes:
# Install reddit-rss just custom::reddit-rss::install # Install Miniflux feed reader just custom::miniflux::install -
Create your own recipes:
Add new modules to the custom/ directory following the same pattern as the examples. Each module should have its own justfile with install, uninstall, and other relevant recipes.
The custom.just file is automatically imported by the main Justfile if it exists, allowing you to maintain your custom workflows separately from the core stack.
Troubleshooting
- Check logs:
kubectl logs -n <namespace> <pod-name>
License
MIT License - See LICENSE file for details