> ## 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.

# Covalidating Partner Onboarding

> The onboarding process consists of the following steps

```mermaid theme={null}
flowchart TD
    A[Configure Your Validator Node]
    click A "covalidator-onboarding#1-configure-your-validator-node" " "
    B[Create GitHub App for Reading DAR Repository]
    click B "covalidator-onboarding#2-create-github-app-for-reading-dar-repository" " "
    C[Exchange Details and Configure and Install Your Covalidation Service]
    click C "covalidator-onboarding#3-exchange-details-and-configure-and-install-your-covalidation-service" " "

    A --> B
    B --> C
```

## 1. Configure your Validator Node

Create / configure the validator node which you will use as your covalidating node. If creating a new node, follow the [Canton Network Validator Onboarding Process](https://docs.canton.network/global-synchronizer/deployment/onboarding-process).

## 2. Create GitHub App for Reading DAR Repository

Before deploying the service, first a GitHub App must be created within your organization's GitHub account in order to access the shared DAR repository.

> **Important Note**
>
> Creating a GitHub App requires GitHub Organization Owner permissions.
>
> A single GitHub App can be reused for multiple Covalidation Service deployments within the same organization.

```mermaid theme={null}
flowchart TD

A[Create GitHub App in your organization] --> B[Share Your GitHub App Details with Primary Validator]
B --> C[Primary Validator installs GitHub App into Organization of DAR repository and Provides Installation ID]
```

The GitHub App setup process entails:

### Create a GitHub App in your organization

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 | Primary validator GitHub App |
| 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
```

***

### Share Your GitHub App Details with Primary Validator

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.

### Primary Validator installs GitHub App into Organization of DAR repository and Provides Installation ID

Once installed, the primary validator will provide you the **Installation ID**, which is required when configuring the Helm chart.

***

## 3. Exchange Details and Configure and Install Your Covalidation Service

* Gather details from the Primary Validator and Covalidating operator on DAR repository, GitHub App installation ID and participant IDs so that each co-validator can be configured correctly.
* Configure and Install the Covalidation Service Helm Chart

### Install the Covalidation Service Helm Chart

#### Setup

Before installing Covalidation Service, 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>

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.