bp99/taskchampion-sync-server
1
0
Fork 0
forked from github-mirrorer/taskchampion-sync-server
Code Pull Requests Actions 1 Activity

Updating Helm documentation (#209)

Browse Source 
* Updating Helm documentation

* No version number
This commit is contained in:
Jansen Fuller
2026-05-29 22:06:53 +00:00
committed by GitHub
parent 1a4f1d94b6
commit 240af34978
2 changed files with 200 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

129
docs/src/usage/helm.md
View File

@ -5,56 +5,127 @@ A Helm chart is available for deploying taskchampion-sync-server on Kubernetes.
## Adding the Repository
```sh
helm repo add taskchampion https://gothenburgbitfactory.org/taskchampion-sync-server/helm-chart
helm repo add taskchampion https://gothenburgbitfactory.org/taskchampion-sync-server
helm repo update
```
## Installing the Chart
The chart requires exactly one storage backend to be enabled. To install with
the SQLite backend:
## Installing
```sh
# SQLite backend
helm install taskchampion-sync-server taskchampion/taskchampion-sync-server \
--set sqlite.enabled=true
```
To install with the Postgres backend, provide the connection details:
```sh
# PostgreSQL backend
helm install taskchampion-sync-server taskchampion/taskchampion-sync-server \
--set postgres.enabled=true \
--set postgres.host=my-postgres \
--set postgres.database=taskchampion \
--set postgres.db=taskchampion \
--set postgres.username=myuser \
--set postgres.password=mypassword
```
Alternatively, pass an existing Secret name via `postgres.existingSecret`. The
secret must contain a `connection` key holding a [LibPQ-style connection
URI](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS).
## Storage Backends
## Configuration
Exactly one storage backend must be enabled. The chart fails validation if
neither or both are enabled.
The chart does not implement TLS. The expectation is that a Kubernetes ingress
or gateway will terminate TLS and proxy HTTP traffic to the server container.
Enable one of the built-in options or configure your own:
### SQLite
```sh
# NGINX ingress
--set ingress.enabled=true --set ingress.hosts[0]=taskchampion.example.com
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:
# Gateway API HTTPRoute
--set httpRoute.enabled=true \
--set httpRoute.gateway=my-gateway \
--set httpRoute.host=taskchampion.example.com
| 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](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS)
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:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: my-client-ids
type: Opaque
data:
client-ids: <base64-encoded comma-separated UUIDs>
```
To restrict which client IDs the server accepts, create a Secret containing a
newline-separated list of UUIDs and reference it:
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`.
```sh
--set clientIdSecret=my-client-ids-secret
## Networking
The chart does not implement TLS. Terminate TLS at the ingress or gateway and
proxy HTTP to port 8080.
### Ingress (NGINX)
```yaml
ingress:
enabled: true
hosts:
- taskchampion.example.com
```
See the chart's `values.yaml` for the full set of configuration options.
### HTTPRoute (Kubernetes Gateway API)
Use `parentRefs`, `hostnames`, and `rules`:
```yaml
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](https://github.com/GothenburgBitFactory/taskchampion-sync-server/blob/main/helm/taskchampion-sync-server/values.yaml)
for all configurable options.