Pages on Landry Zetam - Tech Blog

Technology Stack

Fri, 08 Aug 2025 00:00:00 +0000

This page covers the complete technology landscape and tools that power my infrastructure and projects. Everything runs on a production-grade Kubernetes cluster, providing a solid foundation for experimentation and real-world deployments.

🗺️ How the K3s Cluster Works

The whole platform runs on K3s — a lightweight Kubernetes distribution — driven entirely by GitOps. Nothing is changed by hand: I describe the desired state in Git, and the cluster continuously reconciles itself to match. The diagram below traces that loop end to end.

Active Use Cases - Fako Cluster in Action

Mon, 01 Jan 0001 00:00:00 +0000

This section documents real-world use cases and practical applications of the Fako cluster services. Each use case includes detailed walkthroughs, screenshots, and implementation details.

📋 Table of Contents

🤖 Personal AI Assistant

Overview

A comprehensive AI assistant setup using Open WebUI, Ollama, and GPUStack for various AI models.

Audiobookshelf - Self-Hosted Audiobook and Podcast Server

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Audiobookshelf is a self-hosted audiobook and podcast server deployed in the Fako cluster. It provides a comprehensive media management system with features like automatic metadata fetching, progress syncing across devices, and a beautiful web interface. Audiobookshelf supports various audio formats and offers mobile apps for iOS and Android, making it a complete solution for managing and enjoying your audio library.

Key Features

Multi-Format Support: MP3, M4A, M4B, FLAC, OGG, and more
Automatic Metadata: Fetches cover art, descriptions, and metadata
Progress Sync: Syncs playback position across all devices
Mobile Apps: Native iOS and Android applications
Multi-User: Support for multiple users with individual progress
Series Management: Organize books by series and authors
Podcast Support: Subscribe and manage podcast feeds
Sleep Timer: Built-in sleep timer for bedtime listening
Variable Playback Speed: Adjust playback speed to preference

Architecture

Components

Deployment: Single-replica deployment
Service: ClusterIP service on port 3005
Storage: Three PersistentVolumeClaims:
- Config: Application configuration and database
- Metadata: Cover images and cached metadata
- Audiobooks: Media library storage
ConfigMap: Basic configuration settings
Security Context: Runs as user 1000

Resource Requirements

Memory: 512Mi (request), 1Gi (limit)
CPU: 250m (request), 1000m (limit)
Storage:
- Config volume for database
- Metadata volume for images/cache
- Audiobooks volume for media files

Configuration

Deployment Settings

Parameter	Value	Description
Image	`ghcr.io/advplyr/audiobookshelf:2.26.0`	Audiobookshelf version
Port	`3005`	Web interface port
User/Group	`1000`	Non-root user
Volumes	3 mounts	Config, metadata, and media

Volume Mounts

/config: Database and configuration files
/metadata: Cover art and metadata cache
/audiobooks: Media library root directory

Usage

Accessing Audiobookshelf

Internal access:

Gitleaks - Secret Detection and Cleanup Service

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Gitleaks is an automated secret scanning and cleanup service deployed in the Fako cluster. It runs as a scheduled CronJob that scans Git repositories for exposed secrets, API keys, and sensitive information. When secrets are detected, it can automatically remove them from the entire Git history using BFG Repo-Cleaner. This service helps maintain security by preventing accidental exposure of credentials in version control.

Key Features

Automated Scanning: Scheduled scans every 6 hours
Secret Detection: Identifies various types of secrets and credentials
History Cleanup: Removes secrets from entire Git history
Dry Run Mode: Test scans without making changes
Auto-Push: Optional automatic pushing of cleaned repos
Slack Notifications: Alerts when secrets are found
GitHub Integration: Uses GitHub token for authentication
Comprehensive Reports: JSON reports of findings

Architecture

Components

CronJob: Scheduled execution every 6 hours
ServiceAccount: For Kubernetes API access
ConfigMap: Cleanup script and configuration
External Secret: GitHub token from AWS Secrets Manager
Init Container: Installs required tools (BFG, Java)
Volumes: Temporary storage for scans and results

Resource Requirements

Memory: 512Mi (request), 1Gi (limit)
CPU: 200m (request), 500m (limit)
Storage: EmptyDir volumes for temporary data

Configuration

Environment Variables

