mirror of
https://github.com/morten-olsen/homelab-apps.git
synced 2026-02-08 01:36:28 +01:00
101 lines
3.6 KiB
Markdown
101 lines
3.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
```yaml
|
|
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:
|
|
```yaml
|
|
# 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
|