CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Kubernetes Helm-based homelab application deployment system using ArgoCD for GitOps. Contains 40+ containerized applications deployed via Helm charts with a shared common library to minimize template duplication.

Commands

# Validate YAML files
yamllint .

# Helm chart operations (run from chart directory)
helm dependency build           # Fetch common library dependency
helm lint .                     # Validate chart syntax
helm template <release> . --set globals.environment=prod --set globals.domain=example.com

# Utility scripts
./scripts/migrate_database.py <source_db> <dest_db> [--clean]  # PostgreSQL migration
./scripts/sync_pvc_with_host.sh <host-path> <namespace> <pvc>  # PVC sync

Architecture

Directory Structure

apps/charts/ - Individual application Helm charts (deployed to prod namespace)
apps/common/ - Shared Helm library chart with standardized templates
apps/root/ - ArgoCD ApplicationSet for auto-discovery
shared/charts/ - Shared infrastructure services (authentik, nats)
scripts/ - Python/Bash utility scripts for database migration and PVC sync

Deployment Model

Three ArgoCD ApplicationSets auto-discover charts from their respective charts/ directories. Folders suffixed with .disabled are excluded from deployment.

Common Library Pattern

Most charts use the common library (apps/common/) which provides standardized templates. A minimal chart needs:

Chart.yaml with common library dependency:

apiVersion: v2
version: 1.0.0
name: my-app
dependencies:
  - name: common
    version: 1.0.0
    repository: file://../../common

Standardized values.yaml (see apps/common/README.md for full structure)
Template files that include common helpers:

# templates/deployment.yaml
{{ include "common.deployment" . }}

Or use single file with {{ include "common.all" . }} to render all resources automatically.

Key Templates

common.deployment - Deployment with health probes, volumes, init containers
common.service - Service(s) with port mapping
common.pvc - Persistent volume claims
common.virtualService - Istio routing (public/private gateways)
common.oidc - Authentik OIDC client registration
common.database - PostgreSQL database provisioning
common.externalSecrets - Password generators and secret templates

Placeholders in values.yaml

{release} - Release name
{namespace} - Release namespace
{fullname} - Full app name
{subdomain} - App subdomain (from subdomain value)
{domain} - Global domain
{timezone} - Global timezone

Secret Naming Conventions

OIDC credentials: {release}-oidc-credentials (clientId, clientSecret, issuer)
Database connection: {release}-connection (url, host, port, user, password)
Generated secrets: {release}-secrets

Conventions

Chart and release names use kebab-case
All container images pinned by SHA256 digest (Renovate manages updates)
Storage uses persistent storageClassName
Istio VirtualServices route via public/private gateways
Deployment strategy: Recreate for stateful apps, RollingUpdate for stateless

YAML Style

Max line length: 120 characters
Indentation: 2 spaces
Truthy values: true, false, on, off

Documentation

AGENTS.md - Chart creation guidelines
apps/common/README.md - Complete common library reference
apps/common/MIGRATION.md - Guide for migrating charts to common library
apps/common/TEMPLATING.md - Placeholder system documentation

3.6 KiB Raw Blame History