Variable	Default	Description
`GITHUB_TOKEN`	From secret	GitHub authentication token
`DRY_RUN`	`false`	Run scan without cleanup
`AUTO_PUSH`	`false`	Auto-push cleaned repos
`SLACK_WEBHOOK`	Optional	Slack notification URL
`REPO_URL`	In script	Target repository URL

Schedule

CronJob Schedule: 0 */6 * * * (every 6 hours)
Runs at: 00:00, 06:00, 12:00, 18:00 UTC

Usage

Manual Execution

Trigger a manual scan:

GPUStack Proxy - Secure Tunnel Access Service

Mon, 01 Jan 0001 00:00:00 +0000

Overview

GPUStack Proxy is a Cloudflare Tunnel-based proxy service deployed in the Fako cluster that provides secure external access to the GPUStack AI inference platform. It uses Cloudflare’s cloudflared to create an encrypted tunnel between the cluster and Cloudflare’s edge network, eliminating the need for exposed public IPs or open inbound ports. The service includes automatic endpoint synchronization with AWS Secrets Manager for seamless integration with AI applications.

Key Features

Cloudflare Tunnel: Zero-trust secure access without exposed ports
High Availability: Multi-replica cloudflared deployment
Automatic Failover: Built-in redundancy and health checks
Endpoint Sync: Automated endpoint updates to AWS Secrets Manager
SSL/TLS Termination: Handled by Cloudflare edge
DDoS Protection: Cloudflare’s built-in protection
No Public IP Required: Works behind NAT/firewall
Metrics & Monitoring: Built-in metrics endpoint

Architecture

Components

Cloudflared Deployment: 2 replicas for HA
Service: ClusterIP routing to GPUStack
ConfigMap: Tunnel configuration
External Secrets: Tunnel credentials from AWS
Endpoint Sync Job: Updates AWS with tunnel info
Ingress: Optional Kubernetes ingress

Resource Requirements

Memory: 128Mi (request), 256Mi (limit)
CPU: 250m (request), 500m (limit)
Replicas: 2 for high availability

Configuration

Tunnel Configuration

Parameter	Value	Description
Tunnel Name	`audiobooks`	Cloudflare tunnel identifier
Hostname	`gpustack.landryzetam.net`	External access URL
Target	`http://gpustack:80`	Internal GPUStack service
Metrics Port	`2000`	Health and metrics endpoint

Service Routing

ingress:
 - hostname: gpustack.landryzetam.net
 service: http://gpustack:80
 - hostname: hello.example.com
 service: hello_world  # Debug endpoint
 - service: http_status:404  # Catch-all

Usage

Accessing GPUStack

External access via Cloudflare:

Headlamp - Kubernetes Dashboard

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Headlamp is a user-friendly Kubernetes dashboard deployed in the Fako cluster. It provides a web-based UI for managing and monitoring Kubernetes resources across all namespaces. Headlamp offers an intuitive interface for both beginners and advanced users, with support for plugins and real-time updates. This deployment includes the Kubescape security plugin for enhanced cluster security visibility.

Key Features

User-Friendly Interface: Clean, modern UI for Kubernetes management
Real-Time Updates: Live view of cluster resources and events
Multi-Resource Support: Manage all Kubernetes resource types
Plugin Architecture: Extensible with custom plugins
In-Cluster Mode: Runs with cluster service account
Kubescape Integration: Security scanning and compliance checks
Mobile Responsive: Works on desktop and mobile devices

Architecture

Components

Deployment: Single-replica deployment
Service: ClusterIP service on port 80
Ingress: HTTPS access (configured separately)
ServiceAccount: Cluster-wide permissions for resource access
Init Container: Installs Kubescape plugin
Plugin Volume: EmptyDir for plugin storage

Resource Requirements

Memory: 128Mi (request), 512Mi (limit)
CPU: 100m (request), 500m (limit)
Storage: EmptyDir for plugins (ephemeral)

Configuration

Deployment Settings

Parameter	Value	Description
`-in-cluster`	Enabled	Run using in-cluster config
`-plugins-dir`	`/build/plugins`	Plugin directory location
Port	`4466`	Application HTTP port
Image	`ghcr.io/headlamp-k8s/headlamp:v0.33.0`	Headlamp version

RBAC Configuration

