> ## Documentation Index
> Fetch the complete documentation index at: https://docs.digitalasset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Kubernetes installation instructions for the Covalidation Service.

## Overview

The **Covalidation Service** enables a validator to participate as a **covalidator** by synchronizing DARs (Daml Archive files) from a primary validator and replicating them into its own participant.

## Setup

Before installing the chart, ensure you have:

<Card title="Prerequisites">
  * Access to your GitHub organization
  * A primary validator willing to share DARs
  * A Kubernetes cluster
  * A Kubernetes namespace for the deployment
  * Helm 3.x
  * Kubernetes Secrets containing:
    * GitHub App private key
    * Participant OIDC client secret
</Card>

Before deploying the service, a GitHub App must be created within your organization's GitHub account. The primary validator installs this application into the repository containing the shared DARs, allowing the Covalidation Service to securely synchronize application packages.

The deployment process consists of three stages:

```mermaid theme={null}
flowchart LR

A[Create GitHub App in your organization] --> B[Primary Validator installs App into shared DAR repository]
B --> C[Deploy Covalidation Service with appropriate configuration]
```

## Configure GitHub Access

## Create a GitHub App

> **Important**
>
> Creating a GitHub App requires GitHub Organization Owner permissions.

> **Note**
>
> A single GitHub App can be reused for multiple Covalidation Service deployments within the same organization.

### Create the application

Navigate to:

**Organization Settings → Developer Settings → GitHub Apps**

Select **New GitHub App**.

### Configure the application

Use the following settings.

| Setting                          | Value                                                                        |
| -------------------------------- | ---------------------------------------------------------------------------- |
| Name                             | `<Company Name> Covalidation`                                                |
| Description                      | A description such as `Used by the Covalidation Service to synchronize DARs` |
| Homepage URL                     | Your organization's website                                                  |
| Expire user authorization tokens | Disabled                                                                     |
| Webhooks                         | Disabled                                                                     |

### Repository Permissions

Configure the following permissions.

| Permission | Access       |
| ---------- | ------------ |
| Contents   | Read-only    |
| Webhooks   | Read & Write |

### Installation Scope

Select:

**Any account**

Then create the application.

***

### Record Required Information

After the application has been created, save the following values.

| Item        | Required For                  |
| ----------- | ----------------------------- |
| Public Link | Sent to the primary validator |
| App ID      | Helm configuration            |
| Private Key | Kubernetes Secret             |

### Generate Private Key

Generate a **Private Key** and store it as a Kubernetes Secret in the namespace where the chart will be installed.

Example:

```bash theme={null}
kubectl create secret generic github-app-private-key \
  --from-file=private-key.pem
```

***

## Primary Validator Setup

After creating the GitHub App:

1. Send the **Public Link** to the primary validator.
2. Ask them to install the application into the DAR repository.
3. Request the **Installation ID** from the primary validator.

The Installation ID is required when configuring the Helm chart.

***

### Install the Helm Chart

Deploy the service using Helm.

```bash theme={null}
helm upgrade --install \
  covalidation-service \
  -n some-namespace \
  -f values.yaml \
  oci://europe-docker.pkg.dev/da-images/public/charts/covalidation-service:0.7.4
```

***

### Configuration

A minimal configuration looks like the following.

```yaml theme={null}
covalidator:
  dars:
    github:
      appID: <GitHub App ID>
      installID: <GitHub Installation ID>

      privateKey:
        secretKeyRef:
          name: github-app-private-key
          key: private-key.pem

    repo:
      owner: <Primary validator GitHub organization>
      repo: <DAR repository>

  participant:
    id: <Participant ID>

    oidc:
      issuerUri: <Issuer URI>
      audience: <Audience>
      clientId: <Client ID>

      clientSecret:
        secretKeyRef:
          name: participant-oidc-secret
          key: client-secret

    endpoints:
      ledgerApi: participant.namespace:5001
      adminApi: participant.namespace:5002

  replication:
    participants:
      primary: <Primary participant ID>

      covalidators: []
  monitoring:
    otel:
      endpointURL: <OTEL Monitoring URL>
```

***

### Configuration Reference

#### GitHub

| Field                     | Description                                             |
| ------------------------- | ------------------------------------------------------- |
| `appID`                   | GitHub App ID                                           |
| `installID`               | Installation ID provided by the primary validator       |
| `privateKey.secretKeyRef` | Kubernetes Secret containing the GitHub App private key |

***

#### DAR Repository

| Field    | Description                                       |
| -------- | ------------------------------------------------- |
| `owner`  | GitHub organization containing the DAR repository |
| `repo`   | Repository name                                   |
| `branch` | Optional branch (defaults to `main`)              |
| `dir`    | Optional directory containing DAR files           |

***

#### Participant

| Field          | Description                                         |
| -------------- | --------------------------------------------------- |
| `id`           | Participant identifier                              |
| `issuerUri`    | OIDC issuer URI                                     |
| `audience`     | OIDC audience                                       |
| `clientId`     | OIDC client ID                                      |
| `clientSecret` | Kubernetes Secret containing the OIDC client secret |
| `ledgerApi`    | Ledger API endpoint                                 |
| `adminApi`     | Admin API endpoint                                  |

***

#### Replication

| Field          | Description                            |
| -------------- | -------------------------------------- |
| `primary`      | Primary validator participant ID       |
| `covalidators` | Additional covalidator participant IDs |

***

#### Monitoring

| Field         | Description                  |
| ------------- | ---------------------------- |
| `endpointURL` | OTEL monitoring URL and port |

***

#### Log

| Field    | Description                                   |
| -------- | --------------------------------------------- |
| `format` | Format of the logger (text, json, auto)       |
| `level`  | Level of logger (debug, info, warning, error) |

***

### Kubernetes Secrets

The chart expects existing Kubernetes Secrets.

### GitHub Private Key

```yaml theme={null}
privateKey:
  secretKeyRef:
    name: github-app-private-key
    key: private-key.pem
```

### Participant Client Secret

```yaml theme={null}
clientSecret:
  secretKeyRef:
    name: participant-oidc-secret
    key: client-secret
```

***

### Deployment Flow

```mermaid theme={null}
sequenceDiagram

participant GH as GitHub
participant Repo as DAR Repository
participant Service as Covalidation Service
participant Participant

Service->>GH: Authenticate using GitHub App
GH-->>Service: Installation Token
Service->>Repo: Read DARs
Repo-->>Service: DAR Files
Service->>Participant: Upload DARs
Participant-->>Service: Confirmation
```

## Uninstall

Remove the deployment with Helm.

```bash theme={null}
helm uninstall covalidation-service -n some-namespace
```

This removes the Kubernetes resources created by the chart but does not delete Kubernetes Secrets or the GitHub App.