Skip to content

Commit 240af34

Browse files
jansenfullerjansenfuller
authored
Updating Helm documentation (#209)
* Updating Helm documentation * No version number
1 parent 1a4f1d9 commit 240af34

2 files changed

Lines changed: 200 additions & 51 deletions

File tree

‎docs/src/usage/helm.md‎

Lines changed: 100 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -5,56 +5,127 @@ A Helm chart is available for deploying taskchampion-sync-server on Kubernetes.
55
## Adding the Repository
66

77
```sh
8-
helm repo add taskchampion https://gothenburgbitfactory.org/taskchampion-sync-server/helm-chart
8+
helm repo add taskchampion https://gothenburgbitfactory.org/taskchampion-sync-server
99
helm repo update
1010
```
1111

12-
## Installing the Chart
13-
14-
The chart requires exactly one storage backend to be enabled. To install with
15-
the SQLite backend:
12+
## Installing
1613

1714
```sh
15+
# SQLite backend
1816
helm install taskchampion-sync-server taskchampion/taskchampion-sync-server \
1917
--set sqlite.enabled=true
20-
```
21-
22-
To install with the Postgres backend, provide the connection details:
2318

24-
```sh
19+
# PostgreSQL backend
2520
helm install taskchampion-sync-server taskchampion/taskchampion-sync-server \
2621
--set postgres.enabled=true \
2722
--set postgres.host=my-postgres \
28-
--set postgres.database=taskchampion \
23+
--set postgres.db=taskchampion \
2924
--set postgres.username=myuser \
3025
--set postgres.password=mypassword
3126
```
3227

33-
Alternatively, pass an existing Secret name via `postgres.existingSecret`. The
34-
secret must contain a `connection` key holding a [LibPQ-style connection
35-
URI](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS).
28+
## Storage Backends
3629

37-
## Configuration
30+
Exactly one storage backend must be enabled. The chart fails validation if
31+
neither or both are enabled.
3832

39-
The chart does not implement TLS. The expectation is that a Kubernetes ingress
40-
or gateway will terminate TLS and proxy HTTP traffic to the server container.
41-
Enable one of the built-in options or configure your own:
33+
### SQLite
4234

43-
```sh
44-
# NGINX ingress
45-
--set ingress.enabled=true --set ingress.hosts[0]=taskchampion.example.com
35+
Mounts a volume at `sqlite.dataDir` (default `/var/lib/taskchampion-sync-server/data`).
36+
The volume defaults to `emptyDir` but can be backed by a PVC or
37+
existing PersistentVolumeClaim:
38+
39+
| Value | Description |
40+
|-------|-------------|
41+
| `sqlite.persistence.enabled` | Create a PVC (default: `false`) |
42+
| `sqlite.existingPV` | Use an existing PVC by name |
43+
| `sqlite.emptyDir` | emptyDir volume settings (default fallback) |
44+
45+
### PostgreSQL
46+
47+
Creates a Deployment with optional replicas, an auto-generated or existing
48+
secret for the connection string, and an init container that waits for
49+
PostgreSQL, applies the schema, and optionally seeds client IDs.
50+
51+
**Secret handling** — When `postgres.existingSecret` is empty (default), the
52+
chart creates a secret named `{release-name}-connection` with a `conn` key.
53+
When set, the chart reads the named secret. It accepts either a `conn` key
54+
with a full [LibPQ-style URI](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING-URIS)
55+
or individual fields (`host`, `port`, `username`, `password`, `database`) that
56+
override the corresponding `postgres.*` values.
57+
58+
**Init container** — Enabled by default. Waits for PG readiness, downloads
59+
the schema from `https://raw.githubusercontent.com/GothenburgBitFactory/taskchampion-sync-server/v0.7.0/postgres/schema.sql`,
60+
applies it, and seeds client IDs if `clientIdSecret` is set. Override the
61+
schema URL with `postgres.initContainer.schemaUrl`.
62+
63+
**Replicas** — Replicas only apply with PostgreSQL:
64+
`replicas.enabled=true`, `replicas.count=N`. SQLite is always single-replica.
65+
66+
## Secrets
4667

47-
# Gateway API HTTPRoute
48-
--set httpRoute.enabled=true \
49-
--set httpRoute.gateway=my-gateway \
50-
--set httpRoute.host=taskchampion.example.com
68+
### Client ID Secret
69+
70+
Optional. Restrict which client IDs the server accepts. Create a Secret with
71+
comma-separated UUIDs (base64-encoded) under a `client-ids` key:
72+
73+
```yaml
74+
apiVersion: v1
75+
kind: Secret
76+
metadata:
77+
name: my-client-ids
78+
type: Opaque
79+
data:
80+
client-ids: <base64-encoded comma-separated UUIDs>
5181
```
5282
53-
To restrict which client IDs the server accepts, create a Secret containing a
54-
newline-separated list of UUIDs and reference it:
83+
Reference it via `clientIdSecret: "my-client-ids"`. The value is available to
84+
the server as `CLIENT_ID` and to the init container as `CLIENT_IDS`.
5585

56-
```sh
57-
--set clientIdSecret=my-client-ids-secret
86+
## Networking
87+
88+
The chart does not implement TLS. Terminate TLS at the ingress or gateway and
89+
proxy HTTP to port 8080.
90+
91+
### Ingress (NGINX)
92+
93+
```yaml
94+
ingress:
95+
enabled: true
96+
hosts:
97+
- taskchampion.example.com
5898
```
5999

60-
See the chart's `values.yaml` for the full set of configuration options.
100+
### HTTPRoute (Kubernetes Gateway API)
101+
102+
Use `parentRefs`, `hostnames`, and `rules`:
103+
104+
```yaml
105+
httpRoute:
106+
enabled: true
107+
parentRefs:
108+
- name: my-gateway
109+
hostnames:
110+
- tasks.example.com
111+
rules:
112+
- path:
113+
type: PathPrefix
114+
value: /
115+
backendPort: 8080
116+
```
117+
118+
The deprecated fields `httpRoute.gateway`, `httpRoute.host`,
119+
`httpRoute.path`, and `httpRoute.port` are used as a fallback when the
120+
structured arrays are empty.
121+
122+
### ServiceAccount and RBAC
123+
124+
When `serviceAccount.create` is `true` (default), the chart creates a
125+
ServiceAccount, a Role with `get`/`create`/`update`/`patch` on secrets, and
126+
a RoleBinding. Set `serviceAccount.name` to use an existing SA.
127+
128+
## Reference
129+
130+
See the chart's [values.yaml](https://github.com/GothenburgBitFactory/taskchampion-sync-server/blob/main/helm/taskchampion-sync-server/values.yaml)
131+
for all configurable options.

‎helm/taskchampion-sync-server/README.md‎

Lines changed: 100 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -7,28 +7,55 @@ Deploy the [TaskChampion Sync Server](https://github.com/GothenburgBitFactory/ta
77
- Kubernetes 1.23+
88
- Helm 3+
99

10+
## Installing
11+
12+
```console
13+
helm repo add taskchampion https://gothenburgbitfactory.org/taskchampion-sync-server
14+
helm repo update
15+
helm install my-release taskchampion/taskchampion-sync-server --set sqlite.enabled=true
16+
```
17+
1018
## Storage Backends
1119

12-
Exactly one storage backend must be enabled. The chart will fail validation if both or neither are enabled.
20+
Exactly one storage backend must be enabled. The chart fails validation if neither or both are enabled.
1321

1422
### SQLite
1523

16-
```console
17-
helm install my-release ./helm/taskchampion-sync-server -f helm/taskchampion-sync-server/examples/sqlite-values.yaml
18-
```
24+
| Parameter | Default | Description |
25+
|-----------|---------|-------------|
26+
| `sqlite.enabled` | `false` | Enable SQLite backend |
27+
| `sqlite.dataDir` | `/var/lib/taskchampion-sync-server/data` | Data directory path |
28+
| `sqlite.existingPV` | `""` | Use an existing PVC name |
29+
| `sqlite.persistence.enabled` | `false` | Create a PVC |
30+
| `sqlite.persistence.size` | `1Gi` | PVC size |
31+
| `sqlite.persistence.accessMode` | `ReadWriteOnce` | PVC access mode |
32+
| `sqlite.emptyDir` | — | emptyDir volume settings |
1933

2034
### PostgreSQL
2135

22-
```console
23-
helm install my-release ./helm/taskchampion-sync-server -f helm/taskchampion-sync-server/examples/postgres-values.yaml
24-
```
36+
| Parameter | Default | Description |
37+
|-----------|---------|-------------|
38+
| `postgres.enabled` | `false` | Enable PostgreSQL backend |
39+
| `postgres.host` | `""` | PostgreSQL host |
40+
| `postgres.port` | `5432` | PostgreSQL port |
41+
| `postgres.db` | `taskchampion` | Database name |
42+
| `postgres.username` | `""` | Database user |
43+
| `postgres.password` | `""` | Database password |
44+
| `postgres.sslMode` | `disable` | SSL mode |
45+
| `postgres.existingSecret` | `""` | Use existing secret by name |
2546

26-
## Secrets
47+
**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.
48+
49+
**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`.
2750

28-
The chart expects pre-created secrets referenced by name:
51+
**Replicas** — Only apply with PostgreSQL (`replicas.enabled=true`, `replicas.count=N`). SQLite is single-replica.
52+
53+
## Secrets
2954

3055
### Client ID Secret
3156

57+
Restrict which client IDs the server accepts. Create a Secret with comma-separated UUIDs (base64-encoded) under a `client-ids` key:
58+
3259
```yaml
3360
apiVersion: v1
3461
kind: Secret
@@ -39,22 +66,73 @@ data:
3966
client-ids: <base64-encoded comma-separated UUIDs>
4067
```
4168
42-
Reference it via `clientIdSecret: "my-client-ids"`.
69+
Reference via `clientIdSecret: "my-client-ids"`.
70+
71+
## Networking
72+
73+
The chart does not implement TLS. Terminate TLS at the ingress or gateway.
74+
75+
### Service
76+
77+
| Parameter | Default | Description |
78+
|-----------|---------|-------------|
79+
| `service.type` | `ClusterIP` | Service type |
80+
| `service.port` | `8080` | Service port |
81+
| `service.targetPort` | `8080` | Container port |
82+
83+
### Ingress (NGINX)
84+
85+
| Parameter | Default | Description |
86+
|-----------|---------|-------------|
87+
| `ingress.enabled` | `false` | Enable NGINX ingress |
88+
| `ingress.className` | `""` | Ingress class name |
89+
| `ingress.annotations` | `{}` | Ingress annotations |
90+
| `ingress.hosts` | `[]` | Host list |
91+
| `ingress.tls` | `[]` | TLS configuration |
92+
93+
### HTTPRoute (Kubernetes Gateway API)
94+
95+
| Parameter | Default | Description |
96+
|-----------|---------|-------------|
97+
| `httpRoute.enabled` | `false` | Enable HTTPRoute |
98+
| `httpRoute.parentRefs` | `[]` | Parent gateway references (primary) |
99+
| `httpRoute.hostnames` | `[]` | Hostnames |
100+
| `httpRoute.rules` | `[]` | Routing rules |
101+
| `httpRoute.gateway` | `""` | (Deprecated) Single gateway name |
102+
| `httpRoute.host` | `""` | (Deprecated) Single hostname |
103+
| `httpRoute.path` | `"/"` | (Deprecated) Single path |
104+
| `httpRoute.port` | `8080` | (Deprecated) Single port |
105+
106+
**Recommended** — use `parentRefs`, `hostnames`, `rules`. The deprecated
107+
single-value fields (`gateway`, `host`, `path`, `port`) are used as a fallback
108+
when the arrays are empty.
109+
110+
## ServiceAccount and RBAC
111+
112+
| Parameter | Default | Description |
113+
|-----------|---------|-------------|
114+
| `serviceAccount.create` | `true` | Create SA, Role, and RoleBinding |
115+
| `serviceAccount.name` | `""` | Use existing SA name |
116+
117+
When created, the chart provisions a ServiceAccount, a Role with
118+
`get`/`create`/`update`/`patch` on secrets, and a RoleBinding.
119+
120+
## Image Configuration
43121

44-
### PostgreSQL Secret
122+
| Parameter | Default | Description |
123+
|-----------|---------|-------------|
124+
| `image.repo` | `ghcr.io/gothenburgbitfactory/taskchampion-sync-server` | Image repository |
125+
| `image.tag` | `"0.7.0"` | Image tag |
126+
| `image.pullPolicy` | `IfNotPresent` | Pull policy |
127+
| `image.pullSecrets` | `[]` | Pull secrets |
45128

46-
For PostgreSQL, the chart can automatically create a secret with the connection string, or use an existing secret.
129+
PostgreSQL appends `-postgres` to the image repo automatically.
47130

48-
**Automatic Secret Creation**:
49-
- When `postgres.existingSecret` is empty (default), the chart automatically creates a secret
50-
- Secret is named using Helm naming convention: `release-name-taskchampion-sync-server`
51-
- Secret contains only a `connection` key with the built connection string
131+
## Environment Variables
52132

53-
**Existing Secret Usage**:
54-
- When `postgres.existingSecret` is provided, the chart uses that secret
55-
- The secret **must** contain a `connection` key with the PostgreSQL connection string
56-
- If the secret doesn't have a `connection` key, the deployment will fail with a clear error
133+
Custom env vars are passed via `env`. `DATA_DIR` (SQLite) and `conn`
134+
(PostgreSQL) are set automatically and must not be set manually.
57135

58-
## Configuration
136+
## Full Configuration
59137

60-
See [values.yaml](values.yaml) for all configurable options.
138+
See [values.yaml](values.yaml).

0 commit comments

Comments
 (0)