Skip to content

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 192.168.20.0/24 (cluster network)

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
uvx Python tool runner pip install uv

Quick install (macOS): 

brew install kubectl kubelogin vault terraform gh lefthook rumdl cocogitto
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.

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

vault login

This opens a browser for OIDC authentication via Authentik.

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 (MkDocs)
scripts/ Utility scripts

Next Steps