homey/AGENTS.md

AGENTS.md

This is a Helm chart for deploying a self-hosted home environment (Homey) on Kubernetes.

Project Overview

• Type: Helm Chart (Kubernetes package manager)
• Language: YAML + Go template syntax (Helm templating)
• Key Files:
  • Chart.yaml - Chart metadata
  • values.yaml - Default configuration values
  • templates/ - Kubernetes manifest templates (auth.yaml, media.yaml, phpldapadmin.yaml, _definitions.yaml)
  • files/ - Configuration file templates (processed by Helm with tpl function)

Build/Lint/Test Commands

Helm Validation

# Lint the Helm chart for errors
helm lint .

# Template rendering (dry-run install)
helm template test-release . --debug

# Install/upgrade in cluster
helm upgrade --install homey . -n homey

# Verify chart against Kubernetes API
helm kubeval .

# Check schema validation of values.yaml
helm schema generate

Manual Template Testing

# Render templates locally with custom values
helm template homey . -f values.yaml --set homey.url=example.com

# Template with debug output
helm template homey . --debug 2>&1 | less

Kubectl Validation

# Dry-run apply to validate manifests
kubectl apply -f templates/auth.yaml --dry-run=server

# Get rendered template directly
helm template homey . | kubectl apply --dry-run=server -f -

Code Style Guidelines

YAML Structure

1. Document Separators: Use --- at the start of each YAML document

   ---
   apiVersion: v1
   kind: ConfigMap
   

2. Indentation: Use 2 spaces (not tabs)

   spec:
     containers:
       - name: app
         image: nginx
   

3. Trailing Commas: Optional but preferred for multi-line lists

   accessModes:
     - ReadWriteMany
     - ReadOnlyMany
   

4. Quotes: Use quotes for strings that might be interpreted as other types

   • Always quote: .Values.homey.url | quote
   • Optional for simple strings like names

Kubernetes Resources

1. Labels: Use Kubernetes recommended labels

   labels:
     app.kubernetes.io/name: openldap
     app.kubernetes.io/component: auth
   

2. Naming: Use kebab-case for resource names

   name: openldap-admin
   name: nextcloud-postgres
   

3. Storage: Always specify storageClassName: longhorn

   spec:
     storageClassName: longhorn
   

Helm Template Syntax

1. Variable Assignment: Use $_ := set for complex assignments

   {{- $_ := set $ "varname" (include "homey.lookuporgensecret" (merge (dict "secretname" "secret-name") $)) }}
   

2. Include with Merge: Always pass $ as the last argument

   {{ include "homey.randomsecret" (merge (dict "secretname" "secret-name" "secretval" $secretval) $) }}
   

3. Quote Values from .Values: Use quote filter

   value: {{ .Values.homey.url | quote }}
   

4. Template Definitions: Define reusable templates in _definitions.yaml

   • homey.lookuporgensecret - Look up existing secrets or generate random
   • homey.randomsecret - Generate a random secret
   • homey.randHex - Generate random hex string

5. Template Spacing: Use whitespace control to avoid extra newlines

   {{- "leading minus" -}}  # No newline before
   {{ "trailing minus" -}}   # No newline after
   

Secret Management

1. Annotations: Always annotate managed secrets to prevent deletion

   annotations:
     "helm.sh/resource-policy": "keep"
   

2. Secret Generation Pattern:

   # Check for existing secret, create if not exists
   {{- $secretObj := (lookup "v1" "Secret" .Release.Namespace "secret-name") | default dict -}}
   {{- $secretData := (get $secretObj "data") | default dict -}}
   {{- $pass := (get $secretData "password") | default (randAlphaNum 32 | b64enc) -}}
   

3. Never hardcode secrets - Use the secret lookup pattern above

Config Files (files/ directory)

1. Go Templates in Configs: Use tpl function to process config files

   data:
     config.yml: |-
   {{ tpl (.Files.Get "files/authelia-config.yaml" | indent 4) . }}
   

2. Accessing Variables: Config files can access .Values.* and custom variables set in templates

Ingress Configuration

1. TLS: Always specify TLS with proper hosts and secret

   spec:
     ingressClassName: {{ .Values.homey.ingress_class }}
     tls:
       - hosts:
         - auth.{{ .Values.homey.url }}
         secretName: {{ .Values.homey.certname }}
   

2. Authelia Integration: Use auth snippets for protected ingresses

   annotations:
     nginx.ingress.kubernetes.io/auth-url: http://authelia.{{ .Release.Namespace }}.svc.cluster.local:9091/api/verify
     nginx.ingress.kubernetes.io/auth-signin: https://auth.{{ .Values.homey.url }}?rm=$request_method
   

Resource Organization

1. File Structure:

   • templates/_definitions.yaml - Helper templates (secrets, utilities)
   • templates/auth.yaml - Authentication services (OpenLDAP, Authelia, Gitea, Nextcloud, Radicale)
   • templates/media.yaml - Media services (Jellyfin, Transmission)
   • templates/phpldapadmin.yaml - LDAP admin interface

2. Manifest Order (within a file):

   • PersistentVolumeClaim
   • Secrets
   • ConfigMaps
   • Deployments
   • Services
   • Ingress

3. Unused Resources: Keep deprecated manifests in unused/ directory

Environment Variables

1. Naming: Use uppercase with underscores

   - name: LDAP_ORGANISATION
     value: {{ .Values.homey.organization }}
   

2. Value Sources: Prefer valueFrom.secretKeyRef over inline values

   - name: PASSWORD
     valueFrom:
       secretKeyRef:
         name: secret-name
         key: password
   

Volume Mounts

1. subPath: Use subPath for shared PVCs

   volumeMounts:
     - mountPath: /data
       subPath: service-name/data
   

2. Read-only ConfigMaps: Mark config mounts as read-only

   readOnly: true
   

Common Operations

Adding a New Service

1. Add values to values.yaml
2. Create/extend template in templates/
3. Add PVC if persistent storage needed
4. Add Ingress with appropriate annotations
5. Test with helm template .

Updating Secrets

Secrets are generated on first install. To regenerate:

kubectl delete secret <secret-name> -n homey
helm upgrade --install homey . -n homey

Debugging Templates

# Show all template variables available
helm template . --show-only templates/_helpers.tpl

# Render single template
helm template . --show-only templates/auth.yaml