taskchampion-sync-server/docs/src/usage/helm.md

Helm

A Helm chart is available for deploying taskchampion-sync-server on Kubernetes.

Adding the Repository

helm repo add taskchampion https://gothenburgbitfactory.org/taskchampion-sync-server
helm repo update

Installing

# SQLite backend
helm install taskchampion-sync-server taskchampion/taskchampion-sync-server \
  --set sqlite.enabled=true

# PostgreSQL backend
helm install taskchampion-sync-server taskchampion/taskchampion-sync-server \
  --set postgres.enabled=true \
  --set postgres.host=my-postgres \
  --set postgres.db=taskchampion \
  --set postgres.username=myuser \
  --set postgres.password=mypassword

Storage Backends

Exactly one storage backend must be enabled. The chart fails validation if neither or both are enabled.

SQLite

Mounts a volume at sqlite.dataDir (default /var/lib/taskchampion-sync-server/data). The volume defaults to emptyDir but can be backed by a PVC or existing PersistentVolumeClaim:

Value	Description
sqlite.persistence.enabled	Create a PVC (default: false)
sqlite.existingPV	Use an existing PVC by name
sqlite.emptyDir	emptyDir volume settings (default fallback)

PostgreSQL

Creates a Deployment with optional replicas, an auto-generated or existing secret for the connection string, and an init container that waits for PostgreSQL, applies the schema, and optionally seeds client IDs.

Secret handling — When postgres.existingSecret is empty (default), the chart creates a secret named {release-name}-connection with a conn key. When set, the chart reads the named secret. It accepts either a conn key with a full LibPQ-style URI or individual fields (host, port, username, password, database) that override the corresponding postgres.* values.

Init container — Enabled by default. Waits for PG readiness, downloads the schema from https://raw.githubusercontent.com/GothenburgBitFactory/taskchampion-sync-server/v0.7.0/postgres/schema.sql, applies it, and seeds client IDs if clientIdSecret is set. Override the schema URL with postgres.initContainer.schemaUrl.

Replicas — Replicas only apply with PostgreSQL: replicas.enabled=true, replicas.count=N. SQLite is always single-replica.

Secrets

Client ID Secret

Optional. Restrict which client IDs the server accepts. Create a Secret with comma-separated UUIDs (base64-encoded) under a client-ids key:

apiVersion: v1
kind: Secret
metadata:
  name: my-client-ids
type: Opaque
data:
  client-ids: <base64-encoded comma-separated UUIDs>

Reference it via clientIdSecret: "my-client-ids". The value is available to the server as CLIENT_ID and to the init container as CLIENT_IDS.

Networking

The chart does not implement TLS. Terminate TLS at the ingress or gateway and proxy HTTP to port 8080.

Ingress (NGINX)

ingress:
  enabled: true
  hosts:
    - taskchampion.example.com

HTTPRoute (Kubernetes Gateway API)

Use parentRefs, hostnames, and rules:

httpRoute:
  enabled: true
  parentRefs:
    - name: my-gateway
  hostnames:
    - tasks.example.com
  rules:
    - path:
        type: PathPrefix
        value: /
      backendPort: 8080

The deprecated fields httpRoute.gateway, httpRoute.host, httpRoute.path, and httpRoute.port are used as a fallback when the structured arrays are empty.

ServiceAccount and RBAC

When serviceAccount.create is true (default), the chart creates a ServiceAccount, a Role with get/create/update/patch on secrets, and a RoleBinding. Set serviceAccount.name to use an existing SA.

Reference

See the chart's values.yaml for all configurable options.