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:
- Deployment (
apps/v1) — replicas, image, ports, environment, command/args, and volume mounts. - 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.enabledis 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 volumenameinservices. <name>.volumesmust 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 ofExternalSecretnames → spec (rendered underspec:).externalSecrets.generators— map of names → spec for external-secretsPasswordgenerators.
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.enabledgates both cert-manager/ExternalSecret generation and thetlsblock on the public ingress.