Files
2026-08-31 10:57:52 -04:00
..
2026-02-11 10:00:26 -05:00
2025-08-04 13:47:31 -04:00
2026-08-31 10:57:52 -04:00
2025-10-04 15:50:37 -04:00

compose-app

A generic Helm chart that takes a compose-like YAML declaration and renders one Deployment + Service pair per service entry, plus optional Ingresses, volumes, and secrets. It is designed as a reusable building block for deploying applications "the homelab way" (Traefik + cert-manager + external-secrets + gethomepage discovery) without writing a bespoke chart each time.


What it creates

For each entry in services:

  1. Deployment (apps/v1) — replicas, image, ports, environment, command/args, and volume mounts.
  2. Service (v1) — ClusterIP by default, exposing the declared ports.

Additionally, based on the other values:

  • PersistentVolumes / PersistentVolumeClaims for each entry in volumes (supports NFS-backed volumes).
  • Secrets for each entry in secrets.
  • ExternalSecrets and Password generators (external-secrets) based on externalSecrets.
  • Ingresses when ingress.enabled is true.

values.yaml reference

global

Shared cluster configuration, most importantly global.dns, which drives the ingress hostnames and TLS. See the repo root Readme for the full DNS table. global.dns.tls.enabled must be true for TLS resources to be generated.

services

A map of service name → service definition:

services:
  my-app:
    image: myorg/my-app:latest          # container image (required)
    replicas: 2                          # default 1
    imagePullPolicy: Always              # default "Always"
    labels:                              # optional, set as Deployment annotations
      - "key=value"
    ports:                               # list of container ports
      - name: http                       # default "http"
        port: 8080                       # containerPort (required)
        protocol: TCP                    # default "TCP"
    environment:                         # key/value env vars
      FOO: bar
    envFrom:                             # list of configMap/secret refs
      - configMapRef:
          name: my-config
    command: []                          # list of command args
    args: []                             # list of args
    volumes:                             # map: volumeName -> mount path; PVC is expected to exist
      data: /var/lib/app
    serviceAnnotations: {}               # annotations applied to the Service
    serviceType: ClusterIP               # default "ClusterIP"

Each rendered Service points at the matching Deployment (selector: app: <name>).

volumes

A map of volume name → volume definition. Entries produce a PersistentVolumeClaim (with the entry's name). Two forms are supported:

  • Standard PVC (no type):

    volumes:
      data:
        size: 10Gi                 # default "1Gi"
        accessMode: ReadWriteOnce  # default "ReadWriteOnce"
        type: ""                   # optional storageClassName when set
    
  • NFS-backed (type: nfs): renders a PersistenteVolume bound by name (<namespace>-nfs-<hash>) plus a matching PVC. The volume name in services. <name>.volumes must equal this volume key to bind.

    volumes:
      media:
        type: nfs
        server: nfs-server.local
        path: /export/media
    

secrets

A map of secret name → list of entries. Each entry creates a string key/value, plus optional aliases that reference the same value:

secrets:
  my-secret:
    - name: PASSWORD
      value: "s3cr3t"
      aliases:           # optional extra keys with the same value
        - API_TOKEN

externalSecrets

  • externalSecrets.secrets — map of ExternalSecret names → spec (rendered under spec:).
  • externalSecrets.generators — map of names → spec for external-secrets Password generators.
externalSecrets:
  generators:
    db-pass:
      length: 24
  secrets:
    db-credentials:
      secretStoreRef:
        kind: SecretStore
        name: vault
      data:
        - secretKey: password
          remoteRef:
            key: db
            property: password

ingress

Ingressing is handled by a shared template (homelab.ingress). Set ingress.enabled: true and pass the following:

Key Default Description
prefix (required) Host prefix; the first dotted label is used as the subdomain, the rest as a "lead prefix".
service (required) Name of the Service to route to.
port 80 Backend service port.
path / Backend path (pathType: Prefix).
middleware ingress-https-redirect@kubernetescrd Traefik middleware name.
useSecondaryDomain false Use the secondary DNS root/domain instead of the primary.
useDirectPrefix false When true, output uses the bare primary domain (e.g. <prefix>.bob.cat) instead of the root-qualified form (e.g. <prefix>.gr.bob.cat).
useWildCard global.dns.tls.useWildCard Override wildcard TLS behavior for this ingress.
disableExternalIngress false Skip the public ingress (only the internal one is created).
group Unassigned gethomepage group label.
description — gethomepage description.
icon homepage.png gethomepage icon.
widget — Map rendered as gethomepage.dev/widget.* annotations.
annotations {} Extra annotations applied to both ingresses.
health — Suffix appended to the gethomepage siteMonitor probe URL.

The homelab.ingress template always creates an internal ingress (<prefix>.<global.dns.internalPrefix>, e.g. app.k3s.internal), and — unless disableExternalIngress is set — a public ingress (e.g. app.gr.bob.cat), with optional TLS and gethomepage annotations.

There is also a homelab.ingress.tailscale template for creating a Tailscale (ingressClassName: tailscale) ingress plus a tailscale-<name> Service. It is not wired into ingress.yaml by default; call it explicitly if you need VPN-only exposure.

ingress:
  enabled: true
  prefix: app
  service: my-app
  port: 8080
  group: Media

Notes

  • Volume mounts reference PVCs by name; for standard volumes a matching PVC is generated for you, for NFS the generated PVC/PV must match the service's mount name.
  • global.dns.tls.enabled gates both cert-manager/ExternalSecret generation and the tls block on the public ingress.