Environment Setup

This guide walks you through setting up your local development environment for working with the fzymgc-house cluster.

Prerequisites

macOS or Linux workstation
Git installed and configured
Terminal access
Homebrew (macOS) or equivalent package manager
Network access to the cluster network — any trusted-Main address (192.168.16.0/20: wired Main 20.0/22 or MainWireless 24.0/22) reaches the nodes and VIPs in 192.168.20.0/24

Required Tools

Install the following tools:

Tool	Purpose	Installation
kubectl	Kubernetes CLI	`brew install kubectl`
kubelogin	OIDC authentication	`brew install kubelogin`
vault	HashiCorp Vault CLI	`brew install vault`
terraform	Infrastructure as Code	`brew install terraform`
ansible	Configuration management	`pip install ansible`
gh	GitHub CLI	`brew install gh`
lefthook	Git hooks manager	`brew install lefthook`
rumdl	Markdown linting	`brew install rumdl`
cocogitto	Commit validation	`brew install cocogitto`
go-task	Task runner	`brew install go-task`
uvx	Python tool runner	`pip install uv`

Quick install (macOS):

brew install kubectl kubelogin vault terraform gh lefthook rumdl cocogitto go-task
pip install ansible uv

Cross-platform: Linux users can use their package manager. See tool-specific installation docs for Windows.

Repository Setup

Clone the Repository

git clone git@github.com:fzymgc-house/selfhosted-cluster.git
cd selfhosted-cluster

Install Git Hooks

bd hooks install --chain

This installs git hooks via beads that chain with lefthook for linting and validation.

Note: The hooks are managed by beads (bd) and chain to lefthook for actual linting. This allows beads to manage its own hook lifecycle (for issue tracking sync) while delegating linting to lefthook.

Task Runner

task --list at the repository root shows what exists. Today that is the hl-assets-uploader Go suite, which is cgo against a pinned libheif and therefore runs inside a container rather than on your host — see apps/hl-assets-uploader/README.md.

Python Environment

The repository includes a virtual environment setup for Ansible:

# Create virtual environment (one-time)
./setup-venv.sh

# Activate before Ansible work
source .venv/bin/activate

Environment Variables

Vault Configuration

export VAULT_ADDR=https://vault.fzymgc.house

Add to your shell profile (~/.zshrc or ~/.bashrc) for persistence.

Kubeconfig

Create a directory for cluster configs:

mkdir -p ~/.kube/configs

Set KUBECONFIG to include cluster configs:

export KUBECONFIG=~/.kube/configs/fzymgc-house-oidc.yml

Note: You need to create this kubeconfig file first. See Cluster Access for instructions.

Authentication Setup

vault login

This opens a browser for OIDC authentication via Keycloak.

GitHub CLI

gh auth login

Follow prompts to authenticate with GitHub.

Verification

Run these commands to verify your setup:

# Check Vault connectivity
./scripts/vault-helper.sh status

# Verify kubectl can reach cluster
kubectl --context fzymgc-house get nodes

# Verify Terraform
terraform version

# Verify Ansible
ansible --version

# Verify GitHub CLI
gh auth status

Expected output includes:

Vault showing “connected” status
8 cluster nodes listed (3 control plane, 5 workers)
Terraform version 1.x
Ansible version 2.x
GitHub CLI showing authenticated status

Directory Structure

Key directories you’ll work with:

Directory	Purpose
`ansible/`	Cluster deployment playbooks
`tf/`	Terraform modules for infrastructure
`argocd/`	Kubernetes manifests (GitOps)
`docs/`	Documentation (Astro Starlight)
`scripts/`	Utility scripts

Next Steps

Cluster Access - Configure kubectl and OIDC authentication
AI Tooling - Set up MCP servers and Claude Code