Headlamp runs with a ClusterRole that provides full access to:

Housekeeping - Cluster Cleanup Service

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Housekeeping is an automated cluster maintenance service deployed in the Fako cluster. It runs as a CronJob that periodically cleans up completed and failed pods across all namespaces. This service helps maintain cluster hygiene by removing terminated pods that would otherwise accumulate and consume resources. It’s essential for keeping the cluster clean and preventing resource exhaustion from leftover pod metadata.

Key Features

Automated Cleanup: Runs every hour to clean terminated pods
Cluster-Wide: Scans all namespaces for cleanup candidates
Safe Deletion: Only removes pods in Succeeded or Failed states
Detailed Logging: Reports what was found and cleaned
Concurrency Control: Prevents overlapping cleanup runs
Statistics Tracking: Counts total pods found and deleted
Force Deletion: Uses grace period 0 for immediate removal
Job History: Keeps history of last 3 successful/failed runs

Architecture

Components

CronJob: Scheduled execution every hour
ServiceAccount: Cluster-wide permissions for pod management
ClusterRole: Permissions to list and delete pods
ConfigMap: Cleanup script with logic
Container: kubectl image with bash script execution

Resource Requirements

Image: bitnami/kubectl:1.33
CPU/Memory: Minimal (kubectl operations)
Permissions: Cluster-wide pod list/delete

Configuration

Schedule

CronJob Schedule: 0 * * * * (every hour at minute 0)
Concurrency Policy: Forbid (no overlapping runs)
TTL After Finish: 3600 seconds (1 hour)
History Limits: 3 successful, 3 failed jobs

Cleanup Targets

The service removes pods in these states:

How to Document Your Fako Cluster Setup

Mon, 01 Jan 0001 00:00:00 +0000

This guide will help you systematically document all aspects of your Fako cluster using the Hugo blog system.

Overview of the Documentation System

Your documentation system consists of:

Central docs directory: /docs/ in your repository
Hugo blog: Automatically syncs and serves documentation
CronJob: Updates the blog every 6 hours from GitHub

Step-by-Step Documentation Process

1. Document Your Services

For each service in apps/base/, create documentation using the template:

# Copy the template
cp docs/services/SERVICE_TEMPLATE.md docs/services/[service-name]/README.md

# Edit with your service details

Priority services to document:

Hugo Blog Documentation Service

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The Hugo Blog service is a static site generator that serves as the central documentation hub for the Fako cluster. It automatically collects and organizes documentation from across the repository, presenting it in a searchable, user-friendly website. The service uses Hugo with automatic synchronization from GitHub.

Key Features

Automatic Documentation Collection: CronJob syncs docs every 6 hours
Static Site Generation: Fast, secure Hugo-based site
GitHub Integration: Pulls documentation directly from repository
Organized Structure: Categorized documentation (services, guides, architecture)
Minimal Deployment: Simple Hugo server with basic theme
Persistent Storage: Documentation cached in PVC

Architecture

Components

Deployment: Single-replica Hugo server deployment
Service: ClusterIP service on port 80
Ingress: HTTPS access at blog.fako-cluster.local
Storage: 5Gi PersistentVolumeClaim for content
ConfigMaps:
- Documentation copy scripts
- Hugo configuration (if customized)
CronJob: Automatic GitHub synchronization

Resource Requirements

Memory: 128Mi (request), 256Mi (limit)
CPU: 100m (request), 500m (limit)
Storage: 5Gi for Hugo site content

Configuration

Hugo Server Configuration

The deployment creates a minimal Hugo site on startup with:

Infrastructure Documentation

Mon, 01 Jan 0001 00:00:00 +0000

📍 This content has been reorganized!

The infrastructure documentation has been consolidated into the Kubernetes (K8s) project, which is the foundation of our entire platform.

🏗️ Please visit the Kubernetes (K8s) Project for:

Architecture - High-level system design and principles
Infrastructure - Core components and configurations
Operations - Maintenance procedures and runbooks
Security - Security architecture and practices
Networking - Network setup and ingress management
Storage - Persistent storage solutions

Why the Change?

We’ve reorganized our documentation to better reflect that Kubernetes is the foundation upon which all other services are built. This makes it clearer that:

KAgent - Kubernetes AI Agent Framework

Mon, 01 Jan 0001 00:00:00 +0000

