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 ## Adding the Repository
```sh ```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 helm repo update
``` ```
## Installing the Chart ## Installing
The chart requires exactly one storage backend to be enabled. To install with
the SQLite backend:
```sh ```sh
# SQLite backend
helm install taskchampion-sync-server taskchampion/taskchampion-sync-server \ helm install taskchampion-sync-server taskchampion/taskchampion-sync-server \
--set sqlite.enabled=true --set sqlite.enabled=true
```
To install with the Postgres backend, provide the connection details: # PostgreSQL backend
```sh
helm install taskchampion-sync-server taskchampion/taskchampion-sync-server \ helm install taskchampion-sync-server taskchampion/taskchampion-sync-server \
--set postgres.enabled=true \ --set postgres.enabled=true \
--set postgres.host=my-postgres \ --set postgres.host=my-postgres \
--set postgres.database=taskchampion \ --set postgres.db=taskchampion \
--set postgres.username=myuser \ --set postgres.username=myuser \
--set postgres.password=mypassword --set postgres.password=mypassword
``` ```
Alternatively, pass an existing Secret name via `postgres.existingSecret`. The ## Storage Backends
secret must contain a `connection` key holding a [LibPQ-style connection
URI](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS).
## 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 ### SQLite
or gateway will terminate TLS and proxy HTTP traffic to the server container.
Enable one of the built-in options or configure your own:
```sh Mounts a volume at `sqlite.dataDir` (default `/var/lib/taskchampion-sync-server/data`).
# NGINX ingress The volume defaults to `emptyDir` but can be backed by a PVC or
--set ingress.enabled=true --set ingress.hosts[0]=taskchampion.example.com existing PersistentVolumeClaim:
# Gateway API HTTPRoute | Value | Description |
--set httpRoute.enabled=true \ |-------|-------------|
--set httpRoute.gateway=my-gateway \ | `sqlite.persistence.enabled` | Create a PVC (default: `false`) |
--set httpRoute.host=taskchampion.example.com | `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 Reference it via `clientIdSecret: "my-client-ids"`. The value is available to
newline-separated list of UUIDs and reference it: the server as `CLIENT_ID` and to the init container as `CLIENT_IDS`.
```sh ## Networking
--set clientIdSecret=my-client-ids-secret
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.

122
helm/taskchampion-sync-server/README.md
View File

@ -7,28 +7,55 @@ Deploy the [TaskChampion Sync Server](https://github.com/GothenburgBitFactory/ta
- Kubernetes 1.23+ - Kubernetes 1.23+
- Helm 3+ - Helm 3+
## Installing
```console
helm repo add taskchampion https://gothenburgbitfactory.org/taskchampion-sync-server
helm repo update
helm install my-release taskchampion/taskchampion-sync-server --set sqlite.enabled=true
```
## Storage Backends ## Storage Backends
Exactly one storage backend must be enabled. The chart will fail validation if both or neither are enabled. Exactly one storage backend must be enabled. The chart fails validation if neither or both are enabled.
### SQLite ### SQLite
```console | Parameter | Default | Description |
helm install my-release ./helm/taskchampion-sync-server -f helm/taskchampion-sync-server/examples/sqlite-values.yaml |-----------|---------|-------------|
``` | `sqlite.enabled` | `false` | Enable SQLite backend |
| `sqlite.dataDir` | `/var/lib/taskchampion-sync-server/data` | Data directory path |
| `sqlite.existingPV` | `""` | Use an existing PVC name |
| `sqlite.persistence.enabled` | `false` | Create a PVC |
| `sqlite.persistence.size` | `1Gi` | PVC size |
| `sqlite.persistence.accessMode` | `ReadWriteOnce` | PVC access mode |
| `sqlite.emptyDir` | — | emptyDir volume settings |
### PostgreSQL ### PostgreSQL
```console | Parameter | Default | Description |
helm install my-release ./helm/taskchampion-sync-server -f helm/taskchampion-sync-server/examples/postgres-values.yaml |-----------|---------|-------------|
``` | `postgres.enabled` | `false` | Enable PostgreSQL backend |
| `postgres.host` | `""` | PostgreSQL host |
| `postgres.port` | `5432` | PostgreSQL port |
| `postgres.db` | `taskchampion` | Database name |
| `postgres.username` | `""` | Database user |
| `postgres.password` | `""` | Database password |
| `postgres.sslMode` | `disable` | SSL mode |
| `postgres.existingSecret` | `""` | Use existing secret by name |
**Secret** — When `existingSecret` is empty (default), a secret named `{release-name}-connection` is created with a `conn` key. When set, the chart reads that secret. It accepts either a `conn` key with a full URI or individual keys (`host`, `port`, `username`, `password`, `database`) that override `postgres.*` values.
**Init container** — Enabled by default. Waits for PG readiness, downloads and applies the schema (from the chart's `appVersion` URL), and seeds client IDs if `clientIdSecret` is set. Override with `postgres.initContainer.schemaUrl`.
**Replicas** — Only apply with PostgreSQL (`replicas.enabled=true`, `replicas.count=N`). SQLite is single-replica.
## Secrets ## Secrets
The chart expects pre-created secrets referenced by name:
### Client ID Secret ### Client ID Secret
Restrict which client IDs the server accepts. Create a Secret with comma-separated UUIDs (base64-encoded) under a `client-ids` key:
```yaml ```yaml
apiVersion: v1 apiVersion: v1
kind: Secret kind: Secret
@ -39,22 +66,73 @@ data:
client-ids: <base64-encoded comma-separated UUIDs> client-ids: <base64-encoded comma-separated UUIDs>
``` ```
Reference it via `clientIdSecret: "my-client-ids"`. Reference via `clientIdSecret: "my-client-ids"`.
### PostgreSQL Secret ## Networking
For PostgreSQL, the chart can automatically create a secret with the connection string, or use an existing secret. The chart does not implement TLS. Terminate TLS at the ingress or gateway.
**Automatic Secret Creation**: ### Service
- When `postgres.existingSecret` is empty (default), the chart automatically creates a secret
- Secret is named using Helm naming convention: `release-name-taskchampion-sync-server`
- Secret contains only a `connection` key with the built connection string
**Existing Secret Usage**: | Parameter | Default | Description |
- When `postgres.existingSecret` is provided, the chart uses that secret |-----------|---------|-------------|
- The secret **must** contain a `connection` key with the PostgreSQL connection string | `service.type` | `ClusterIP` | Service type |
- If the secret doesn't have a `connection` key, the deployment will fail with a clear error | `service.port` | `8080` | Service port |
| `service.targetPort` | `8080` | Container port |
## Configuration ### Ingress (NGINX)
See [values.yaml](values.yaml) for all configurable options. | Parameter | Default | Description |
|-----------|---------|-------------|
| `ingress.enabled` | `false` | Enable NGINX ingress |
| `ingress.className` | `""` | Ingress class name |
| `ingress.annotations` | `{}` | Ingress annotations |
| `ingress.hosts` | `[]` | Host list |
| `ingress.tls` | `[]` | TLS configuration |
### HTTPRoute (Kubernetes Gateway API)
| Parameter | Default | Description |
|-----------|---------|-------------|
| `httpRoute.enabled` | `false` | Enable HTTPRoute |
| `httpRoute.parentRefs` | `[]` | Parent gateway references (primary) |
| `httpRoute.hostnames` | `[]` | Hostnames |
| `httpRoute.rules` | `[]` | Routing rules |
| `httpRoute.gateway` | `""` | (Deprecated) Single gateway name |
| `httpRoute.host` | `""` | (Deprecated) Single hostname |
| `httpRoute.path` | `"/"` | (Deprecated) Single path |
| `httpRoute.port` | `8080` | (Deprecated) Single port |
**Recommended** — use `parentRefs`, `hostnames`, `rules`. The deprecated
single-value fields (`gateway`, `host`, `path`, `port`) are used as a fallback
when the arrays are empty.
## ServiceAccount and RBAC
| Parameter | Default | Description |
|-----------|---------|-------------|
| `serviceAccount.create` | `true` | Create SA, Role, and RoleBinding |
| `serviceAccount.name` | `""` | Use existing SA name |
When created, the chart provisions a ServiceAccount, a Role with
`get`/`create`/`update`/`patch` on secrets, and a RoleBinding.
## Image Configuration
| Parameter | Default | Description |
|-----------|---------|-------------|
| `image.repo` | `ghcr.io/gothenburgbitfactory/taskchampion-sync-server` | Image repository |
| `image.tag` | `"0.7.0"` | Image tag |
| `image.pullPolicy` | `IfNotPresent` | Pull policy |
| `image.pullSecrets` | `[]` | Pull secrets |
PostgreSQL appends `-postgres` to the image repo automatically.
## Environment Variables
Custom env vars are passed via `env`. `DATA_DIR` (SQLite) and `conn`
(PostgreSQL) are set automatically and must not be set manually.
## Full Configuration
See [values.yaml](values.yaml).