Skip to content

Commit bf7552c

Browse files
ZIJZIJ
committed
Update helm setup docs
1 parent cbb7be7 commit bf7552c

File tree

1 file changed

+264
-22
lines changed

1 file changed

+264
-22
lines changed

‎docs/ce/self-host/deploy-helm.mdx

Lines changed: 264 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,279 @@
11
---
2-
title: 'Digger Helm Chart'
2+
title: "Kubernetes via Helm"
3+
description: "Learn how to use Helm chart to install Digger on your Kubernetes cluster."
34
---
45

5-
## Installation steps
6+
**Prerequisites**
7+
- You have extensive understanding of [Kubernetes](https://kubernetes.io/)
8+
- Installed [Helm package manager](https://helm.sh/) version v3.11.3 or greater
9+
- You have [kubectl](https://kubernetes.io/docs/reference/kubectl/kubectl/) installed and connected to your kubernetes cluster
10+
- A domain name for ingress configuration
11+
- A GitHub organization where you'll install the GitHub App
612

13+
<Steps>
14+
<Step title="Install Digger Helm chart">
15+
Install the `digger-backend` helm chart from GitHub Container Registry:
16+
17+
```bash
18+
helm install digger-backend oci://ghcr.io/diggerhq/helm-charts/digger-backend \
19+
--namespace digger \
20+
--create-namespace \
21+
--values values.yaml
22+
```
23+
</Step>
724

8-
1. Install the `digger-backend` helm chart from https://diggerhq.github.io/helm-charts/, leaving empty all the data related to the GitHub App
9-
2. Go to `your_digger_hostname/github/setup` to install and configure the GitHub App
10-
3. Configure in the helm values or in the external secret all the data related to the new GitHub app and upgrade the helm installation to reload the Digger application with the new configuration
25+
<Step title="Create Helm values">
26+
Create a `values.yaml` file. This will be used to configure settings for the Digger Helm chart.
27+
To explore all configurable properties, check the [values.yaml](https://github.com/diggerhq/digger/blob/develop/helm-charts/digger-backend/values.yaml) file in the repository.
28+
</Step>
1129

12-
## Configuration Details
30+
<Step title="Select Digger version">
31+
By default, the Digger version set in your helm chart will likely be outdated.
32+
Choose the latest Digger docker image tag from the [releases page](https://github.com/diggerhq/digger/releases).
33+
34+
```yaml values.yaml
35+
digger:
36+
image:
37+
repository: registry.digger.dev/diggerhq/digger_backend
38+
tag: "v0.6.106" # Select tag from GitHub releases
39+
pullPolicy: IfNotPresent
40+
```
41+
42+
<Warning>
43+
Do not use the latest docker image tag in production deployments as they can introduce unexpected changes
44+
</Warning>
45+
</Step>
1346

14-
To configure the Digger backend deployment with the Helm chart, you'll need to set several values in the `values.yaml` file. Below are the key configurations to consider:
47+
<Step title="Configure required secrets">
48+
Configure the required secrets for Digger. Note that GitHub App credentials will be filled after the initial setup.
49+
50+
```yaml values.yaml
51+
digger:
52+
secret:
53+
httpBasicAuthUsername: "admin"
54+
httpBasicAuthPassword: "<strong-password>"
55+
bearerAuthToken: "<strong-token>"
56+
hostname: "digger.example.com"
57+
58+
# GitHub App credentials (filled after setup)
59+
githubOrg: ""
60+
githubAppID: "" # Note: uppercase ID
61+
githubAppClientID: ""
62+
githubAppClientSecret: ""
63+
githubAppKeyFile: "" # base64 encoded private key
64+
githubWebhookSecret: ""
65+
```
66+
</Step>
1567

16-
- `digger.image.repository`: The Docker image repository for the Digger backend (e.g., `registry.digger.dev/diggerhq/digger_backend`).
17-
- `digger.image.tag`: The specific version tag of the Docker image to deploy (e.g., `"v0.4.2"`).
68+
<Step title="Configure database">
69+
Choose your database configuration based on your environment:
70+
71+
<Tabs>
72+
<Tab title="External PostgreSQL (Production)">
73+
For production environments, use an external PostgreSQL database:
74+
75+
```yaml values.yaml
76+
digger:
77+
postgres:
78+
user: "digger"
79+
database: "digger"
80+
host: "postgresql.example.com"
81+
password: "secure-password"
82+
sslmode: "require" # or "disable"
83+
```
84+
</Tab>
85+
86+
<Tab title="Built-in PostgreSQL (Testing Only)">
87+
For test or proof-of-concept purposes, you can use the built-in PostgreSQL:
88+
89+
```yaml values.yaml
90+
postgres:
91+
enabled: true
92+
secret:
93+
postgresPassword: "<test-password>"
94+
```
95+
96+
<Warning>
97+
Built-in PostgreSQL is only recommended for testing purposes
98+
</Warning>
99+
</Tab>
100+
</Tabs>
101+
</Step>
18102

19-
- `digger.service.type`: The type of Kubernetes service to create, such as `ClusterIP`, `NodePort`, or `LoadBalancer`.
20-
- `digger.service.port`: The port number that the service will expose (e.g., `3000`).
103+
<Step title="Configure ingress">
104+
Configure ingress to route traffic to Digger (required for GitHub App setup):
105+
106+
```yaml values.yaml
107+
digger:
108+
ingress:
109+
enabled: true
110+
host: "digger.example.com" # Your domain
111+
annotations:
112+
# Add annotations based on your ingress controller
113+
# Example for nginx:
114+
# kubernetes.io/ingress.class: "nginx"
115+
# cert-manager.io/cluster-issuer: "letsencrypt-prod"
116+
```
117+
</Step>
21118

22-
- `digger.ingress.enabled`: Set to `true` to create an Ingress for the service.
23-
- `digger.annotations`: Add the needed annotations based on your ingress controller configuration.
24-
- `digger.ingress.host`: The hostname to use for the Ingress resource (e.g., `digger-backend.test`).
25-
- `digger.ingress.path`: The path for the Ingress resource (e.g., `/`).
26-
- `digger.ingress.tls.secretName`: The name of the TLS secret to use for Ingress encryption (e.g., `digger-backend-tls`).
119+
<Step title="Initial deployment">
120+
Deploy Digger with the initial configuration:
121+
122+
```bash
123+
helm install digger-backend oci://ghcr.io/diggerhq/helm-charts/digger-backend \
124+
--namespace digger \
125+
--create-namespace \
126+
--values values.yaml
127+
```
128+
129+
Wait for all pods to reach a running state:
130+
131+
```bash
132+
kubectl get pods -n digger
133+
```
134+
</Step>
27135

28-
- `digger.secret.*`: Various secrets needed for the application, such as `HTTP_BASIC_AUTH_PASSWORD` and `BEARER_AUTH_TOKEN`. You can provide them directly or reference an existing Kubernetes secret by setting `useExistingSecret` to `true` and specifying `existingSecretName`.
136+
<Step title="GitHub App setup">
137+
Navigate to your Digger hostname to create and configure the GitHub App:
138+
139+
1. Go to `https://your-digger-hostname/github/setup`
140+
2. Follow the web interface to create your GitHub App
141+
3. Install the app in your GitHub organization
142+
4. Collect the generated credentials:
143+
- GitHub App ID
144+
- Client ID
145+
- Client Secret
146+
- Private Key (base64 encoded)
147+
- Webhook Secret
148+
</Step>
29149

30-
- `digger.postgres.*`: If you're using an external Postgres database, configure the `user`, `database`, and `host` accordingly. Ensure you provide the `password` either directly or through an existing secret in the `secret.*` section.
150+
<Step title="Update configuration with GitHub App credentials">
151+
Add the GitHub App credentials to your `values.yaml` file:
152+
153+
```yaml values.yaml
154+
digger:
155+
secret:
156+
# ... existing configuration ...
157+
githubOrg: "your-github-org"
158+
githubAppID: "123456"
159+
githubAppClientID: "Iv1.abc123def456"
160+
githubAppClientSecret: "github_app_client_secret"
161+
githubAppKeyFile: "LS0tLS1CRUdJTi..." # base64 encoded private key
162+
githubWebhookSecret: "webhook_secret"
163+
```
164+
165+
Then upgrade the Helm release:
166+
167+
```bash
168+
helm upgrade digger-backend oci://ghcr.io/diggerhq/helm-charts/digger-backend \
169+
--namespace digger \
170+
--values values.yaml
171+
```
172+
</Step>
31173

32-
Remember to replace placeholders and default values with your specific, sensitive information before deploying the chart. For example, it's essential to generate a strong `bearerAuthToken` and `postgresPassword` rather than using the defaults for security reasons.
174+
<Step title="Access Digger">
175+
After deployment, wait for 2-5 minutes for all pods to reach a running state.
176+
You can find the IP address/hostname by executing:
177+
178+
```bash
179+
kubectl get ingress -n digger
180+
```
181+
182+
Access Digger at your configured hostname and verify the GitHub App is properly connected.
183+
</Step>
33184

34-
You can also deploy a PostgreSQL database ONLY FOR TEST PURPOSES configuring the `postgres.*` section:
185+
<Step title="Upgrade your instance">
186+
To upgrade your instance of Digger, update the docker image tag in your Helm values and rerun:
187+
188+
```bash
189+
helm upgrade digger-backend oci://ghcr.io/diggerhq/helm-charts/digger-backend \
190+
--namespace digger \
191+
--values values.yaml
192+
```
193+
194+
<Tip>
195+
Always back up your database before each upgrade, especially in a production environment.
196+
</Tip>
197+
</Step>
198+
</Steps>
35199

36-
- `postgres.enabled`: Set to `true` if you want to deploy a postgres database
37-
- `postgres.secret.*`: As for the digger secret, you can pass the `postgres` user password directly or through an existing secret
200+
## Advanced Configuration
201+
202+
<Accordion title="Using existing secrets">
203+
If you prefer to manage secrets separately, you can reference an existing Kubernetes secret:
204+
205+
```yaml values.yaml
206+
digger:
207+
secret:
208+
useExistingSecret: true
209+
existingSecretName: "digger-secrets"
210+
```
211+
</Accordion>
212+
213+
<Accordion title="Resource configuration">
214+
Configure resource limits and requests:
215+
216+
```yaml values.yaml
217+
digger:
218+
resources:
219+
requests:
220+
cpu: 100m
221+
memory: 128Mi
222+
limits:
223+
cpu: 500m
224+
memory: 512Mi
225+
```
226+
</Accordion>
227+
228+
<Accordion title="Full values.yaml example">
229+
```yaml values.yaml
230+
digger:
231+
image:
232+
repository: registry.digger.dev/diggerhq/digger_backend
233+
tag: "v0.6.106"
234+
pullPolicy: IfNotPresent
235+
236+
service:
237+
type: ClusterIP
238+
port: 3000
239+
240+
ingress:
241+
enabled: true
242+
host: "digger.example.com"
243+
annotations:
244+
kubernetes.io/ingress.class: "nginx"
245+
cert-manager.io/cluster-issuer: "letsencrypt-prod"
246+
247+
secret:
248+
httpBasicAuthUsername: "admin"
249+
httpBasicAuthPassword: "secure-password-123"
250+
bearerAuthToken: "secure-bearer-token-456"
251+
hostname: "digger.example.com"
252+
253+
githubOrg: "your-github-org"
254+
githubAppID: "123456"
255+
githubAppClientID: "Iv1.abc123def456"
256+
githubAppClientSecret: "github_app_client_secret"
257+
githubAppKeyFile: "LS0tLS1CRUdJTi..."
258+
githubWebhookSecret: "webhook_secret"
259+
260+
postgres:
261+
user: "digger"
262+
database: "digger"
263+
host: "postgresql.example.com"
264+
password: "postgres-password"
265+
sslmode: "require"
266+
267+
resources:
268+
requests:
269+
cpu: 100m
270+
memory: 128Mi
271+
limits:
272+
cpu: 500m
273+
memory: 512Mi
274+
275+
# For testing only - use external database in production
276+
postgres:
277+
enabled: false
278+
```
279+
</Accordion>

0 commit comments

Comments
 (0)