Overview

KAgent is a Kubernetes-native AI agent framework deployed in the Fako cluster. It provides a platform for deploying and managing AI agents that can interact with various systems through the Model Context Protocol (MCP). Agents can be configured with different AI models, specialized knowledge, and tool access. The framework supports multiple AI providers including OpenAI, Ollama, and GPUStack, making it flexible for various use cases from Kubernetes operations to code generation.

Keycloak - Identity and Access Management

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Keycloak is an open-source Identity and Access Management (IAM) solution deployed in the Fako cluster. It provides single sign-on (SSO), user federation, identity brokering, and social login capabilities. This deployment uses Keycloak 26.x with PostgreSQL backend and is configured for high availability with clustering.

Key Features

Single Sign-On (SSO): One login for multiple applications
Identity Brokering: Connect to external identity providers
User Federation: Sync users from LDAP or Active Directory
Social Login: Support for Google, GitHub, Facebook, etc.
Multi-Factor Authentication: Enhanced security with MFA
High Availability: Clustered deployment with 2 replicas
Secure Credential Management: Integration with AWS Secrets Manager

Architecture

Components

Deployment: 2-replica deployment with pod anti-affinity
Services:
- Main service on port 8080
- Headless service for JGroups clustering
Storage: PostgreSQL database (postgres-cluster)
ConfigMap: Environment configuration
External Secrets:
- Admin credentials from AWS Secrets Manager
- Database credentials from AWS Secrets Manager
Init Container: Database initialization and user setup

Resource Requirements

Memory: 1Gi (request), 2Gi (limit) per pod
CPU: 500m (request), 1000m (limit) per pod
Database: PostgreSQL with dedicated database and user

Configuration

Environment Settings

Parameter	Value	Description
`KC_HOSTNAME`	`https://auth.landryzetam.net`	External hostname
`KC_HOSTNAME_STRICT`	`false`	Allow backend access
`KC_HTTP_ENABLED`	`true`	Enable HTTP (behind proxy)
`KC_PROXY`	`edge`	Running behind edge proxy
`KC_PROXY_HEADERS`	`xforwarded`	Use X-Forwarded headers
`KC_HEALTH_ENABLED`	`true`	Enable health endpoints
`KC_METRICS_ENABLED`	`true`	Enable metrics
`KC_CACHE_STACK`	`kubernetes`	Use Kubernetes discovery

Database Configuration

Type: PostgreSQL
Host: postgres-cluster-rw.postgres.svc.cluster.local
Port: 5432
Database: keycloak
Credentials: Managed via AWS Secrets Manager

Clustering Configuration

JGroups clustering is configured for session replication:

Kube-bench - Kubernetes Security Benchmark Scanner

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Kube-bench is an automated security compliance scanner deployed in the Fako cluster. It runs the CIS Kubernetes Benchmark checks to ensure the cluster follows security best practices. The service executes as a daily CronJob that performs comprehensive security scans, checking configurations of various Kubernetes components against industry standards. Results are saved with timestamps for audit trails and compliance reporting.

Key Features

CIS Benchmark Compliance: Checks against Center for Internet Security standards
Automated Scanning: Daily scheduled security assessments
Comprehensive Coverage: Scans master and worker node configurations
JSON Output: Machine-readable results for integration
Historical Records: Timestamped results for trend analysis
Host Access: Direct access to Kubernetes configuration files
Multi-Component: Checks etcd, kubelet, API server, and more
Results Processing: Automatic display of scan findings

Architecture

Components

CronJob: Daily execution at 2 AM
ServiceAccount: Permissions for scanning operations
Main Container: kube-bench scanner with host access
Results Processor: Monitors and displays scan results
Storage: PersistentVolumeClaim for scan history
Host Mounts: Access to Kubernetes system directories

Resource Requirements

Scanner: 256Mi RAM (request), 512Mi (limit)
Processor: 64Mi RAM (request), 128Mi (limit)
CPU: 100m-300m for scanner, 50m-100m for processor
Storage: Persistent volume for results history

Configuration

Schedule

CronJob Schedule: 0 2 * * * (daily at 2:00 AM)
Concurrency Policy: Forbid (no overlapping scans)
History Limits: 3 successful, 3 failed jobs

Security Context

