Skip to content

Development Tools

Helpful scripts and tools to work with this repository locally.

Documentation Generators

Auto-generate doc stubs

# Generate doc skeleton for all kustomizations
python3 tools/generate_docs.py

# Force overwrite existing docs
python3 tools/generate_docs.py --force

Produces basic docs/apps/<APP>.md stubs for each kustomization.yaml found.

Restructure docs into categories

# Organize docs/apps/*.md into subdirectories
python3 tools/restructure_docs.py

Creates: - docs/apps/apps/ — User applications - docs/apps/infrastructure/ — Infrastructure components - docs/apps/clusters/ — Cluster-related docs - docs/apps/other/ — Everything else

Generate category index pages

# Create index.md for each category
python3 tools/generate_category_indexes.py

Updates navigation and category indexes automatically.

Local Development

MkDocs

pip install -r requirements.txt

mkdocs serve
# Open http://localhost:8000

mkdocs build -d site/

Kubernetes / Kustomize

# Check what will be deployed
kustomize build apps/base/mkdocs
kustomize build apps/production

# Dry-run apply (no changes)
kustomize build apps/production | kubectl apply --dry-run=client -f -

# Apply kustomization
kubectl apply -k apps/production

Docker

docker build -t ghcr.io/your-org/homelab-mkdocs:latest -f docs/docker/Dockerfile .

docker run -p 8000:80 ghcr.io/your-org/homelab-mkdocs:latest
# Open http://localhost:8000

docker push ghcr.io/your-org/homelab-mkdocs:latest

Repository Structure Tools

Understand directory layout

# Tree view (install tree if needed: brew install tree)
tree -L 2 apps/
tree -L 2 infrastructure/

Find kustomizations

# List all kustomization.yaml files
find . -name "kustomization.yaml" | sort

# Count by category
find apps -name "kustomization.yaml" | wc -l
find infrastructure -name "kustomization.yaml" | wc -l

Search manifests

# Find deployments with image tag
grep -r "image:" apps/ | grep "latest"

# Find PVCs
grep -r "PersistentVolume" apps/ infrastructure/

# Find ingress definitions
grep -r "networking.k8s.io/v1" . | grep "Ingress"

Cluster Management

Access cluster

# Set kubeconfig or context
export KUBECONFIG=/path/to/kubeconfig.yaml
kubectl config set-context mycontext

# Check cluster info
kubectl cluster-info
kubectl get nodes

Debugging pods

# Logs from deployment
kubectl -n <namespace> logs -f deployment/<app>

# Get shell into pod
kubectl -n <namespace> exec -it deployment/<app> -- /bin/sh

# Port-forward to local
kubectl -n <namespace> port-forward svc/<service> 8000:80

Watch reconciliation (Flux)

# Watch Flux status
kubectl -n flux-system logs -f deployment/source-controller
kubectl -n flux-system logs -f deployment/kustomize-controller

# Trigger manual reconciliation
flux reconcile kustomization apps --with-source

Code Quality

YAML linting

# Install yamllint
pip install yamllint

# Lint all manifests
yamllint apps/ infrastructure/

Shell scripts

# Install ShellCheck
brew install shellcheck

# Check shell scripts
shellcheck tools/*.sh

Markdown linting

# Install mdl (markdownlint)
gem install mdl

# Check docs
mdl docs/

Tips & Tricks

Diff before applying

# Show what would change
kustomize build apps/production | kubectl diff -f -

# Dry-run to see changes
kubectl apply -k apps/production --dry-run=client --output yaml | less

Backup current cluster state

# Export all resources
kubectl get all --all-namespaces -o yaml > cluster-backup.yaml

# Export specific namespace
kubectl get all -n <namespace> -o yaml > namespace-backup.yaml

Quick port-forwards for testing

# Access Grafana locally
kubectl -n monitoring port-forward svc/grafana 3000:80

# Access Prometheus
kubectl -n monitoring port-forward svc/prometheus 9090:9090

# Access MkDocs
kubectl -n mkdocs port-forward svc/mkdocs 8000:80

Environment Variables

Set these for convenience:

export KUBECONFIG=$HOME/.kube/config
export DOCKER_REGISTRY=ghcr.io/your-org
export DOCKER_USERNAME=your-github-username

Next Steps