apps/CLAUDE.md

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:

1. 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

2. Standardized values.yaml (see apps/common/README.md for full structure)

3. 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