hostPID: true (access host processes)
privileged: true (full host access)
Read-only mounts: All host paths mounted read-only

Usage

Manual Scan Execution

Trigger an immediate security scan:

Kubescape Operator - Kubernetes Security Scanning Platform

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Kubescape Operator is a comprehensive Kubernetes security scanning platform deployed in the Fako cluster. It provides continuous security assessment using multiple frameworks including NSA, MITRE, and CIS benchmarks. The operator performs real-time vulnerability scanning, compliance checking, and network policy analysis. It stores scan results locally and can optionally integrate with Kubescape Cloud for enhanced dashboards and reporting.

Key Features

Multi-Framework Scanning: NSA, MITRE, CIS compliance checks
Continuous Monitoring: Real-time security posture assessment
Vulnerability Scanning: Container image vulnerability detection
Network Policy Analysis: Automated network policy recommendations
Local Storage: Persistent storage for scan results and vulnerability DB
Prometheus Metrics: Export security metrics for monitoring
Node Agent: Runtime security monitoring on Linux nodes
Scheduled Scans: Configurable scanning intervals

Architecture

Components

Operator: Core controller managing scans
Kubevuln: Vulnerability scanner component
Gateway: API gateway for results
Node Agent: Runtime security on each node
Storage: NFS-backed persistent volumes
Helm Release: Managed by Flux

Resource Requirements

Component	Memory Request	Memory Limit	CPU Request	CPU Limit	Ephemeral Storage
Operator	256Mi	512Mi	100m	500m	1Gi/2Gi
Kubevuln	512Mi	1Gi	200m	500m	5Gi/15Gi
Gateway	256Mi	512Mi	100m	300m	1Gi/2Gi

Configuration

Scanning Schedule

Framework	Schedule	Description
NSA	Every 6 hours	National Security Agency guidelines
MITRE	Every 6 hours	MITRE ATT&CK framework
CIS v1.23	Daily at 2 AM	Center for Internet Security benchmark

Storage Configuration

Scan Results: 20Gi on nfs-security-logs
Vulnerability DB: 10Gi on nfs-security-logs
Access Mode: ReadWriteOnce

Usage

Viewing Scan Results

Access scan results via kubectl:

Linkding - Self-Hosted Bookmark Manager

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Linkding is a self-hosted bookmark manager deployed in the Fako cluster. It provides a clean, minimal web interface for saving, organizing, and searching bookmarks. Linkding offers features like automatic title and description retrieval, tagging, full-text search, and bookmark archiving. It’s designed as a privacy-focused alternative to commercial bookmark services, keeping all your data under your control.

Key Features

Privacy-Focused: Self-hosted with no external dependencies
Clean Interface: Minimalist, fast web UI
Tagging System: Organize bookmarks with tags
Full-Text Search: Search titles, descriptions, and tags
Auto-Completion: Title and description fetching
Archive Support: Archive bookmarks with Wayback Machine
Import/Export: Supports standard bookmark formats
REST API: Programmatic access to bookmarks
Mobile-Friendly: Responsive design for all devices

Architecture

Components

Deployment: Single-replica deployment
Service: ClusterIP service on port 9090
Storage: PersistentVolumeClaim for bookmark data
Secret: Environment variables for configuration
Security Context: Runs as www-data user (UID 33)

Resource Requirements

Memory: 128Mi (request), 256Mi (limit)
CPU: 250m (request), 500m (limit)
Storage: Persistent volume for database and assets

Configuration

Deployment Settings

Parameter	Value	Description
Image	`sissbruecker/linkding:1.41.0`	Linkding version
Port	`9090`	Web interface port
User	`www-data (33)`	Run as non-root user
Data Path	`/etc/linkding/data`	Persistent data location

Environment Variables

Configuration via linkding-container-env secret:

MCP Servers - Model Context Protocol Services

Mon, 01 Jan 0001 00:00:00 +0000

Overview

MCP (Model Context Protocol) Servers is a collection of specialized services deployed in the Fako cluster that extend AI capabilities by providing structured access to various tools and resources. These servers implement the Model Context Protocol, enabling AI assistants like Claude to interact with external systems, databases, APIs, and tools in a standardized way. Each MCP server provides specific functionality that can be consumed by AI agents for enhanced automation and integration.

