Update helm setup docs #2040
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,37 +1,279 @@ | ||
| --- | ||
| title: "Kubernetes via Helm" | ||
| description: "Learn how to use Helm chart to install Digger on your Kubernetes cluster." | ||
| --- | ||
|
|
||
| **Prerequisites** | ||
| - You have extensive understanding of [Kubernetes](https://kubernetes.io/) | ||
| - Installed [Helm package manager](https://helm.sh/) version v3.11.3 or greater | ||
| - You have [kubectl](https://kubernetes.io/docs/reference/kubectl/kubectl/) installed and connected to your kubernetes cluster | ||
| - A domain name for ingress configuration | ||
| - A GitHub organization where you'll install the GitHub App | ||
|
|
||
| <Steps> | ||
| <Step title="Install Digger Helm chart"> | ||
| Install the `digger-backend` helm chart from GitHub Container Registry: | ||
|
|
||
| ```bash | ||
| helm install digger-backend oci://ghcr.io/diggerhq/helm-charts/digger-backend \ | ||
| --namespace digger \ | ||
| --create-namespace \ | ||
| --values values.yaml | ||
| ``` | ||
| </Step> | ||
|
|
||
| <Step title="Create Helm values"> | ||
| Create a `values.yaml` file. This will be used to configure settings for the Digger Helm chart. | ||
| 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. | ||
| </Step> | ||
|
|
||
| <Step title="Select Digger version"> | ||
| By default, the Digger version set in your helm chart will likely be outdated. | ||
| Choose the latest Digger docker image tag from the [releases page](https://github.com/diggerhq/digger/releases). | ||
|
|
||
| ```yaml values.yaml | ||
| digger: | ||
| image: | ||
| repository: registry.digger.dev/diggerhq/digger_backend | ||
| tag: "v0.6.106" # Select tag from GitHub releases | ||
| pullPolicy: IfNotPresent | ||
| ``` | ||
|
|
||
| <Warning> | ||
| Do not use the latest docker image tag in production deployments as they can introduce unexpected changes | ||
| </Warning> | ||
| </Step> | ||
|
|
||
| <Step title="Configure required secrets"> | ||
| Configure the required secrets for Digger. Note that GitHub App credentials will be filled after the initial setup. | ||
|
|
||
| ```yaml values.yaml | ||
| digger: | ||
| secret: | ||
| httpBasicAuthUsername: "admin" | ||
| httpBasicAuthPassword: "<strong-password>" | ||
| bearerAuthToken: "<strong-token>" | ||
| hostname: "digger.example.com" | ||
|
|
||
| # GitHub App credentials (filled after setup) | ||
| githubOrg: "" | ||
| githubAppID: "" # Note: uppercase ID | ||
| githubAppClientID: "" | ||
| githubAppClientSecret: "" | ||
| githubAppKeyFile: "" # base64 encoded private key | ||
| githubWebhookSecret: "" | ||
| ``` | ||
| </Step> | ||
|
|
||
| <Step title="Configure database"> | ||
| Choose your database configuration based on your environment: | ||
|
|
||
| <Tabs> | ||
| <Tab title="External PostgreSQL (Production)"> | ||
| For production environments, use an external PostgreSQL database: | ||
|
|
||
| ```yaml values.yaml | ||
| digger: | ||
| postgres: | ||
| user: "digger" | ||
| database: "digger" | ||
| host: "postgresql.example.com" | ||
| password: "secure-password" | ||
| sslmode: "require" # or "disable" | ||
| ``` | ||
| </Tab> | ||
|
|
||
| <Tab title="Built-in PostgreSQL (Testing Only)"> | ||
| For test or proof-of-concept purposes, you can use the built-in PostgreSQL: | ||
|
|
||
| ```yaml values.yaml | ||
| postgres: | ||
| enabled: true | ||
| secret: | ||
| postgresPassword: "<test-password>" | ||
|
Comment on lines
+92
to
+93
There was a problem hiding this comment. logic: The nested 'secret' structure under 'postgres' doesn't match the actual chart structure which expects 'postgres.secret.password' not 'postgres.secret.postgresPassword'. |
||
| ``` | ||
|
|
||
| <Warning> | ||
| Built-in PostgreSQL is only recommended for testing purposes | ||
| </Warning> | ||
| </Tab> | ||
| </Tabs> | ||
| </Step> | ||
|
|
||
| <Step title="Configure ingress"> | ||
| Configure ingress to route traffic to Digger (required for GitHub App setup): | ||
|
|
||
| ```yaml values.yaml | ||
| digger: | ||
| ingress: | ||
| enabled: true | ||
| host: "digger.example.com" # Your domain | ||
| annotations: | ||
| # Add annotations based on your ingress controller | ||
| # Example for nginx: | ||
| # kubernetes.io/ingress.class: "nginx" | ||
| # cert-manager.io/cluster-issuer: "letsencrypt-prod" | ||
| ``` | ||
| </Step> | ||
|
|
||
| <Step title="Initial deployment"> | ||
| Deploy Digger with the initial configuration: | ||
|
|
||
| ```bash | ||
| helm install digger-backend oci://ghcr.io/diggerhq/helm-charts/digger-backend \ | ||
| --namespace digger \ | ||
| --create-namespace \ | ||
| --values values.yaml | ||
| ``` | ||
|
|
||
| Wait for all pods to reach a running state: | ||
|
|
||
| ```bash | ||
| kubectl get pods -n digger | ||
| ``` | ||
| </Step> | ||
|
|
||
| <Step title="GitHub App setup"> | ||
| Navigate to your Digger hostname to create and configure the GitHub App: | ||
|
|
||
| 1. Go to `https://your-digger-hostname/github/setup` | ||
| 2. Follow the web interface to create your GitHub App | ||
| 3. Install the app in your GitHub organization | ||
| 4. Collect the generated credentials: | ||
| - GitHub App ID | ||
| - Client ID | ||
| - Client Secret | ||
| - Private Key (base64 encoded) | ||
| - Webhook Secret | ||
| </Step> | ||
|
|
||
| <Step title="Update configuration with GitHub App credentials"> | ||
| Add the GitHub App credentials to your `values.yaml` file: | ||
|
|
||
| ```yaml values.yaml | ||
| digger: | ||
| secret: | ||
| # ... existing configuration ... | ||
| githubOrg: "your-github-org" | ||
| githubAppID: "123456" | ||
| githubAppClientID: "Iv1.abc123def456" | ||
| githubAppClientSecret: "github_app_client_secret" | ||
| githubAppKeyFile: "LS0tLS1CRUdJTi..." # base64 encoded private key | ||
| githubWebhookSecret: "webhook_secret" | ||
| ``` | ||
|
|
||
| Then upgrade the Helm release: | ||
|
|
||
| ```bash | ||
| helm upgrade digger-backend oci://ghcr.io/diggerhq/helm-charts/digger-backend \ | ||
| --namespace digger \ | ||
| --values values.yaml | ||
| ``` | ||
| </Step> | ||
|
|
||
| <Step title="Access Digger"> | ||
| After deployment, wait for 2-5 minutes for all pods to reach a running state. | ||
| You can find the IP address/hostname by executing: | ||
|
|
||
| ```bash | ||
| kubectl get ingress -n digger | ||
| ``` | ||
|
|
||
| Access Digger at your configured hostname and verify the GitHub App is properly connected. | ||
| </Step> | ||
|
|
||
| <Step title="Upgrade your instance"> | ||
| To upgrade your instance of Digger, update the docker image tag in your Helm values and rerun: | ||
|
|
||
| ```bash | ||
| helm upgrade digger-backend oci://ghcr.io/diggerhq/helm-charts/digger-backend \ | ||
| --namespace digger \ | ||
| --values values.yaml | ||
| ``` | ||
|
|
||
| <Tip> | ||
| Always back up your database before each upgrade, especially in a production environment. | ||
| </Tip> | ||
| </Step> | ||
| </Steps> | ||
|
|
||
| ## Advanced Configuration | ||
|
|
||
| <Accordion title="Using existing secrets"> | ||
| If you prefer to manage secrets separately, you can reference an existing Kubernetes secret: | ||
|
|
||
| ```yaml values.yaml | ||
| digger: | ||
| secret: | ||
| useExistingSecret: true | ||
| existingSecretName: "digger-secrets" | ||
| ``` | ||
| </Accordion> | ||
|
|
||
| <Accordion title="Resource configuration"> | ||
| Configure resource limits and requests: | ||
|
|
||
| ```yaml values.yaml | ||
| digger: | ||
| resources: | ||
| requests: | ||
| cpu: 100m | ||
| memory: 128Mi | ||
| limits: | ||
| cpu: 500m | ||
| memory: 512Mi | ||
| ``` | ||
| </Accordion> | ||
|
|
||
| <Accordion title="Full values.yaml example"> | ||
| ```yaml values.yaml | ||
| digger: | ||
| image: | ||
| repository: registry.digger.dev/diggerhq/digger_backend | ||
| tag: "v0.6.106" | ||
| pullPolicy: IfNotPresent | ||
|
|
||
| service: | ||
| type: ClusterIP | ||
| port: 3000 | ||
|
|
||
| ingress: | ||
| enabled: true | ||
| host: "digger.example.com" | ||
| annotations: | ||
| kubernetes.io/ingress.class: "nginx" | ||
| cert-manager.io/cluster-issuer: "letsencrypt-prod" | ||
|
|
||
| secret: | ||
| httpBasicAuthUsername: "admin" | ||
| httpBasicAuthPassword: "secure-password-123" | ||
| bearerAuthToken: "secure-bearer-token-456" | ||
| hostname: "digger.example.com" | ||
|
|
||
| githubOrg: "your-github-org" | ||
| githubAppID: "123456" | ||
| githubAppClientID: "Iv1.abc123def456" | ||
| githubAppClientSecret: "github_app_client_secret" | ||
| githubAppKeyFile: "LS0tLS1CRUdJTi..." | ||
| githubWebhookSecret: "webhook_secret" | ||
|
|
||
| postgres: | ||
| user: "digger" | ||
| database: "digger" | ||
| host: "postgresql.example.com" | ||
| password: "postgres-password" | ||
| sslmode: "require" | ||
|
|
||
| resources: | ||
| requests: | ||
| cpu: 100m | ||
| memory: 128Mi | ||
| limits: | ||
| cpu: 500m | ||
| memory: 512Mi | ||
|
|
||
| # For testing only - use external database in production | ||
| postgres: | ||
| enabled: false | ||
| ``` | ||
| </Accordion> | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
logic: The secret key names in the documentation (camelCase) don't match the actual Helm chart expectations (UPPER_CASE with underscores). For example, the chart expects 'GITHUB_APP_ID' but the docs show 'githubAppID'.