# 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](../Readme.md#global-dns-configuration) 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: ```yaml 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: `). ### `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`): ```yaml 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 (`-nfs-`) plus a matching PVC. The volume `name` in `services. .volumes` must equal this volume key to bind. ```yaml 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: ```yaml 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. ```yaml 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. `.bob.cat`) instead of the root-qualified form (e.g. `.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 (`.`, 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-` Service. It is not wired into `ingress.yaml` by default; call it explicitly if you need VPN-only exposure. ```yaml 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.