Node Labeling - Kubernetes Node Classification Service

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Node Labeling is an automated Kubernetes job deployed in the Fako cluster that applies strategic labels to cluster nodes. It classifies nodes based on their hardware capabilities, particularly focusing on GPU resources and performance tiers. This service ensures that workloads can be properly scheduled to appropriate nodes using node selectors and affinity rules. The labeling is crucial for GPU workloads, voice pipeline services, and general workload distribution across the heterogeneous cluster.

Ollama WebUI - Test Instance of Open WebUI

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Ollama WebUI is a test/staging deployment of Open WebUI in the Fako cluster. Despite its name, this service actually uses the Open WebUI image and is configured to connect to GPUStack (not Ollama) as its AI backend. It serves as a testing environment for new configurations, model testing, and user onboarding before changes are promoted to the production Open WebUI instance. This separation allows for safe experimentation without affecting production users.

OpenWakeWord - Wake Word Detection Service

Mon, 01 Jan 0001 00:00:00 +0000

Overview

OpenWakeWord is a wake word detection service deployed in the Fako cluster as part of the voice assistant pipeline. It uses machine learning models to detect specific wake words (like “Hey Jarvis”) in continuous audio streams. The service implements the Wyoming protocol for integration with voice assistants and can handle multiple concurrent audio streams. It’s designed for low-latency, real-time wake word detection and scales automatically based on load.

Key Features

Real-Time Detection: Low-latency wake word detection
Multiple Models: Support for various wake word models
Wyoming Protocol: Standard voice assistant integration
Auto-Scaling: HPA-based scaling for concurrent streams
Model Preloading: Fast startup with preloaded models
High Performance: Optimized for CPU-based inference
Debug Mode: Detailed logging for troubleshooting
Health Monitoring: TCP-based health checks
Persistent Storage: Model caching and custom models

Architecture

Components

Deployment: Single to multi-replica with HPA
Service: ClusterIP on port 10400
NodePort Service: Optional external access
HPA: Auto-scaling 1-3 replicas
Storage: PVC for model storage
Node Affinity: Avoids control plane nodes

Resource Requirements

Memory: 2Gi (request), 3Gi (limit)
CPU: 2 cores (request), 3 cores (limit)
Storage: Persistent volume for models
Scaling: Up to 3 replicas for 4+ streams

Configuration

Service Settings

Parameter	Value	Description
Port	`10400`	Wyoming protocol port
Protocol	`TCP`	Wyoming TCP transport
Preloaded Model	`hey_jarvis`	Default wake word
Debug	Enabled	Verbose logging

Auto-Scaling Configuration

Min Replicas: 1
Max Replicas: 3
CPU Target: 50% utilization
Memory Target: 60% utilization
Scale Up: 15 seconds stabilization
Scale Down: 300 seconds stabilization

Usage

Wyoming Protocol Access

Internal service:

Oura Collector - Health Data Collection Service

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Oura Collector is an automated health data collection service deployed in the Fako cluster. It integrates with the Oura Ring API to collect personal health metrics including sleep, activity, readiness, and heart rate data. The service stores this data in PostgreSQL for analysis and visualization. It features scheduled collection, backfill capabilities, and secure credential management through AWS Secrets Manager. This enables long-term health tracking and analysis within your personal infrastructure.

pgAdmin - PostgreSQL Management Tool

Mon, 01 Jan 0001 00:00:00 +0000

Overview

pgAdmin is a comprehensive web-based management tool for PostgreSQL deployed in the Fako cluster. It provides a graphical interface for database administration, query execution, and monitoring. This deployment is pre-configured to connect to the PostgreSQL cluster with both read-write and read-only endpoints, making database management accessible through a web browser.

Key Features

Web-Based Interface: Full-featured PostgreSQL management from browser
Pre-Configured Servers: Automatic connection to cluster databases
Query Tool: Advanced SQL editor with syntax highlighting
Visual Database Designer: ERD and schema visualization
Backup/Restore: GUI for database backup operations
Server Monitoring: Real-time database statistics
User Management: Graphical user and role administration

Architecture

Components

Deployment: Single-replica deployment
Service: ClusterIP service on port 80
Ingress: HTTPS access (when configured)
Storage: PersistentVolumeClaim for pgAdmin data
ConfigMap: Server configuration and connection settings
External Secrets: Database passwords from AWS Secrets Manager

Resource Requirements

Memory: 256Mi (request), 512Mi (limit)
CPU: 250m (request), 500m (limit)
Storage: Persistent volume for pgAdmin data and sessions

Configuration

Environment Settings

Parameter	Value	Description
`PGADMIN_DEFAULT_EMAIL`	`85landry@gmail.com`	Admin login email
`PGADMIN_CONFIG_SERVER_MODE`	`False`	Desktop mode (single user)
`PGADMIN_CONFIG_MASTER_PASSWORD_REQUIRED`	`False`	No master password needed
`PGADMIN_SERVER_JSON_FILE`	`/pgadmin4/servers.json`	Pre-configured servers

Pre-Configured Database Servers

PostgreSQL Cluster (Read-Write)

Piper - Local Text-to-Speech Service

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Piper is a fast, local text-to-speech (TTS) service deployed in the Fako cluster. It converts text into natural-sounding speech using neural voice models and exposes its functionality via the Wyoming protocol, making it compatible with voice assistant platforms like Home Assistant.

Key Features

CPU-Optimized: Runs efficiently on CPU without requiring GPU
Wyoming Protocol: Compatible with Home Assistant and other voice platforms
Multiple Voice Support: Various voice models with different qualities
Voice Management: Automatic voice model management via sidecar container
Persistent Storage: Voice models cached to avoid re-downloading
Scalable: Supports multiple concurrent TTS processes

Architecture

Components

Deployment: Single-replica deployment with node affinity rules
Service: ClusterIP service on port 10200 (Wyoming protocol)
Storage: PersistentVolumeClaim for voice model storage
ConfigMap: Configuration for default voice settings
Sidecar Container: Voice manager for monitoring voice models

Resource Requirements

GPU: Not required (CPU-only)
Memory: 4Gi (request), 8Gi (limit)
CPU: 2 cores (request), 4 cores (limit)
Storage: Persistent volume for voice model storage

Configuration

Environment Settings

Parameter	Default	Description
`DEFAULT_VOICE`	`en_US-amy-medium`	Default voice model to use
`--max-piper-procs`	`8`	Maximum concurrent TTS processes
`--data-dir`	`/data`	Directory for voice data
`--download-dir`	`/data`	Directory for downloading voices

Available Voice Models

Piper supports various voice models with different qualities:

PostgreSQL Cluster Service

Mon, 01 Jan 0001 00:00:00 +0000

Overview

The PostgreSQL Cluster is a highly available database service deployed using CloudNative PG (CNPG) operator. It provides a 3-node PostgreSQL 16.2 cluster with automatic failover, backup scheduling, and secure credential management through AWS Secrets Manager. This cluster serves as the primary database backend for multiple services including Keycloak, N8N, and other applications.

Key Features

High Availability: 3-node cluster with automatic failover
Automated Backups: Daily scheduled backups at 2 AM
Secure Credentials: Integration with AWS Secrets Manager
Connection Pooling: PgBouncer pooler for efficient connections
Performance Tuned: Optimized PostgreSQL parameters
Pod Anti-Affinity: Instances spread across different nodes
Monitoring Ready: Prometheus metrics support

Architecture

Components

Cluster: 3 PostgreSQL instances (1 primary, 2 replicas)
Operator: CloudNative PG operator manages the cluster
Storage: 50Gi persistent volume per instance
Pooler: PgBouncer connection pooler
Backup: Scheduled backup with retention policy
External Secrets: AWS Secrets Manager integration

Resource Requirements

Memory: 2Gi (request), 4Gi (limit) per instance
CPU: 1 core (request), 2 cores (limit) per instance
Storage: 50Gi per instance (150Gi total)
Storage Class: nfs-postgres-v2

Configuration

PostgreSQL Parameters

Parameter	Value	Description
`max_connections`	`200`	Maximum concurrent connections
`shared_buffers`	`512MB`	Memory for caching data
`effective_cache_size`	`3GB`	Planner’s assumption about cache
`work_mem`	`8MB`	Memory for query operations
`wal_buffers`	`16MB`	WAL write buffer size
`maintenance_work_mem`	`64MB`	Memory for maintenance operations
`max_wal_size`	`1GB`	Maximum WAL size before checkpoint
`checkpoint_timeout`	`5min`	Time between checkpoints

Network Access

The cluster allows connections from:

wger - Self-Hosted Fitness and Workout Manager

Mon, 01 Jan 0001 00:00:00 +0000

Overview

wger (Workout Manager) is a free, open-source fitness and workout tracking application deployed in the Fako cluster. It provides comprehensive features for managing workouts, tracking nutrition, monitoring body weight, and creating exercise routines. The application includes a large exercise database with images and videos, making it an excellent self-hosted alternative to commercial fitness apps. It’s accessible via the web interface and offers both registered user accounts and guest access.

Whisper - Speech-to-Text Service

Mon, 01 Jan 0001 00:00:00 +0000

Overview

Whisper is an automatic speech recognition (ASR) service deployed in the Fako cluster. It uses OpenAI’s Whisper model running on GPU acceleration to provide high-quality speech-to-text transcription. The service is exposed via the Wyoming protocol, making it compatible with various voice assistant platforms.

Key Features

GPU Acceleration: Runs on NVIDIA GPU for fast transcription
Wyoming Protocol: Compatible with Home Assistant and other voice platforms
Multiple Model Sizes: Configurable model size (base, small, medium, large)
Voice Activity Detection: Built-in VAD for efficient processing
Persistent Model Storage: Models are cached to avoid re-downloading

Architecture

Components

Deployment: Single-replica GPU deployment pinned to the yeezyai node
Service: ClusterIP service on port 10300 (Wyoming protocol)
Storage: PersistentVolumeClaim for model caching
ConfigMap: Environment configuration for model parameters

Resource Requirements

GPU: 1 NVIDIA GPU (required)
Memory: 2Gi (request), 4Gi (limit)
CPU: 2 cores (request), 4 cores (limit)
Storage: Persistent volume for model storage

Configuration

Model Parameters (via ConfigMap)

Parameter	Default	Description
`MODEL`	`base`	Whisper model size (tiny, base, small, medium, large)
`LANGUAGE`	`en`	Primary language for transcription
`COMPUTE_TYPE`	`float16`	GPU compute precision
`BEAM_SIZE`	`5`	Beam search width for decoding

Voice Activity Detection

Parameter	Default	Description
`VAD_THRESHOLD`	`0.5`	Voice activity detection threshold
`MIN_SPEECH_DURATION_MS`	`250`	Minimum speech duration in milliseconds
`MAX_SPEECH_DURATION_S`	`30`	Maximum speech duration in seconds
`SPEECH_PAD_MS`	`400`	Padding around detected speech

Usage

Accessing the Service

The Whisper service is available within the cluster at:

Pages on Landry Zetam - Tech Blog

Technology Stack

🗺️ How the K3s Cluster Works

Active Use Cases - Fako Cluster in Action

📋 Table of Contents

AI/ML Use Cases

Development & Automation

Personal Productivity

Infrastructure Management

🤖 Personal AI Assistant

Overview

Audiobookshelf - Self-Hosted Audiobook and Podcast Server

Overview

Key Features

Architecture

Components

Resource Requirements

Configuration

Deployment Settings

Volume Mounts

Usage

Accessing Audiobookshelf

Gitleaks - Secret Detection and Cleanup Service

Overview

Key Features

Architecture

Components

Resource Requirements

Configuration

Environment Variables

Schedule

Usage

Manual Execution

GPUStack Proxy - Secure Tunnel Access Service

Overview

Key Features

Architecture

Components

Resource Requirements

Configuration

Tunnel Configuration

Service Routing

Usage

Accessing GPUStack

Headlamp - Kubernetes Dashboard

Overview

Key Features

Architecture

Components

Resource Requirements

Configuration

Deployment Settings

RBAC Configuration

Housekeeping - Cluster Cleanup Service

Overview

Key Features

Architecture

Components

Resource Requirements

Configuration

Schedule

Cleanup Targets

How to Document Your Fako Cluster Setup

Overview of the Documentation System

Step-by-Step Documentation Process

1. Document Your Services

Hugo Blog Documentation Service

Overview

Key Features

Architecture

Components

Resource Requirements

Configuration

Hugo Server Configuration

Infrastructure Documentation

📍 This content has been reorganized!

🏗️ Please visit the Kubernetes (K8s) Project for:

Why the Change?

KAgent - Kubernetes AI Agent Framework

Overview